Skip to main content

Create Token

The /v1/tokens endpoint tokenizes a card without requiring a full payment. There are two flows depending on whether you pass save_only.

note

This endpoint is for creditcard only. To save a card from an Apple Pay or Samsung Pay payment, use source.save_card: true instead.

Default flow​

Creates a token using a 1 SAR card authorization for 3DS verification. The 1 SAR is never captured — it is voided automatically. Once the cardholder completes verification, the token becomes active and can be reused for any number of future payments.

How it works​

  1. Call POST /v1/tokens. The token is returned as initiated with a verification_url.
  2. Redirect the cardholder to verification_url to complete 3DS.
  3. After 3DS, the cardholder is returned to your callback_url and the token becomes active.
  4. Use the active token with POST /v1/payments to charge the customer later.

Endpoint: POST /v1/tokens

Authentication: Publishable key

POST /v1/tokens
{
  "name": "John Doe",
  "number": "4111111111111111",
  "month": 12,
  "year": 30,
  "cvc": "123",
  "callback_url": "https://merchant.example/token-saved"
}

Response​

POST /v1/tokens — initiated response
{
  "id": "token_x6okRgkZJrhgDHyqJ9zztW2X1k",
  "status": "initiated",
  "brand": "visa",
  "funding": "credit",
  "country": "US",
  "month": "12",
  "year": "2030",
  "name": "John Doe",
  "last_four": "1111",
  "metadata": null,
  "message": null,
  "verification_url": "https://api.moyasar.com/v1/...",
  "created_at": "2024-01-15T10:00:00.000Z",
  "updated_at": "2024-01-15T10:00:00.000Z"
}

Redirect the cardholder to verification_url. After 3DS, the token status changes to active. Always confirm this by fetching the token before using it for a payment.

Save-only flow​

Creates a token without any charge or 3DS at creation time. The token is short-lived and single-use — it can only be passed to POST /v1/payments once. When your backend does so, Moyasar automatically runs 3DS for the actual payment amount.

Use this when you want the frontend to collect the card, but the backend to control the payment amount and initiation.

warning

Save-only tokens do not produce a recurring active token after the payment. If you need a recurring token, use the default flow or save the card during the payment.

How it works​

  1. Frontend calls POST /v1/tokens with save_only: true. No charge, no 3DS.
  2. Frontend passes the token ID to your backend (e.g. via your own API).
  3. Backend calls POST /v1/payments with source.type: "token" and the token ID. 3DS is automatically triggered.
  4. The payment response includes source.transaction_url. Redirect the cardholder to complete 3DS.
  5. After 3DS, the cardholder is returned to your callback_url and the payment completes.

Endpoint: POST /v1/tokens

Authentication: Publishable key

POST /v1/tokens
{
  "name": "John Doe",
  "number": "4111111111111111",
  "month": 12,
  "year": 30,
  "cvc": "123",
  "save_only": true
}

Then your backend initiates the payment:

Endpoint: POST /v1/payments

Authentication: Publishable key

POST /v1/payments
{
  "amount": 10000,
  "currency": "SAR",
  "callback_url": "https://merchant.example/return",
  "source": {
    "type": "token",
    "token": "token_x6okRgkZJrhgDHyqJ9zztW2X1k"
  }
}

The payment comes back as initiated with a source.transaction_url. Redirect the cardholder there to complete 3DS for the actual payment amount.

Request parameters​

FieldRequiredDescription
nameYesCardholder name as it appears on the card
numberYesCard number (digits only)
monthYesExpiry month as an integer (e.g. 12)
yearYesExpiry year as a 2-digit integer (e.g. 30)
cvcYesCard verification code (3–4 digits)
callback_urlYes for default flowURL to redirect the cardholder after 3DS verification. Not required for save_only tokens
save_onlyNoSet to true to create a short-lived token with no charge. Defaults to false
metadataNoCustom key-value pairs attached to the token
Last updated on