巴西&墨西哥对接文档

Owner: A Alex Tags: Guides and Processes 更新时间：2026-05-10

商户支付对接文档

本文档仅说明商户通过 API Key 接入支付网关时需要使用的接口与回调规范，覆盖创建订单、查询订单、关闭订单和异步通知。

💡 对接建议

• 创建订单成功后请保存 payment_id，后续详情查询、关闭、取消都使用该字段
• 验签时务必使用原始请求体，避免因 JSON 重排导致签名不一致
• 若接入环境配置了 IP 白名单，请确认商户服务出口 IP 已提前登记
• 联调通过沙盒进行
• 注意金额为分，举个栗子：100分=1元，10分=0.1元

1. 基础信息

Base URL

https://api.x2pay.eu.org

鉴权请求头（必填）

• X-API-Key：平台分配的应用 API Key
• X-Signature：请求签名，HMAC-SHA256 小写十六进制
• X-Timestamp：Unix 时间戳，支持秒或毫秒
• X-Nonce：一次性随机串，建议长度不少于 16

可选请求头

• X-Request-ID：商户请求流水号，便于排查问题

签名算法

1. 收集参与签名的参数
2. 按参数名升序排序
3. 拼接为 key1=value1&key2=value2...
4. signature = hex(hmac_sha256(api_secret, canonical_string))

参与签名的字段

• 所有 URL Query 参数
• 固定字段：
  • api_key：请求头 X-API-Key
  • timestamp：请求头 X-Timestamp
  • nonce：请求头 X-Nonce
  • method：大写 HTTP 方法，如 POST、GET、PUT
  • path：请求路径，不含域名，如 /api/v1/payin
• 当请求方法为 POST 或 PUT 时，额外加入：
  • content_type：请求的 Content-Type，例如 application/json
• 当请求体非空时，额外加入：
  • body_sha256：原始请求体的 SHA256 小写十六进制

拼接规则

• 所有参与字段按参数名升序排序
• 空值字段不参与拼接
• 使用 key=value 形式拼接，并以 & 连接

签名示例：创建收款订单

请求：

• POST /api/v1/payin
• Content-Type: application/json

若请求头和请求体如下：

• X-API-Key = {api_key}
• X-Timestamp = 1710000000000
• X-Nonce = abcdef1234567890
• body = {"app_id":"app_456","merchant_tx_id":"order_789","amount":10000,"currency":"BRL","subject":"商品购买"}

则先计算：

body_sha256 = sha256(body)

参与签名的参数排序后拼接为：

api_key={api_key}&body_sha256={body_sha256}&content_type=application/json&method=POST&nonce=abcdef1234567890&path=/api/v1/payin&timestamp=1710000000000

最终签名：

signature = hex(hmac_sha256(api_secret, canonical_string))

签名示例：查询支付订单

请求：

• GET /api/v1/payments/pay_abc123

若无 Query 参数，则参与签名的参数排序后拼接为：

api_key={api_key}&method=GET&nonce=abcdef1234567890&path=/api/v1/payments/pay_abc123&timestamp=1710000000000

若 URL 上带 Query 参数，则 Query 参数也需要一并加入后再排序拼接。

时效与防重放

• X-Timestamp 与服务器时间允许偏差为 ±5 分钟
• 同一 X-API-Key 下，X-Nonce 不可重复使用

2. 响应结构

成功响应：

{
  "code": "0",
  "message": "success",
  "request_id": "req_123456",
  "data": {}
}

失败响应：

{
  "code": "1001",
  "message": "无效的请求",
  "request_id": "req_123456",
  "data": "..."
}

说明：

• 成功时返回 HTTP 200
• 失败时会返回对应的 HTTP 错误状态（如 400、401、403、404、429、500），并在响应体中携带业务错误码

常见错误码

• 1001 无效请求
• 1002 未授权
• 1003 禁止访问
• 1004 资源不存在
• 1005 超过限流
• 1006 签名无效
• 1007 时间戳过期
• 1008 IP 不在白名单
• 2002 重复订单（同一 merchant_tx_id 提交了不同金额）
• 2007 无效状态
• 5001 内部错误

