DEEPayment Merchant API
DEEPayment Merchant API 提供统一的代收、代付、订阅、查询、余额和代付凭证接口。所有请求使用 HTTPS + JSON。业务接口使用商户 Ed25519 密钥签名（RFC 9421），POST body 使用 X25519 sealed box 加密，两者都由平台 SDK 完成。
建议按“生成密钥 → 配置 SDK → 创建订单 → 处理 webhook → 查询兜底”的顺序接入。字段细节在 API Reference 中查询。
文档导航
快速开始
接入前置条件、Base URL、下单示例、成功和失败响应。
鉴权机制
Ed25519 签名、Signature-Input、Content-Digest、sealed box body 加密和 GET/POST 规则。
订阅快速开始
Plan、托管 Checkout、状态确认、账单查询、取消和异常恢复。
webhook
代收和代付最终状态回调、签名校验、事件字段和幂等处理。
Subscription Events
独立签名、事件字段、重复通知、乱序处理和查询兜底。
API Reference
按代收、代付、国家和支付方式进入完整接口文档。
Postman Collection
导入代收、代付、查询、余额和凭证请求示例。签名和 body 加密需要通过 SDK 完成。
API 一览
创建代收订单
按国家和支付方式进入独立文档，每个 method 页面都包含完整请求、响应和 webhook 示例。
/paymentsPOST创建代付订单
按国家和出款方式进入独立文档，每个 method 页面都完整说明字段和错误处理。
/payoutsGET查询代收订单
用平台订单号或商户订单号确认代收最终状态。
/payments?orderNo=...POST创建和管理订阅
创建 Plan 和托管 Checkout Session，确认 Subscription 状态，并查询 Invoice 和 Payment Order。
/subscription/**GET查询代付订单
代付创建超时、回调延迟或状态冲突时，用查询结果兜底。
/payouts?merchantOrderNo=...GET查询余额
按币种查看商户可用余额。
/balances?currency=BRLGET查询代付凭证
获取代付凭证详情，用于出款后对账或客诉处理。
/payouts/{orderNo}/receipt接入主线
- 准备商户密钥
生产请求发送至
https://panama.deepayment.com/api/v1。开户后获取Access Key和平台公钥，上传商户 Ed25519 公钥，每个环境的密钥独立保存。 - 选择业务接入主线
单次订单使用代收与代付快速开始；持续扣款使用订阅快速开始和托管 Checkout。
- 用 SDK 签名和加密
用商户 Ed25519 私钥对 RFC 9421 签名基串签名，并用平台 X25519 公钥加密
POSTbody。SDK 会自动完成。 - 创建代收或代付订单
用
merchantOrderNo做商户侧幂等键，并按 method code 传入对应的 lowerCamelCase 分支字段。 - 处理 webhook 与查询兜底
验签后保存终态事件。回调延迟、重复、超时或 5xx 时，用查询接口确认最终状态。
Method 结构
创建订单统一使用 merchantOrderNo、currency、amount、webhookUrl。method 使用 code + lowerCamelCase 分支字段：
{
"paymentMethod": {
"code": "PIX",
"pix": {
"payerCPF": "12345678901",
"payerName": "Joao Silva"
}
}
}
code 使用大写枚举值；分支字段使用 lowerCamelCase，例如 PIX -> pix、PSE -> pse、BANK_TRANSFER -> bankTransfer。每个 method 的字段和必填规则见附录。