Manage Customer Tokens

This page describes how to create, retrieve, update, and delete customer tokens, including how to retrieve a customer's default payment and shipping details, and how to manage the payment instruments and shipping addresses linked to a customer.

Create a Customer

This section describes how to create a customer token with no payment details.

Endpoint

POST /tms/v2/customers

Example

{  "buyerInformation": {    "merchantCustomerID": "Your customer identifier",    "email": "{% t key="test-email" /%}"  },  "clientReferenceInformation": {    "code": "TC50171_3"  },  "merchantDefinedInformation": [    {      "name": "data1",      "value": "Your customer data"    }  ]}

{  "_links": {    "self": {      "href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078"    },    "paymentInstruments": {      "href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/payment-instruments"    },    "shippingAddresses": {      "href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/shipping-addresses"    }  },  "id": "F2F3ADA770102B51E053A2598D0A9078",  "buyerInformation": {    "merchantCustomerID": "Your customer identifier",    "email": "{% t key="test-email" /%}"  },  "clientReferenceInformation": {    "code": "TC50171_3"  },  "merchantDefinedInformation": [    {      "name": "data1",      "value": "Your customer data"    }  ],  "metadata": {    "creator": "testrest"  }}

Optional Fields

Field	Type	Description
`buyerInformation.merchantCustomerID`	string	Your identifier for the customer.
`buyerInformation.email`	string	The customer's email address.
`clientReferenceInformation.code`	string	Unique reference code for the transaction.
`merchantDefinedInformation.name`	string	The name of the merchant-defined data field.
`merchantDefinedInformation.value`	string	The value of the merchant-defined data field.

Retrieve a Customer

This section describes how to retrieve a customer token.

Endpoint

GET /tms/v2/customers/{customerTokenId}

The {customerTokenId} is the customer token ID returned in the id field when you created the customer token.

Example

{  "_links": {    "self": {      "href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078"    },    "paymentInstruments": {      "href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/payment-instruments"    },    "shippingAddresses": {      "href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/shipping-addresses"    }  },  "id": "F2F3ADA770102B51E053A2598D0A9078",  "buyerInformation": {    "merchantCustomerID": "Your customer identifier",    "email": "{% t key="test-email" /%}"  },  "clientReferenceInformation": {    "code": "TC50171_3"  },  "merchantDefinedInformation": [    {      "name": "data1",      "value": "Your customer data"    }  ],  "metadata": {    "creator": "testrest"  }}

Update a Customer

This section describes how to update a customer token.

Endpoint

PATCH /tms/v2/customers/{customerTokenId}

The {customerTokenId} is the customer token ID returned in the id field when you created the customer token. Include only the fields you want to add or update in the request.

Example

{  "_links": {    "self": {      "href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078"    },    "paymentInstruments": {      "href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/payment-instruments"    },    "shippingAddresses": {      "href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/shipping-addresses"    }  },  "id": "F2F3ADA770102B51E053A2598D0A9078",  "buyerInformation": {    "merchantCustomerID": "Your customer identifier",    "email": "{% t key="test-email" /%}"  },  "clientReferenceInformation": {    "code": "TC50171_3"  },  "merchantDefinedInformation": [    {      "name": "data1",      "value": "Your customer data"    }  ],  "metadata": {    "creator": "testrest"  }}

Optional Fields

Field	Type	Description
`buyerInformation.merchantCustomerID`	string	Your identifier for the customer.
`buyerInformation.email`	string	The customer's email address.
`clientReferenceInformation.code`	string	Unique reference code for the transaction.
`merchantDefinedInformation.name`	string	The name of the merchant-defined data field.
`merchantDefinedInformation.value`	string	The value of the merchant-defined data field.

Delete a Customer

This section describes how to delete a customer token.

Endpoint

DELETE /tms/v2/customers/{customerTokenId}

The {customerTokenId} is the customer token ID returned in the id field when you created the customer token. A successful delete response returns an empty HTTP 204 No Content status.

Retrieve a Customer's Default Payment with an Unmasked Card Number

This section describes how to retrieve a customer's default payment with an unmasked card number.

Endpoint

GET /tms/v2/customers/{customerTokenId}

The {customerTokenId} is the customer token ID returned in the id field when you created the customer token. The response returns encrypted card data.

Example