订单状态

• PENDING
• PROCESSING
• SUCCESS
• FAILED
• CANCELLED
• CLOSED
• REFUNDED

时间字段统一使用 RFC3339，例如 2026-03-03T12:00:00Z。

3. 创建收款订单

POST /api/v1/payin

请求体

墨西哥专用：创建收款订单

以下字段仅在接入墨西哥渠道时使用；其它国家或渠道无需传入。

墨西哥 VA/SPEI 收款示例：

{
  "app_id": "app_456",
  "merchant_tx_id": "mx_order_001",
  "amount": 10000,
  "currency": "MXN",
  "payment_method": "va",
  "notify_url": "https://merchant.example.com/payments/notify",
  "return_url": "https://merchant.example.com/payments/return",
  "subject": "Mexico VA order",
  "account_name": "Juan Perez",
  "extra": "{\"email\":\"juan@example.com\",\"phone\":\"+525512345678\"}"
}

墨西哥专用说明：

• amount 仍使用最小货币单位。例如 10000 表示 100.00 MXN。
• extra 是 JSON 字符串；请确保转义后仍是合法 JSON。
• 普通 VA/SPEI 接入只需要传 payment_method。extra.payment_type 是渠道侧覆盖项，不需要和 payment_method 同时配置。
• 若使用墨西哥 VA，用户实际还款金额和次数可能与订单期望金额不同，详见本文 Webhook 章节的“墨西哥 VA 多次回款”说明。

幂等规则

• 同一 app_id + merchant_tx_id 重复提交，且金额相同：返回首次创建的订单
• 同一 app_id + merchant_tx_id 重复提交，但金额不同：返回 2002

响应 data

示例

curl -X POST "https://{HOST}/api/v1/payin" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: {api_key}" \
  -H "X-Signature: {signature}" \
  -H "X-Timestamp: {timestamp}" \
  -H "X-Nonce: {nonce}" \
  -d '{
    "app_id": "app_456",
    "merchant_tx_id": "order_789",
    "amount": 10000,
    "currency": "BRL",
    "subject": "商品购买"
  }'

收银台链接

如需收银台页面（适用于 H5/网页支付），可在创建订单成功后调用创建收银会话接口获取链接。

POST /api/v1/cashier/sessions

请求体

响应 data

错误码说明

• 1001 无效请求（参数缺失或格式错误）
• 1002 未授权（签名或 API Key 错误）
• 1004 资源不存在（payment_id/merchant_tx_id 未找到）
• 2007 无效状态（订单状态不允许创建收银会话）

常见错误

• invalid return url：return_url 不在白名单
• payment not found：订单不存在或不属于当前商户

示例

curl -X POST "https://{HOST}/api/v1/cashier/sessions" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: {api_key}" \
  -H "X-Signature: {signature}" \
  -H "X-Timestamp: {timestamp}" \
  -H "X-Nonce: {nonce}" \
  -d '{
    "app_id": "app_456",
    "payment_id": "pay_abc123",
    "return_url": "https://merchant.example.com/return"
  }'

4. 创建付款订单

POST /api/v1/payout

app_id,merchant_tx_id,amount,currency基础字段外，付款订单还需要收款账户信息。

补充请求字段

对照关系（0-CPF，1-CNPJ，2-EMAIL，3-PHONE，4-EVP）

其余规则与“创建收款订单”一致，响应中的 transaction_type 固定为 PAY_OUT。

墨西哥专用：创建付款订单

以下字段仅在接入墨西哥渠道时使用；其它国家或渠道无需按此解释。

墨西哥代付银行信息说明：

• account_bank 必须传银行编码，不是银行简称。商户应使用平台提供的墨西哥银行编码表。
• CLABE 前 3 位通常需要与银行编码后 3 位匹配。例如 BBVA MEXICO 银行编码 40012，CLABE 示例以 012 开头。

墨西哥代付示例：

