Save a card for future payments
Convert a single-use token into a reusable card that can be charged multiple times. This is useful for:
- Implementing "save card for later" functionality
- Setting up subscription billing
- Enabling one-click payments
The token must be created with multi-use capability (usage="multi"). Single-use tokens cannot be saved as cards.
You can optionally provide your own external_id to help track the card in your system. This ID can be used instead of the card ID in other API calls.
This card will be associated with that contact. If default is set to true, the card will be set as the contact's default card.
The endpoint returns the unique card ID that you can use for future charges.
Note: A token can only be saved as a card once. Attempting to save the same token multiple times will result in an error.
external_id
string
Optional. Your custom identifier for this card. This can be used instead of the card ID in other API calls to help match cards to your system's records. Must be unique across all your saved cards.
token
string
Required. The token ID to convert into a saved card. Must be a multi-use token that hasn't been saved before.
contact_id
string
Required. Either a Contact ID (starting with ctc_) or your own external
contact identifier. We'll link this card to an existing contact
if found, or create a new contact if not.
If you provide your own external ID and a contact with that ID doesn't exist, we'll create a new contact using that ID as their external identifier.
contact_email
string
Optional. The contact's email address. If provided, we'll either:
- Link this card to an existing contact with this email
- Create a new contact with this email if no match is found
- Update the email for the contact specified in contact_id (if provided)
contact_mobile
string
Optional. The contact's mobile number. If provided, we'll either:
- Link this card to an existing contact with this mobile
- Create a new contact with this mobile if no match is found
- Update the mobile for the contact specified in contact_id (if provided)
contact_name
string
Optional. The contact's name. If provided, we'll either:
- Update the name for an existing contact if found
- Set the name when creating a new contact
- Update the name for the contact specified in contact_id (if provided)
default
boolean
Optional. Make this card the primary card for the contact. Default: false.
NOT_FOUND
The token with the provided ID could not be found, or the contact with the provided contact_id could not be found. Verify that you're using the correct IDs.
NOT_REUSABLE
The token is single-use and cannot be saved as a card. Create a new multi-use token instead.
ALREADY_SAVED
This token has already been converted to a saved card. Use the existing card ID instead.
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 does not exist. This commonly happens when using an outdated SDK or when the API version specified in the request URL is incorrect.
curl "https://api.reservepay.com/merchants/save-card" \
-X POST
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer $(RESERVEPAY_API_KEY)" \
-d '{
"external_id": "3958",
"token": "IC3949UCOE6U93"
}'