eyJraWQiOiJiYTE1ZDRmMTIzMTM0NjlkZjg5MDM1Nzk2YWE4Nzc4ZGM0NTY4ODlkIiwiY3R5IjoianNvbiIsInR5cCI6IkpXVCIsImVuYyI6IkEyNTZHQ00iLCJhbGciOiJSU0EtT0FFUC0yNTYifQ...

Retrieve a Customer's Default Payment and Shipping Details

This section describes how to retrieve a customer's default payment and shipping details.

Endpoint

GET /tms/v2/customers/{customerTokenId}

The {customerTokenId} is the customer token ID returned in the id field when you created the customer token.

This section describes how to create, retrieve, update, and delete payment instruments linked to a customer token, including how to add default and non-default instruments and change which instrument is the customer's default.

Create a Customer Payment Instrument

Endpoint

POST /tms/v2/customers/{customerTokenId}/payment-instruments

The {customerTokenId} is the customer token ID returned in the id field when you created the customer token.

Example

{  "card": {    "expirationMonth": "12",    "expirationYear": "2031",    "type": "001"  },  "billTo": {    "firstName": "John",    "lastName": "Doe",    "company": "Company Name",    "address1": "1 Market St",    "locality": "San Francisco",    "administrativeArea": "CA",    "postalCode": "94105",    "country": "US",    "email": "{% t key="test-email" /%}",    "phoneNumber": "4158880000"  },  "instrumentIdentifier": {    "id": "7010000000016241111"  }}

{  "_links": {    "self": {      "href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/payment-instruments/F39732BE4BDA9A1EE053AF598E0A4081"    },    "customer": {      "href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078"    }  },  "id": "F39732BE4BDA9A1EE053AF598E0A4081",  "default": true,  "state": "ACTIVE",  "card": {    "expirationMonth": "12",    "expirationYear": "2031",    "type": "001"  },  "billTo": {    "firstName": "John",    "lastName": "Doe",    "company": "Company Name",    "address1": "1 Market St",    "locality": "San Francisco",    "administrativeArea": "CA",    "postalCode": "94105",    "country": "US",    "email": "{% t key="test-email" /%}",    "phoneNumber": "4158880000"  },  "instrumentIdentifier": {    "id": "7010000000016241111"  },  "metadata": {    "creator": "testrest"  }}

Field	Type	Description
`card.type`	string	Required if the instrument identifier ID being linked to is card-based. For example, `001` for Visa.

Optional Fields

Field	Type	Description
`bankAccount.type`	string	The bank account type.
`billTo.address1`	string	The first line of the billing street address.
`billTo.address2`	string	The second line of the billing street address.
`billTo.administrativeArea`	string	State or province in the billing address.
`billTo.company`	string	The name of the customer's company.
`billTo.country`	string	Country of the billing address. Use the two-character ISO Standard Country Code.
`billTo.email`	string	The customer's billing email address.
`billTo.firstName`	string	The customer's first name.
`billTo.lastName`	string	The customer's last name.
`billTo.locality`	string	City in the billing address.
`billTo.phoneNumber`	string	The customer's phone number.
`billTo.postalCode`	string	ZIP or postal code in the billing address.
`buyerInformation.companyTaxID`	string	The company tax ID of the customer.
`buyerInformation.currency`	string	The default currency for the customer.
`buyerInformation.dateOfBirth`	string	The customer's date of birth.
`buyerInformation.personalIdentification.id`	string	Personal identification number.
`buyerInformation.personalIdentification.issuedBy.administrativeArea`	string	State or province that issued the personal identification.
`buyerInformation.personalIdentification.type`	string	Type of personal identification.
`card.expirationMonth`	string	Card expiration month in two-digit format. For example, `12`.
`card.expirationYear`	string	Card expiration year in four-digit format. For example, `2031`.
`card.issueNumber`	string	Number of times a Maestro (UK Domestic) card has been issued.
`card.startMonth`	string	Month of the start of the Maestro (UK Domestic) card validity period.
`card.startYear`	string	Year of the start of the Maestro (UK Domestic) card validity period.
`card.useAs`	string	How the card is used. For example, `credit` or `debit`.
`card.tokenizedInformation.requestorID`	string	Token requestor ID for the tokenized card.
`card.tokenizedInformation.transactionType`	string	Transaction type for the tokenized card.
`default`	boolean	Set to `true` to designate this as the default payment instrument. If not included, the first payment instrument for a customer becomes the default.
`instrumentIdentifier.id`	string	The instrument identifier token ID to link to this payment instrument.
`processingInformation.billPaymentProgramEnabled`	boolean	Set to `true` to enable the bill payment program.
`merchantInformation.merchantDescriptor.alternateName`	string	Alternate name for the merchant descriptor.

