发卡 API：虚拟卡开卡、充值、冻结和交易查询

开发者中心资源

通过审核的合作方可以在应用内开发者中心查看 App ID、API Key 状态、Webhook 配置、事件投递历史、生产开通状态和 Postman 接入资源。登录后可进入 /issuing-api 查看实时工作区。

• App ID 与脱敏 API Key 状态
• Base URL 与授权范围
• Webhook URL 草稿与审核状态
• 卡片与交易事件投递历史
• 卡产品、钱包扣款与管理后台审核入口

核心接口能力

接口围绕卡产品、卡生命周期、平台 USD 余额充值卡片和交易查询组织。

• GET /products - 查询卡产品、BIN、国家地区、币种、费用、最低充值和可用状态
• POST /cards - 使用 Idempotency-Key 创建虚拟卡
• GET /cards 与 GET /cards/{cardId} - 查询卡列表和卡片详情
• POST /cards/{cardId}/topup - 从平台 USD 余额扣款并给卡充值
• POST /cards/{cardId}/freeze、/unfreeze、/close - 冻结、解冻和销卡
• GET /cards/{cardId}/transactions - 查询授权、清算、退款、拒付和手续费记录

curl -X POST https://openrambo.com/api/issuing/v1/cards
  -H "X-API-Key: or_live_xxxxxxxxx"
  -H "Idempotency-Key: order_20260724_0001"
  -H "Content-Type: application/json"

Webhook 事件与对账

不要只凭接口响应就认为操作完成。生产系统必须同时核对 API 响应、平台 USD 钱包流水和 Webhook 事件。每个事件都应校验签名、落库，并按事件 ID 去重。

• card.created - 开卡成功或失败
• card.topup.posted - 卡充值入账
• card.status.changed - 冻结、解冻、销卡或风控状态变化
• transaction.authorized - 商户授权产生
• transaction.settled - 清算完成
• transaction.refunded - 退款入账
• chargeback.created - 拒付或争议通知

生产错误处理

生产接入必须区分认证、权限、幂等冲突、参数校验、限流和上游故障。502 只能使用有限退避重试，并且必须复用同一个幂等键。

• 401 Unauthorized - API Key 缺失或无效
• 403 Forbidden - 权限范围不足或账户未通过审核
• 409 Conflict - 同一个幂等键用于不同请求内容
• 422 Validation error - 请求参数需要修正后再提交
• 429 Rate limited - 触发限流，需要等待后重试
• 500 或 502 Upstream error - 可安全重试，但必须先对账再展示最终状态

继续深入阅读