API references
Search documentation... ⌘K
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. To save the card to a contact for later payments, set usage to MULTIPLE when creating the token.

The security code is never saved with the card. It covers only the payment made right after tokenization, so use the token right away. For a later customer-initiated payment on a saved card, collect the security code again and call rehydrate-card right before select-payment-method. To charge a saved card from your backend without the security code (a merchant-initiated payment), use the merchant request-payment endpoint instead.

Billing-address fields are routed according to the setting that requires them:

Configuration Address destination Required fields
Card payment method requires_address: true tokenize-card The card payment method's required_fields
Installation address_capture: required select-payment-method The selected payment method's required_fields

This endpoint validates only the card payment method's address requirement. Installation address capture is validated by select-payment-method. street_address_2 is always optional.

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?,
payment_method: string?,
street_address_1: string?,
street_address_2: string?,
postal_code: string?,
city: string?,
state: string?,
country: 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 saved to a contact and reused for later payments. Each later customer-initiated payment needs the security code again through rehydrate-card
Allowed values:
  • SINGLE
  • MULTIPLE
payment_method string

Optional. The card-based payment method this card will be charged with:

  • CARD (default): a one-time card payment
  • INSTALLMENT: a card installment payment
Allowed values:
  • CARD
  • INSTALLMENT
  • CARD_PRESENT
street_address_1 string

Optional. The first line of the cardholder's billing address (e.g. street number and name).

street_address_2 string

Optional. The second line of the cardholder's billing address (e.g. apartment, suite, or unit).

postal_code string

Optional. The postal or ZIP code of the cardholder's billing address.

city string

Optional. The city of the cardholder's billing address.

state string

Optional. The state, province, or region of the cardholder's billing address.

country string

Optional. The country of the cardholder's billing address.

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.

NOT_ENABLED

This installation is currently disabled.

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.

Open in Markdown
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.