Add a Default Payment Instrument Using Instrument Identifier

Add a default payment instrument to a customer account using an existing instrument identifier.

Endpoint

POST /tms/v2/customers/{customerTokenId}/payment-instruments

Field	Type	Description
`instrumentIdentifier.id`	string	The instrument identifier token ID to link as the default payment instrument.
`default`	boolean	Set to `true` to designate this as the default payment instrument.

Add Default Payment Instrument with Validated Payment

Add a default payment instrument to a customer account by validating a payment.

Endpoint

POST /pts/v2/payments

Field	Type	Description
`paymentInformation.paymentInstrument.id`	string	The payment instrument token ID.
`orderInformation.amountDetails.totalAmount`	string	The total amount for the order.
`orderInformation.amountDetails.currency`	string	The currency for the order. Use the three-character ISO Standard Currency Code.

Add a Non-Default Payment Instrument Using Instrument Identifier

Add a non-default payment instrument to a customer account using an existing instrument identifier.

Endpoint

POST /tms/v2/customers/{customerTokenId}/payment-instruments

Field	Type	Description
`instrumentIdentifier.id`	string	The instrument identifier token ID to link as a non-default payment instrument.

Add Non-Default Payment Instrument with Validated Payment

Add a non-default payment instrument to a customer account by validating a payment.

Endpoint

POST /pts/v2/payments

Field	Type	Description
`paymentInformation.paymentInstrument.id`	string	The payment instrument token ID.
`orderInformation.amountDetails.totalAmount`	string	The total amount for the order.
`orderInformation.amountDetails.currency`	string	The currency for the order. Use the three-character ISO Standard Currency Code.

Change a Customer's Default Payment Instrument

Change which payment instrument is designated as the default for a customer.

Endpoint

PATCH /tms/v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId}

Field	Type	Description
`customerTokenId`	string	The customer token ID in the URL path.
`paymentInstrumentTokenId`	string	The payment instrument token ID in the URL path.

Retrieve a Customer Payment Instrument

Retrieve a specific customer payment instrument.

Endpoint

GET /tms/v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId}

Example

GET /tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/payment-instruments/F39732BE4BDA9A1EE053AF598E0A4081

{  "_links": {    "self": {      "href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/payment-instruments/F39732BE4BDA9A1EE053AF598E0A4081"    },    "customer": {      "href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078"    }  },  "id": "F39732BE4BDA9A1EE053AF598E0A4081",  "default": true,  "state": "ACTIVE",  "card": {    "expirationMonth": "12",    "expirationYear": "2031",    "type": "001"  },  "billTo": {    "firstName": "John",    "lastName": "Doe",    "company": "Company Name",    "address1": "1 Market St",    "locality": "San Francisco",    "administrativeArea": "CA",    "postalCode": "94105",    "country": "US",    "email": "{% t key="test-email" /%}",    "phoneNumber": "4158880000"  },  "instrumentIdentifier": {    "id": "7010000000016241111"  },  "metadata": {    "creator": "testrest"  }}

Retrieve a Customer Payment Instrument with an Unmasked Card Number

Retrieve a customer payment instrument with the card number unmasked.

Endpoint

GET /tms/v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId}

List Payment Instruments for a Customer

Retrieve all payment instruments for a customer.

Endpoint

GET /tms/v2/customers/{customerTokenId}/payment-instruments

Optional Fields

Field	Type	Description
`offset`	integer	Page offset number for pagination. Defaults to `0`.
`limit`	integer	Maximum number of items to return. Defaults to `20`; maximum is `100`.

The {customerTokenId} is the customer token ID returned in the id field when you created the customer token.

Update a Customer Payment Instrument

Update a customer payment instrument.

Endpoint

PATCH /tms/v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId}

Field	Type	Description
`customerTokenId`	string	The customer token ID in the URL path.
`paymentInstrumentTokenId`	string	The payment instrument token ID in the URL path.

Optional Fields

