Tokens

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

object

required

Card details object

Show card properties

string

required

Card number (13-19 digits). Spaces and dashes are automatically stripped.

integer

required

Expiration month (1-12)

integer

required

Expiration year (e.g., 2027)

string

required

Security code (3-4 digits)

string

Cardholder name

Response

string

Token ID (tok_ prefix). Valid for 30 minutes, single use.

object

Masked card details

Show card properties

string

Last 4 digits of the card number

string

Card brand (visa, mastercard, amex, discover, jcb, diners)

integer

Expiration month

integer

Expiration year

string

Creation timestamp (ISO 8601)

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

const response = await fetch('https://api.sandbox.zafapay.com/v1/tokens', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pk_test_xxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    card: {
      number: '4242424242424242',
      exp_month: 12,
      exp_year: 2027,
      cvc: '123',
      cardholder_name: 'John Doe'
    }
  })
});

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

Token Errors

Code	HTTP Status	Description
`validation_error`	400	Invalid card details (number, expiry, CVC)
`tokenization_failed`	400	Failed to tokenize card data
`payment_token_expired`	400	Token has expired (30 minute limit)
`payment_token_already_used`	400	Token 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.

You can save the card for recurring payments by adding save_card: true and customer_id to the payment request. See S2S Payments — Save Card for details.

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: { 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).

Overview

Payments

Customers

Webhook

Tokens

Overview

Create Token

Request Parameters

Response

Token Errors

Using a Token for Payment

JavaScript SDK

​Overview

​Create Token

​Request Parameters

​Response

​Token Errors

​Using a Token for Payment

​JavaScript SDK

Overview

Create Token

Request Parameters

Response

Token Errors

Using a Token for Payment

JavaScript SDK