RamboPay

开发者接入

用一个 API 创建隐私化收款订单。

核心原则：支付通道只看到标准化付款摘要，完整商品名、SKU、用途和采购清单保留在商家自己的独立站系统。

API 能力总览

POST /api/v1/payments创建付款订单并返回 checkout_url
GET /api/v1/payments/:id查询付款状态、金额、币种和订单号
Webhook付款成功后签名通知商户系统
payment_descriptor控制支付通道看到的商品反馈信息

认证

商户完成邮箱验证和后台审核后，可以在后台生成 API Key。

Authorization: Bearer rp_test_xxx

接入后如何不暴露完整商品信息

不要把完整商品名、SKU、详细用途、采购清单写入 `title`。请使用 `payment_descriptor` 或 `title` 传递合法、简洁、标准化的付款摘要。真实订单明细保留在你自己的数据库，并用 `merchant_order_id` 做映射。

不建议

{
  "title": "500pcs exact SKU-A991 custom buyer catalog..."
}

建议

{
  "merchant_order_id": "B2B-20260723-8819",
  "payment_descriptor": "Merchant Invoice Payment",
  "metadata": {
    "private_order_ref": "stored_by_merchant"
  }
}

创建付款

POST /api/v1/payments
Content-Type: application/json

{
  "amount": "99.00",
  "currency": "USD",
  "merchant_order_id": "ORDER10001",
  "payment_descriptor": "Cross-border Ecommerce Order",
  "return_url": "https://merchant.example/success",
  "notify_url": "https://merchant.example/webhook",
  "metadata": {
    "private_note": "Full SKU remains in merchant system"
  }
}

返回结果包含 `checkout_url`，商家把买家跳转到这个链接完成付款。

{
  "id": "pay_xxx",
  "status": "pending",
  "checkout_url": "https://routermodels.com/checkout/pay_xxx"
}

查询付款

GET /api/v1/payments/pay_xxx
Authorization: Bearer rp_test_xxx

Webhook

付款成功后，平台会向商户 `notify_url` 发送签名回调。商户必须验签后再发货。

X-RamboPay-Timestamp: 1784780000
X-RamboPay-Signature: hex_hmac_sha256(timestamp + "." + raw_body)

上线检查清单

  • 商户邮箱已验证，后台审核通过。
  • 默认 public descriptor 已配置，不包含完整商品名和 SKU。
  • notify_url 可访问，并完成 Webhook 签名校验。
  • 商家系统可通过 merchant_order_id 找回真实订单。
  • 发货/开通服务逻辑具备幂等处理。