Field	Type	Description
`bankAccount.type`	string	The bank account type.
`billTo.address1`	string	The first line of the billing street address.
`billTo.address2`	string	The second line of the billing street address.
`billTo.administrativeArea`	string	State or province in the billing address.
`billTo.company`	string	The name of the customer's company.
`billTo.country`	string	Country of the billing address. Use the two-character ISO Standard Country Code.
`billTo.email`	string	The customer's billing email address.
`billTo.firstName`	string	The customer's first name.
`billTo.lastName`	string	The customer's last name.
`billTo.locality`	string	City in the billing address.
`billTo.phoneNumber`	string	The customer's phone number.
`billTo.postalCode`	string	ZIP or postal code in the billing address.
`buyerInformation.companyTaxID`	string	The company tax ID of the customer.
`buyerInformation.currency`	string	The default currency for the customer.
`buyerInformation.dateOfBirth`	string	The customer's date of birth.
`buyerInformation.personalIdentification.id`	string	Personal identification number.
`buyerInformation.personalIdentification.issuedBy.administrativeArea`	string	State or province that issued the personal identification.
`buyerInformation.personalIdentification.type`	string	Type of personal identification.
`card.expirationMonth`	string	Card expiration month in two-digit format. For example, `12`.
`card.expirationYear`	string	Card expiration year in four-digit format. For example, `2031`.
`card.issueNumber`	string	Number of times a Maestro (UK Domestic) card has been issued.
`card.startMonth`	string	Month of the start of the Maestro (UK Domestic) card validity period.
`card.startYear`	string	Year of the start of the Maestro (UK Domestic) card validity period.
`card.type`	string	The card type code. For example, `001` for Visa.
`card.useAs`	string	How the card is used. For example, `credit` or `debit`.
`card.tokenizedInformation.requestorID`	string	Token requestor ID for the tokenized card.
`card.tokenizedInformation.transactionType`	string	Transaction type for the tokenized card.
`default`	boolean	Set to `true` if this is the default payment instrument; `false` otherwise.
`instrumentIdentifier.id`	string	The instrument identifier token ID to link to this payment instrument.
`processingInformation.billPaymentProgramEnabled`	boolean	Set to `true` to enable the bill payment program.
`merchantInformation.merchantDescriptor.alternateName`	string	Alternate name for the merchant descriptor.

Delete a Customer Payment Instrument

Delete a customer payment instrument.

Endpoint

DELETE /tms/v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId}

This section describes how to create, retrieve, update, and delete shipping address tokens linked to a customer token, including how to add default and non-default addresses and change which address is the customer's default.

Endpoints

Method	Path
`POST`	`/tms/v2/customers/{customerTokenId}/shipping-addresses`
`GET`	`/tms/v2/customers/{customerTokenId}/shipping-addresses/{shippingAddressTokenId}`
`GET`	`/tms/v2/customers/{customerTokenId}/shipping-addresses`
`PATCH`	`/tms/v2/customers/{customerTokenId}/shipping-addresses/{shippingAddressTokenId}`
`DELETE`	`/tms/v2/customers/{customerTokenId}/shipping-addresses/{shippingAddressTokenId}`

The {customerTokenId} is the customer token ID returned in the id field when you created the customer token.

Create a Customer Shipping Address

This operation creates a new shipping address token associated with a customer. If the default field is not supplied and the customer does not already have a shipping address, the shipping address becomes the default. Otherwise, it becomes a non-default shipping address.

Endpoint

POST /tms/v2/customers/{customerTokenId}/shipping-addresses

Example

POST /tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/shipping-addresses

{  "_links": {    "self": {      "href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/shipping-addresses/F2F4C2D1B966D631E053A2598D0AB155"    },    "customer": {      "href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078"    }  },  "id": "F2F4C2D1B966D631E053A2598D0AB155",  "default": true,  "shipTo": {    "firstName": "John",    "lastName": "Doe",    "company": "Company Name",    "address1": "1 Market St",    "locality": "San Francisco",    "administrativeArea": "CA",    "postalCode": "94105",    "country": "US",    "email": "{% t key=\"test-email\" /%}",    "phoneNumber": "4158880000"  },  "metadata": {    "creator": "testrest"  }}

Optional Fields

Field	Type	Description
`shipTo.address1`	string	The first line of the shipping street address.
`shipTo.address2`	string	The second line of the shipping street address.
`shipTo.administrativeArea`	string	State or province in the shipping address.
`shipTo.company`	string	The name of the recipient's company.
`shipTo.country`	string	Country of the shipping address. Use the two-character ISO Standard Country Code.
`shipTo.email`	string	The recipient's email address.
`shipTo.firstName`	string	The recipient's first name.
`shipTo.lastName`	string	The recipient's last name.
`shipTo.locality`	string	City in the shipping address.
`shipTo.phoneNumber`	string	The recipient's phone number.
`shipTo.postalCode`	string	ZIP or postal code in the shipping address.

