CroPay 国际信用卡收款cropay.com
Developer Center · 技术文档中心

Cropay开发者中心

为开发团队整理支付下单、签名、跳转、回调、状态查询、退款、测试与版本管理的接入路径。

Scope & readiness

业务与能力核验说明

具体服务地区、支付方式、结算周期与技术接入方案,均结合商户主体、业务场景与通道准入结果逐项确认。

开发者中心仅限一次性主动交易评估

开发者中心目前用于预上线审核。真实接口字段、地址、测试卡和错误码在完成资料脱敏与版本核对前不会公开,避免开发者依据过期或不完整文档实施。

文档信息架构

快速开始

说明申请测试商户、环境配置、签名准备和首笔测试交易。

支付接口

覆盖请求字段、金额币种、订单标识、支付页面和结果校验。

Webhook

说明签名验证、幂等、重试、响应要求和异常补偿。

退款与查询

记录退款申请、状态查询、错误处理和业务订单同步。

上线前技术检查

01 凭证安全

证书只保存在服务端,限制访问权限,不写入前端、日志或代码仓库。

02 订单一致性

金额、币种和订单号由服务端生成并签名,避免客户端篡改。

03 回调幂等

重复通知只能更新一次业务结果,未知状态使用查询接口核对。

04 全分支验收

覆盖成功、待处理、失败、异常、超时、重复通知与退款流程。

能力、证据与合规边界

接口正文待资料

在真实接口手册完成脱敏、版本核验和业务审核前,不展示伪造代码示例。

MD5 不替代传输安全

签名必须与 HTTPS、证书保护、访问控制和日志脱敏共同使用。

版本需可追溯

应按 gw_version 等字段记录版本,并维护兼容性和变更日志。

网关时序与状态机图谱

一次性支付、3DS2 验证与签名回调时序架构图

Cropay 国际支付网关一次性结账、3D Secure 2 验证与签名 Webhook 回调时序图
图 1:端到端交易状态机时序图——覆盖持卡人确认、商户服务端下单、3DS2 强验证及签名 Webhook 幂等履约。

技术选型对比矩阵

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 次,商户端仍需实现幂等和主动查询。

Business assessment

开始测试接入

提交公司主体、业务网址或 App、目标地区、收费项目、交易模式和预计接入方式,先审核适用性,再确认能力与技术路径。

提交接入评估