如何在 BlueSnap Payment API 中自定义交易 ID？

2026-10-24支付阿杰

明确结论

商户可以传入自己的交易编号，但不能替换 BlueSnap 生成的交易 ID。

创建交易时，只需将自定义编号写入 merchantTransactionId 字段。交易成功后，BlueSnap 仍会生成自己的交易 ID。建议同时保存这两个编号，便于后续对账、查询和排查问题。

设置方法

通过 Payment API 创建交易时，在请求体中加入 merchantTransactionId：

{
  "amount": 49.99,
  "currency": "USD",
  "merchantTransactionId": "ORDER-20260910-0001",
  "cardHolderInfo": {
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "creditCard": {
    "cardNumber": "4111111111111111",
    "expirationMonth": "12",
    "expirationYear": "2030",
    "securityCode": "123"
  }
}

示例请求：

curl -X POST \
  'https://sandbox.bluesnap.com/services/2/transactions' \
  -u 'API_USERNAME:API_PASSWORD' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "amount": 49.99,
    "currency": "USD",
    "merchantTransactionId": "ORDER-20260910-0001",
    "cardHolderInfo": {
      "firstName": "Jane",
      "lastName": "Doe"
    },
    "creditCard": {
      "cardNumber": "4111111111111111",
      "expirationMonth": "12",
      "expirationYear": "2030",
      "securityCode": "123"
    }
  }'

实际接入时，还需根据所用的支付方式补充相应字段，如卡片信息、支付来源或 vaulted shopper 信息。

两类交易 ID 的区别

merchantTransactionId：由商户提供，通常填写订单号、支付流水号或内部业务编号。
BlueSnap transaction ID：由 BlueSnap 创建，用于标识其平台中的交易，商户无法指定。

建议在数据库中分别保存：

order_id: ORDER-20260910-0001
merchant_transaction_id: ORDER-20260910-0001
bluesnap_transaction_id: BlueSnap 返回的交易 ID

注意事项

merchantTransactionId 主要用于关联业务和对账。它不会取代 BlueSnap transaction ID，因此不要只依赖该字段执行退款、撤销或交易查询。

不同类型的 Payment API 请求对字段的支持范围可能不同。正式上线前，请以当前 BlueSnap API 文档中对应交易接口的请求结构为准，并确认 merchantTransactionId 的长度限制、字符限制和唯一性要求。为避免网络重试造成重复扣款，应使用 BlueSnap 当前支持的幂等或重复交易防护机制，不要将 merchantTransactionId 当作幂等键。