Submit Charge with Tokenized Payment Method

Charge a saved payment method with the customer absent. Call this endpoint only from your backend, from an allowlisted IP.

Pre-requisite

When integrating with Codapay APIs, ensure you adhere to the following standards:

1. Use HTTPS protocol.

2. TLS 1.2 or higher

Environment	Base URL
Sandbox	https://sandbox.codapayments.com/airtime
Production	https://airtime.codapayments.com/airtime

Endpoint

POST {Base URL}/v1/payment/token/charge

Headers

Header	Required	Description
Content-Type	yes	application/json; charset=UTF-8
X-API-Key	yes	Same value as Init v2 apiKey. Identifier only — not the JWT HMAC secret.
Authorization	yes	Bearer <JWT> (HS256). See Authentication.
Idempotency-Key	optional	Unique identifier of the request to avoid duplicate charges.

Idempotency-Key implementation is strongly recommended to ensure your order doesn't get charged twice unintentionally.

1. Send a unique Idempotency-Key per logical charge attempt (UUID recommended).

2. Retry only the same request body (amount, payment_method_id, order identifiers, etc.) with the same key after timeouts.

3. Stop retrying the same key before the 24-hour boundary. After TTL expiry, the platform may treat the request as a new charge.

Request parameters

Field	Type	Required	Description
country	number	yes	Numeric country code. Must match JWT country.
currency	number	yes	Numeric currency code. Must match JWT currency.
payType	number	yes	Payment Channel Id. Must match JWT payType.
projectId	number	yes	Same project as Init. Must match JWT projectId.
orderId	string	yes	Your unique order id for this charge. Must match JWT orderId.
offSessionType	string	yes	Same agreement type as the CIT that saved the card. One of Unscheduled, Subscriptions, Installments. Must match JWT offSessionType.
items	array	yes	Non-empty. Each item: code, price, name. Must match JWT items exactly.
paymentMethodId	string	yes	Saved payment method id from PAYMENT_METHOD_ADDED Event (paymentMethod.id) or from the query parameter PaymentMethodId of Successful Payment notification

Coda loads tax jurisdiction from the shopper who owns this payment method.

Sample Token Charge body

{
  "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"
}

Use offSessionType that binded with assigned paymentMethodId from a successful CIT-for-MIT save.

Immediate response

Field	Type	Description
txnId	number	Coda transaction id. 0 if the request was rejected before a charge was created.
resultCode	integer	431 = accepted, processing. 0 = success (rare on this path). Other values = error.
resultDesc	string	English message on error. null when the charge is accepted for processing (431).

Accepted (processing):

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

Do not treat 431 as paid. Wait for the complete notification or Inquiry.

Rejected example:

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

---

Authentication (Token Charge)

Token Charge endpoint uses two credentials:

Credential	Role
X-API-Key	Same string / key as Init Payment API apiKey.
HMAC signing secret	Separate secret Coda gives you out of band. Used only to sign the JWT. Never put it in X-API-Key, the JSON body, logs, or git.

There is no Coda endpoint that issues the JWT. Your server builds and signs it per request.

JWT header

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

Algorithm is HS256 only. Other algorithms are rejected.

JWT claims

exp - iat must be ≤ 300 seconds. Coda allows about 30 seconds of clock skew. Every listed claim is required. After signature verify, each claim must exactly match the JSON body (same types). Mismatch → resultCode 103.

Claim	Type	Rule
iat	number	Unix seconds UTC. Must be ≤ now (with skew).
exp	number	Unix seconds UTC. Must be > now. exp - iat ≤ 300.
orderId	string	Match body orderId.
projectId	number	Match body projectId. Used with country to resolve the merchant.
country	number	Match body country.
currency	number	Match body currency.
payType	number	Match body payType.
offSessionType	string	Match body offSessionType.
items	array of {code, price, name}	Same length and fields as body items. This binds the amount.
paymentMethodId	string	Match body paymentMethodId.

Do not include iss, jti, kid, apiKey, userInitiated, shopper, profile, or paymentMethods in the JWT. This endpoint is MIT-only; Coda sets customer-absent internally.

{
  "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"
}

Sign (Node-style sketch)

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 allowlist (Token Charge)

Coda only accepts Token Charge from IPv4 addresses or CIDR ranges you give your account manager (NAT / load-balancer egress of the servers that call the API — not developer laptops unless that is intentional for sandbox).

Rule	Detail
Who sends IPs	You, before go-live
Format	Exact IPv4 and/or CIDR (e.g. 203.0.113.10, 198.51.100.0/24)
If missing or IP not listed	Token Charge is rejected

When your egress IPs change, notify Coda before cutover.