Tokenization

Vault card data with a merchant-signed JWT, then charge the stored token.

Use these endpoints to vault a card and to charge a stored token on later transactions, so sensitive card data never has to be stored on your side. Every operation below lists its required headers, the full request body fields, and the full body of each response it can return.

Endpoints on this page

Method	Path	Summary	operationId
POST	/payment/create/tokenization	Create Payment Tokenization	createTokenization
POST	/payment/create/token	Create Payment with Token	createWithToken

POST/payment/create/tokenization

Create Payment Tokenization

operationId: createTokenization

Initiates a credit-card payment and vaults the card for later use with /payment/create/token. The tokenization result arrives asynchronously at tokenization_notification_url. Credit cards only, consent must be true, and card data is supplied inside merchant_jwt.

Required headers

merchant-tokenContent-TypeIdempotency-Key

Request body

Tokenization request

Example variants

credit_card_tokenize

Responses

200	Payment create response
400	Error response
401	Error response
500	Error response

Example: tokenization JWT payload

{
  "jti": "e0f0a2f4-6f1e-4a5b-9a0e-1f2c3d4e5f60",
  "op": "tokenize",
  "sub": "9e07802d51264b02b4b3ef09dfb94219",
  "iat": 1735689600,
  "cardholder_number": "4111111111111111",
  "cardholder_name": "John Doe",
  "cardholder_exp_month": "12",
  "cardholder_exp_year": "2030"
}

Request body fields

Tokenization request26 fields

Field	Required	Type	Description	Example
merchant_id	required	string
merchant_site_id	required	string
payment_method	required	enum	credit_card only.	credit_card
amount	required	number
currency	required	string
email	required	string
request_id	required	string
country	required	string	ISO 3166-1 alpha-3.
first_name	required	string
last_name	required	string
notification_link	required	string (uri)
success_url	required	string (uri)
pending_url	required	string (uri)
fail_url	required	string (uri)
back_url	required	string (uri)
device_ip	required	string
mobile	required	string
address	required	string
city	required	string
zipCode	required	string
state	required	string
birthDate	required	string
cardCvv	required	string	Body field; never tokenized.
merchant_jwt	required	string	Carries the tokenize card data.
consent	required	boolean	Must be true.	true
tokenization_notification_url	required	string (uri)	Receives the tokenization result; separate from notification_link.

Response body fields

200Payment create response6 fields

Field	Required	Type	Description
status	optional	enum	success \| failed
status_code	optional	integer
request_id	optional	uuid / string
payin_id	optional	uuid
redirect_url	optional	string (uri)
created_at	optional	string (date-time)

400401500Error response8 fields

Field	Required	Type	Description
status	optional	enum	error
status_code	optional	integer
reason_code	optional	string
error_code	optional	string	5 digits
request_id	optional	uuid / string
message	optional	string
payin_id	optional	uuid \| null
details	optional	object	Field validation errors.

POST/payment/create/token

Create Payment with Token

operationId: createWithToken

Charges a vaulted card by redeeming the token inside merchant_jwt. No PAN, cardholder name or expiry is sent; CVV is collected on every charge. The merchant_jwt payload uses op=decrypt, sub and token.

Required headers

merchant-tokenContent-TypeIdempotency-Key

Request body

Pay with token request

Example variants

pay_with_token

Responses

200	Payment create response
400	Error response
401	Error response
500	Error response

Example: pay-with-token JWT payload

{
  "jti": "b71c9f0a-2c33-4d7e-8f61-52a0d9c7e311",
  "op": "decrypt",
  "sub": "9e07802d51264b02b4b3ef09dfb94219",
  "iat": 1735689600,
  "token": "tok_9f8c1b2a3d4e"
}

Request body fields

Pay with token request24 fields

Field	Required	Type	Description	Example
merchant_id	required	string
merchant_site_id	required	string
payment_method	required	enum	credit_card only.	credit_card
amount	required	number
currency	required	string
email	required	string
request_id	required	string
country	required	string
first_name	required	string
last_name	required	string
notification_link	required	string (uri)
success_url	required	string (uri)
pending_url	required	string (uri)
fail_url	required	string (uri)
back_url	required	string (uri)
device_ip	required	string
mobile	required	string
address	required	string
city	required	string
zipCode	required	string
state	required	string
birthDate	required	string
merchant_jwt	required	string	Carries the decrypt token data.
cardCvv	required	string	Collected on every charge.

Response body fields

200Payment create response6 fields

Field	Required	Type	Description
status	optional	enum	success \| failed
status_code	optional	integer
request_id	optional	uuid / string
payin_id	optional	uuid
redirect_url	optional	string (uri)
created_at	optional	string (date-time)

400401500Error response8 fields

Field	Required	Type	Description
status	optional	enum	error
status_code	optional	integer
reason_code	optional	string
error_code	optional	string	5 digits
request_id	optional	uuid / string
message	optional	string
payin_id	optional	uuid \| null
details	optional	object	Field validation errors.

Back to the full API reference