Skip to main content

​
Overview

Tokens allow you to securely collect card details on your own payment form. Card data is tokenized in the browser using the JavaScript SDK and your publishable key, so raw card numbers never reach your server.

​
Create Token

POST /v1/tokens Authentication: Publishable key (pk_test_* / pk_live_*) via Bearer token
You can call this endpoint directly with fetch or any HTTP client. The JavaScript SDK is optional — it provides client-side validation and a simpler API, but is not required.

​
Request Parameters

​
card
object
required
Card details object

​
Response

​
id
string
Token ID (tok_ prefix). Valid for 30 minutes, single use.
​
card
object
Masked card details
​
connector_id
string
Connector ID used for tokenization
​
created_at
string
Creation timestamp (ISO 8601)
​
expires_at
string
Expiration timestamp (ISO 8601). 30 minutes after creation.
curl -X POST https://api.sandbox.zafapay.com/v1/tokens \
  -H "Authorization: Bearer pk_test_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "card": {
      "number": "4242424242424242",
      "exp_month": 12,
      "exp_year": 2027,
      "cvc": "123",
      "cardholder_name": "John Doe"
    }
  }'

{
  "id": "tok_xxxxxxxxxxxxxxxxxxxxxx",
  "card": {
    "bin": "424242",
    "last4": "4242",
    "brand": "visa",
    "exp_month": 12,
    "exp_year": 2027
  },
  "connector_id": "conn_xxx",
  "created_at": "2026-04-07T10:30:00.000Z",
  "expires_at": "2026-04-07T11:00:00.000Z"
}

​
Token Errors

CodeHTTP StatusDescription
validation_error400Invalid card details (number, expiry, CVC)
tokenization_failed400Failed to tokenize card data
payment_token_expired400Token has expired (30 minute limit)
payment_token_already_used400Token has already been used for a payment

​
Using a Token for Payment

After creating a token, pass it to POST /v1/payments: 
{
  "amount": 10.00,
  "currency": "usd",
  "token": "tok_xxxxxxxxxxxxxxxxxxxxxx",
  "return_url": "https://your-site.com/complete"
}
For the full integration guide, see Server-to-Server Payments.

​
JavaScript SDK

The JavaScript SDK is an optional convenience wrapper that provides client-side card validation and a simpler API. 
<script src="https://js.zafapay.com/v1/zafapay.js"></script>

const zafapay = Zafapay('pk_test_xxxxx');

const { token, card, expires_at } = await zafapay.createToken({
  number: '4242424242424242',
  exp_month: 12,
  exp_year: 2027,
  cvc: '123',
  cardholder_name: 'John Doe'
});
// token: "tok_xxxxxxxxxxxxxxxxxxxxxx"
// card: { bin, last4, brand, exp_month, exp_year }
The SDK returns the token ID as token (the API response field is id — the SDK renames it for convenience).