{
  "app_id": "app_456",
  "merchant_tx_id": "mx_payout_001",
  "amount": 2500,
  "currency": "MXN",
  "payment_method": "spei",
  "notify_url": "https://merchant.example.com/payouts/notify",
  "subject": "Mexico payout",
  "account_bank": "40012",
  "account_name": "JUAN PEREZ",
  "account_type": "CLABE",
  "account_number": "012345678901234567",
  "extra": "{\"bank_name\":\"BBVA MEXICO\",\"id_card_number\":\"GAPG00000000000000\"}"
}

5. 查询支付订单列表

GET /api/v1/payments

当前 API Key 仅能查询自身应用下的订单。

常用查询参数

响应 data

订单明细会返回当前商户可见字段；部分敏感字段可能按规则脱敏。

6. 查询支付订单详情

GET /api/v1/payments/{payment_id}

路径参数

返回当前商户可见的订单详情。若商户仅持有 merchant_tx_id，可先通过列表接口按 merchant_tx_id 过滤后获取对应 payment_id。

7. 查询应用余额

GET /api/v1/balance

该接口用于查询当前 API Key 所属应用的余额信息。默认读取认证上下文中的 app_id；如传 app_id 查询参数，必须与认证应用一致。

查询参数

响应 data

示例

curl -X GET "https://{HOST}/api/v1/balance?app_id=app_456" \
  -H "X-API-Key: {api_key}" \
  -H "X-Signature: {signature}" \
  -H "X-Timestamp: {timestamp}" \
  -H "X-Nonce: {nonce}"

8. Webhook 通知

当订单状态变化时，系统会向订单的 notify_url 发送 POST 请求。

请求头

• Content-Type: application/json
• X-Signature：通知签名
• X-Event-Type：事件类型
• X-Notification-ID：通知唯一标识
• X-Timestamp：发送时间（Unix 秒级时间戳）

请求体示例

{
  "event_type": "PAYMENT_SUCCESS",
  "payment_id": "pay_123456",
  "merchant_id": "merchant_001",
  "app_id": "app_001",
  "merchant_tx_id": "order_123",
  "amount": 10000,
  "currency": "BRL",
  "status": "SUCCESS",
  "end_to_end": "ch_789",
  "qrCode": "000201010212...",
  "errorCode": "",
  "account": {
    "bank": "001",
    "name": "Maria Silva",
    "number": "1234567890",
    "accountType": "CACC"
  },
  "extra": {
    "user_id": "123"
  },
  "timestamp": 1772491200
}

验签方式

signature = hex(hmac_sha256(api_secret, raw_body))

• raw_body 为通知请求的原始 JSON 字节
• api_secret 为应用 API Secret（与请求签名使用同一密钥）
• 以请求头 X-Signature 为准

回调响应要求

• 商户处理成功后请返回 2xx
• 返回非 2xx 时，系统会按重试策略继续发送

墨西哥专用：VA 多次回款

墨西哥 VA 收款与普通一次性收款不同：当用户通过 VA 还款时，实际还款金额和还款次数由用户决定，可能出现以下情况：

• 单次回款金额小于订单期望金额
• 单次回款金额大于订单期望金额
• 同一商户订单发生多次回款

平台会根据累计回款结果更新订单状态。商户只需要按平台 Webhook 通知处理自身业务状态，并确保回调处理幂等。

商户处理建议：

• 商户收到的 Webhook 仍是平台订单状态通知；通知中的 amount 为原订单金额，不代表墨西哥 VA 的某一笔实际回款金额。
• 不要假设用户只会还款一次，也不要假设实际累计回款一定等于原订单金额。
• 若业务需要精确核对 VA 多次回款，请以商户订单号 merchant_tx_id 归集，并结合平台对账数据核对每笔回款。
• 商户回调接口必须幂等；同一通知重试时不应重复发货、重复记账或重复变更业务状态。
• 订单累计回款未达到期望金额前，平台订单可能仍保持处理中状态；累计达到或超过期望金额后，平台会将主订单推进到成功状态。