API references
Search documentation... ⌘K
API references
Open merchant dashboard
SDK API
All our references

Tokenize a card number

This endpoint securely converts sensitive card details into a token that can be safely stored and used for future payments. The token can be used with the select-payment-method endpoint to process card payments.

The tokenization process helps you maintain PCI compliance by avoiding the need to handle raw card data directly in your systems. The token can only be used with your merchant account and cannot be used to process payments elsewhere.

For security reasons, tokens are single-use by default. If you need to charge the same card multiple times (like for subscriptions), set usage to MULTIPLE when creating the token.

Endpoint signature
POST https://api.reservepay.com/sdk/tokenize-card HTTP/1.1
Content-Type: application/json
Accept: application/json
{
merchant_id: string,
installation_id: string,
number: string,
name: string,
expiration_date: string,
security_code: string,
usage: string?,
}
Returns: string
New to Reservepay? Read our guide on how to call endpoints to get started.
Request arguments
merchant_id string

Required. Your merchant ID that uniquely identifies your account.

installation_id string

Required. The installation ID for this platform (e.g. your iOS app, Android app, website, or terminal).

number string

Required. The card number (PAN) without any spaces or special characters.

name string

Required. The cardholder's name exactly as it appears on the card.

expiration_date string

Required. The card's expiration date in MM/YY format (e.g. 12/25).

security_code string

Required. The card's security code (CVV/CVC). This is typically a 3-digit number on the back of the card, or 4 digits on the front for American Express.

usage string

Optional. Controls how many times this card token can be used for payments:

  • SINGLE (default): The token can only be used once and will be invalidated after the first payment attempt
  • MULTIPLE: The token can be used multiple times, suitable for recurring payments or subscriptions
Allowed values:
  • SINGLE
  • MULTIPLE
Errors specific to this endpoint
NOT_FOUND

This error occurs when we cannot find the merchant account or installation with the IDs provided. Double check that you are using the correct IDs.

Errors common to all endpoints
UNHANDLED_ERROR

This error occurs when the server encounters an unexpected internal error that it cannot handle gracefully. This typically happens due to bugs, infrastructure issues, or edge cases that weren't anticipated during development.

INVALID_ARGUMENTS

This error occurs when the request contains invalid or missing parameters. Common cases include missing required fields, or values that don't match the expected format or type.

BAD_VERSION

This error occurs when making requests to an API version that is either deprecated or not yet released. This commonly happens when using an outdated SDK or when the API version specified in the request URL is incorrect.

CODE SAMPLES
curl
curl "https://api.reservepay.com/sdk/tokenize-card" \
  -X POST
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "merchant_id": "123456789012",
        "installation_id": "ins_xhBi6ypq9G",
        "number": "4242424242424242",
        "name": "John Doe",
        "expiration_date": "12/29",
        "security_code": "123",
        "usage": "SINGLE"
      }'
Learn how to run these code samples in your terminal by reading our guide.