Add a Default Shipping Address

This operation adds a new default shipping address to an existing customer. The new address becomes the customer's default shipping address.

Endpoint

POST /tms/v2/customers/{customerTokenId}/shipping-addresses

Field	Type	Description
`default`	boolean	Set to `true` to mark this as the default shipping address.

Optional Fields

Field	Type	Description
`shipTo.address1`	string	The first line of the shipping street address.
`shipTo.address2`	string	The second line of the shipping street address.
`shipTo.administrativeArea`	string	State or province in the shipping address.
`shipTo.company`	string	The name of the recipient's company.
`shipTo.country`	string	Country of the shipping address. Use the two-character ISO Standard Country Code.
`shipTo.email`	string	The recipient's email address.
`shipTo.firstName`	string	The recipient's first name.
`shipTo.lastName`	string	The recipient's last name.
`shipTo.locality`	string	City in the shipping address.
`shipTo.phoneNumber`	string	The recipient's phone number.
`shipTo.postalCode`	string	ZIP or postal code in the shipping address.

Add a Non-Default Shipping Address

This operation adds a new non-default shipping address to an existing customer. The address is stored but does not replace the customer's current default shipping address.

Endpoint

POST /tms/v2/customers/{customerTokenId}/shipping-addresses

Field	Type	Description
`default`	boolean	Set to `false` to mark this as a non-default shipping address.

Optional Fields

Field	Type	Description
`shipTo.address1`	string	The first line of the shipping street address.
`shipTo.address2`	string	The second line of the shipping street address.
`shipTo.administrativeArea`	string	State or province in the shipping address.
`shipTo.company`	string	The name of the recipient's company.
`shipTo.country`	string	Country of the shipping address. Use the two-character ISO Standard Country Code.
`shipTo.email`	string	The recipient's email address.
`shipTo.firstName`	string	The recipient's first name.
`shipTo.lastName`	string	The recipient's last name.
`shipTo.locality`	string	City in the shipping address.
`shipTo.phoneNumber`	string	The recipient's phone number.
`shipTo.postalCode`	string	ZIP or postal code in the shipping address.

Change Default Shipping Address

This operation designates a different existing shipping address as the customer's default. The previously default address becomes a non-default address.

Endpoint

PATCH /tms/v2/customers/{customerTokenId}/shipping-addresses/{shippingAddressTokenId}

Field	Type	Description
`default`	boolean	Set to `true` to make this address the new default shipping address.

Retrieve a Customer Shipping Address

This operation retrieves the details of a specific shipping address token associated with a customer.

Endpoint

GET /tms/v2/customers/{customerTokenId}/shipping-addresses/{shippingAddressTokenId}

The {shippingAddressTokenId} path parameter is the shipping address token ID returned in the response when you created the shipping address token.

Retrieve All Customer Shipping Addresses

This operation retrieves all shipping address tokens associated with a specific customer.

Endpoint

GET /tms/v2/customers/{customerTokenId}/shipping-addresses

Update a Customer Shipping Address

This operation updates an existing shipping address token. You can modify any of the shipping address fields.

Endpoint

PATCH /tms/v2/customers/{customerTokenId}/shipping-addresses/{shippingAddressTokenId}

Optional Fields

Field	Type	Description
`shipTo.address1`	string	The first line of the shipping street address.
`shipTo.address2`	string	The second line of the shipping street address.
`shipTo.administrativeArea`	string	State or province in the shipping address.
`shipTo.company`	string	The name of the recipient's company.
`shipTo.country`	string	Country of the shipping address. Use the two-character ISO Standard Country Code.
`shipTo.email`	string	The recipient's email address.
`shipTo.firstName`	string	The recipient's first name.
`shipTo.lastName`	string	The recipient's last name.
`shipTo.locality`	string	City in the shipping address.
`shipTo.phoneNumber`	string	The recipient's phone number.
`shipTo.postalCode`	string	ZIP or postal code in the shipping address.

Delete a Customer Shipping Address

This operation deletes a specific shipping address token associated with a customer.

Endpoint

DELETE /tms/v2/customers/{customerTokenId}/shipping-addresses/{shippingAddressTokenId}

Was this page helpful?

Last published: September 29, 2026