Cropay开发者中心
为开发团队整理支付下单、签名、跳转、回调、状态查询、退款、测试与版本管理的接入路径。
Scope & readiness
业务与能力核验说明
具体服务地区、支付方式、结算周期与技术接入方案,均结合商户主体、业务场景与通道准入结果逐项确认。
开发者中心目前用于预上线审核。真实接口字段、地址、测试卡和错误码在完成资料脱敏与版本核对前不会公开,避免开发者依据过期或不完整文档实施。
文档信息架构
快速开始
说明申请测试商户、环境配置、签名准备和首笔测试交易。
支付接口
覆盖请求字段、金额币种、订单标识、支付页面和结果校验。
Webhook
说明签名验证、幂等、重试、响应要求和异常补偿。
退款与查询
记录退款申请、状态查询、错误处理和业务订单同步。
上线前技术检查
01 凭证安全
证书只保存在服务端,限制访问权限,不写入前端、日志或代码仓库。
02 订单一致性
金额、币种和订单号由服务端生成并签名,避免客户端篡改。
03 回调幂等
重复通知只能更新一次业务结果,未知状态使用查询接口核对。
04 全分支验收
覆盖成功、待处理、失败、异常、超时、重复通知与退款流程。
能力、证据与合规边界
接口正文待资料
在真实接口手册完成脱敏、版本核验和业务审核前,不展示伪造代码示例。
MD5 不替代传输安全
签名必须与 HTTPS、证书保护、访问控制和日志脱敏共同使用。
版本需可追溯
应按 gw_version 等字段记录版本,并维护兼容性和变更日志。
网关时序与状态机图谱
一次性支付、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
常见问题
如何申请测试环境?
联系技术支持申请测试商户号、测试地址和测试证书。
收到 T 状态可以发货吗?
不应。T 表示待处理,应等待签名有效的回调或主动查询获得最终结果。
回调最多会重试多少次?
现有业务资料写明最多重试 3 次,商户端仍需实现幂等和主动查询。