可集成的国际支付网关与API
围绕 Hosted、Embedded 与 API 接入,说明订单签名、支付状态、异步回调、退款查询和上线验证。
Scope & readiness
业务与能力核验说明
具体服务地区、支付方式、结算周期与技术接入方案,均结合商户主体、业务场景与通道准入结果逐项确认。
Capability definition
能力定义与适用范围
网关接入的重点不是“接口能调通”,而是商户系统能在重复通知、网络超时、待处理、失败和异常状态下保持订单一致,并向用户给出准确反馈。
Use cases
适用业务场景
- Hosted 跳转支付
- Embedded 内嵌支付
- 统一 API
- 退款与查询
Transaction types
交易类型边界
- 用户主动确认的一次性交易
- 退款、取消与状态查询(以具体能力为准)
- 不包含自动循环扣款或订阅管理
Integration modes
接入模式
Hosted
适合希望由网关承载支付页面的场景。
Embedded
适合需要站内体验并能承担相应安全实施的场景。
API
适合服务端订单、查询、退款和回调集成。
Process steps
接入与处理流程
- 01
01 申请测试资料
联系技术支持获取测试商户号、测试地址和交易证书。
- 02
02 完成签名与下单
按字段顺序和版本要求生成签名,避免金额、币种和订单号被篡改。
- 03
03 接入回调与查询
回调处理必须幂等;对 T 或未知结果使用查询接口最终确认。
- 04
04 覆盖异常测试
测试成功、失败、待处理、超时、重复回调、退款和网络中断。
核验支持范围与限制边界
已核验支持范围
认证机制:商户号与交易证书生成 MD5 签名,需按接口规范实现 结果状态:Y 成功、T 待处理、N 失败、E 异常 异步通知:支付完成后主动回传,最多重试 3 次
限制与边界
必须按现有接口规范使用,同时通过 TLS、证书保管、访问控制和日志脱敏保护链路。 浏览器跳转结果不能单独作为发货依据,应结合服务端回调或主动查询。 真实接口字段、错误码和版本变更记录应在资料核验后进入开发者中心。
网关时序与状态机图谱
一次性支付、3DS2 验证与签名回调时序架构图
技术选型对比矩阵
Hosted、Embedded 与 Server API 接入模式对比表
Cropay 三种支付网关接入模式在 PCI DSS 合规边界、3DS2 处理与适用场景上的结构化对比。
| 接入模式 | PCI DSS 合规范围 | 结账交互控制度 | 3DS2 与异步通知机制 | 推荐适用场景 |
|---|---|---|---|---|
| Hosted 跳转收银台 | 最低(由网关承载卡信息输入与加密) | 跳转至网关托管的多语言响应式收银台 | 网关自动编排 3DS2 挑战跳转,服务端验签 Webhook 发货 | 希望快速上线、降低安全合规成本的交友与直播 Web/H5 平台 |
| Embedded 内嵌组件 | 中等(需通过域名白名单与安全边界复核) | 在站内购买弹层或充值页内嵌支付步骤 | 组件内完成 3DS2 验证跳转,配合服务端异步通知更新账本 | 注重直播间内不中断观看体验的金币充值与单次解锁场景 |
| Server API 服务端集成 | 高(若直接接触卡号需具备对应 PCI 资质) | 由商户后端完全编排订单创建、查询与退款生命周期 | 幂等下单接口 + HMAC/RSA 签名回调 + 主动状态查询兜底 | 高并发虚拟钱包账本、自动化退款同步与财务批次对账系统 |
接口报文与签名验签规范示例
一次性支付会话创建与 Webhook 签名校验参考模式
以下展示标准的一次性订单幂等创建与服务端 Webhook 签名核验结构。通过业务初审后将发放对应通道的沙盒密钥与完整接口文档。
1. POST /v1/payment-sessions (Server-to-Server)
REST JSON{
"merchantOrderId": "ord_20261026_98231",
"idempotencyKey": "idem_7f83b165-4a2b-4c9e",
"amount": "29.99",
"currency": "USD",
"captureMethod": "automatic",
"transactionModel": "one_time_user_initiated",
"threeDSecure": { "mode": "dynamic_step_up" },
"productContext": {
"itemCode": "coin_pack_300",
"itemDescription": "300 Virtual Coins (One-Time Purchase)"
},
"returnUrl": "https://merchant.example.com/checkout/return",
"webhookUrl": "https://merchant.example.com/api/webhooks/cropay"
}2. Signed Asynchronous Webhook Event (payment.succeeded)
200 OK// Header: X-Cropay-Signature: t=1761472800,v1=hmac_sha256(secret, t + "." + rawBody)
{
"eventId": "evt_01J9Z8K4M2P5X",
"eventType": "payment.succeeded",
"gatewayTransactionId": "txn_cp_88492019",
"merchantOrderId": "ord_20261026_98231",
"amount": "29.99",
"currency": "USD",
"threeDSecureResult": {
"version": "2.2.0",
"authenticated": true,
"flow": "frictionless"
},
"capturedAt": "2026-10-26T09:00:00Z"
}FAQ
常见问题
支付成功后应以哪个结果为准?
商户应以服务端签名校验通过的异步通知或主动查询结果为准,不只依赖浏览器跳转。
为什么回调要做幂等?
网关可能为确保送达而重复通知,商户必须避免重复发货、重复记账或重复更新。
如何获得测试环境?
需联系技术支持申请测试商户号、测试地址和测试证书。