Manage Customer Payment Instruments

This page describes how to create, retrieve, update, and delete payment instruments linked to a customer token, including how to add default and non-default instruments using an instrument identifier or a validated payment, and how to 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}

Was this page helpful?

Last published: September 29, 2026