使用 Token 化支付方式发起扣款

顾客不在场的情况下，使用已保存的支付方式进行扣款。请仅从后端服务器，且使用已列入白名单的 IP 地址调用此端点。

Headers 标头

标头	是否必须	介绍
Content-Type	yes	application/json; charset=UTF-8
X-API-Key	yes	与 Init v2 的值相同apiKey。仅标识符，不包含 JWT HMAC 密钥。
Authorization	yes	Bearer <JWT>（HS256）。参见认证。
Idempotency-Key	yes	请求的唯一标识符，以避免重复收费

强烈建议实现 Idempotency-Key（幂等键），以确保您的订单不会被意外重复扣款。

1. 每次逻辑扣款尝试请发送唯一的 Idempotency-Key（推荐使用 UUID）。

2. 遇到超时时，请务必使用相同的 key 仅重试完全相同的请求体（包含金额、payment_method_id、订单标识符等）。

3. 请在 24 小时期限内停止使用同一个 key 进行重试。TTL（生存时间）过期后，平台可能会将该请求视为全新的扣款请求。

请求参数

值	类型	是否必须	介绍
country	number	yes	数字国家代码。必须与 JWT 匹配country。
currency	number	yes	数字货币代码。必须与 JWT 匹配currency。
payType	number	yes	卡片通道 ID。必须与 JWT 匹配payType。
projectId	number	yes	与 Init 项目相同。必须匹配 JWT projectId。
orderId	string	yes	您此次消费的唯一订单 ID 。必须与 JWT 匹配orderId。
offSessionType	string	yes	与保存卡片的 CIT 协议类型相同。可以是以下之一Unscheduled：Subscriptions，，Installments。必须与 JWT 匹配offSessionType。
items	array	yes	非空。每个项目：code，，price。name必须与 JWTitems完全匹配。
paymentMethodId	string	yes	来自 PAYMENT_METHOD_ADDED 回调（paymentMethod.id）或支付成功通知参数 PaymentMethodId 中已保存的 ID。

Coda 会从拥有此支付方式的购物者处获取税务管辖权信息。

示例令牌付费请求体

{
  "country": 360,
  "currency": 360,
  "payType": 1005,
  "projectId": 1,
  "orderId": "1773302739024703",
  "offSessionType": "Unscheduled",
  "items": [
    {
      "code": "0a141558-3c61-45d0-b299-c867ec023543",
      "price": 1000,
      "name": "Monthly subscription"
    }
  ],
  "paymentMethodId": "pmt_sg1a9999ac56ae00000"
}

使用与成功的 CIT-for-MIT 保存流程中绑定的已分配 paymentMethodId 相关的 offSessionType。

即时响应回复

值	类型	介绍
txnId	number	Coda 交易 ID。0如果请求在创建费用之前被拒绝。
resultCode	integer	431= 已接受，正在处理。0= 成功（此路径上很少见）。其他值 = 错误。
resultDesc	string	错误时的英文消息。null当费用被接受处理时（431）。

已接受（处理中​​）：

{
  "resultCode": 431,
  "resultDesc": null,
  "txnId": 7883459825339273000
}

请勿视为431已付款。请等待完整通知或问询。

被拒绝的示例：

{
  "resultCode": 103,
  "resultDesc": "This transaction has been cancelled. No charges were made. (error:103).",
  "txnId": 0
}

---

身份验证（令牌支付）

Token Charge 端点使用两个凭证：

Credential 身份验证	Role 角色
X-API-Key	与 Init Payment API 相同的字符串/键apiKey。
HMAC signing secret	Coda 会单独提供一个密钥，用于带外传输。该密钥仅用于签署 JWT。切勿将其放入X-API-KeyJSON 正文、日志或 Git 中。

Coda 没有颁发 JWT 的端点。您的服务器会针对每个请求构建并签名 JWT。

JWT 标头

{ "alg": "HS256", "typ": "JWT" }

算法仅支持HS256。其他算法均不接受。

JWT 声明

exp - iat必须≤300秒。Coda允许约30秒的时钟偏差。所有列出的声明都是必需的。签名验证后，每个声明必须与JSON正文完全匹配（类型相同）。不匹配→返回resultCode 103错误。

声明	类型	规则
iat	number	Unix 秒 UTC。必须小于等于当前时间（存在偏差）。
exp	number	Unix 秒（UTC）。必须大于当前时间，exp - iat且小于等于 300。
orderId	string	匹配主体orderId。
projectId	number	匹配主体projectId。用于country解析商家。
country	number	匹配主体country。
currency	number	匹配主体currency。
payType	number	匹配主体payType。
offSessionType	string	匹配主体offSessionType。
items	array of {code, price, name}	长度和字段与正文相同items。此操作用于绑定金额。
paymentMethodId	string	匹配主体paymentMethodId。

请勿在 JWT 中包含iss, jti, kid, apiKey, userInitiated, shopper, profile, 或paymentMethods。此端点仅限 MIT 权限；Coda 会在内部设置 customer-absent。

{
  "iat": 1787126400,
  "exp": 1787126700,
  "orderId": "1773302739024703",
  "projectId": 1,
  "country": 360,
  "currency": 360,
  "payType": 1005,
  "offSessionType": "Unscheduled",
  "items": [
    {
      "code": "0a141558-3c61-45d0-b299-c867ec023543",
      "price": 1000,
      "name": "Monthly subscription"
    }
  ],
  "paymentMethodId": "pmt_sg1a9999ac56ae00000"
}

符号（节点式草图）

const jwt = require('jsonwebtoken');
const secret = process.env.CODA_TOKEN_CHARGE_HMAC; // not the API key
const now = Math.floor(Date.now() / 1000);
const token = jwt.sign(
  {
    orderId: '1773302739024703',
    projectId: 1,
    country: 360,
    currency: 360,
    payType: 1005,
    offSessionType: 'Unscheduled',
    items: [{
      code: '0a141558-3c61-45d0-b299-c867ec023543',
      price: 1000,
      name: 'Monthly subscription'
    }],
    paymentMethodId: 'pm_1234567890000',
    iat: now,
    exp: now + 300
  },
  secret,
  { algorithm: 'HS256' }
);

---

IP地址白名单（令牌支付）

Coda 只接受来自您提供给您的帐户管理员的IPv4 地址或 CIDR 范围的令牌充值（调用 API 的服务器的 NAT / 负载均衡器出口- 除非是故意用于沙箱，否则不接受开发人员笔记本电脑）。

规则	细节
谁发送IP地址	你，在正式上线之前
格式	准确的 IPv4 地址和/或 CIDR 地址（例如203.0.113.10，198.51.100.0/24）
如果缺失或 IP 地址未列出	令牌收费被拒绝

当您的出口 IP 地址发生变化时，请在切换之前通知 Coda。