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
POST /tms/v2/customers/{customerTokenId}/payment-instruments
POST /tms/v2/customers/{customerTokenId}/payment-instruments
POST /tms/v2/customers/{customerTokenId}/payment-instruments
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": "", "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": "", "phoneNumber": "4158880000" }, "instrumentIdentifier": { "id": "7010000000016241111" }, "metadata": { "creator": "testrest" }}Required Fields for Create a Customer Payment Instrument
card.type
Required if the instrument identifier ID being linked to is card-based. For example, 001 for Visa.
Optional Fields for Create a Customer Payment Instrument
bankAccount.type
The bank account type.
billTo.address1
The first line of the billing street address.
billTo.address2
The second line of the billing street address.
billTo.administrativeArea
State or province in the billing address.
billTo.company
The name of the customer's company.
billTo.country
Country of the billing address. Use the two-character ISO Standard Country Code.
billTo.email
The customer's billing email address.
billTo.firstName
The customer's first name.
billTo.lastName
The customer's last name.
billTo.locality
City in the billing address.
billTo.phoneNumber
The customer's phone number.
billTo.postalCode
ZIP or postal code in the billing address.
buyerInformation.companyTaxID
The company tax ID of the customer.
buyerInformation.currency
The default currency for the customer.
buyerInformation.dateOfBirth
The customer's date of birth.
buyerInformation.personalIdentification.id
Personal identification number.
buyerInformation.personalIdentification.issuedBy.administrativeArea
State or province that issued the personal identification.
buyerInformation.personalIdentification.type
Type of personal identification.
card.expirationMonth
Card expiration month in two-digit format. For example, 12.
card.expirationYear
Card expiration year in four-digit format. For example, 2031.
card.issueNumber
Number of times a Maestro (UK Domestic) card has been issued.
card.startMonth
Month of the start of the Maestro (UK Domestic) card validity period.
card.startYear
Year of the start of the Maestro (UK Domestic) card validity period.
card.useAs
How the card is used. For example, credit or debit.
card.tokenizedInformation.requestorID
Token requestor ID for the tokenized card.
card.tokenizedInformation.transactionType
Transaction type for the tokenized card.
default
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
The instrument identifier token ID to link to this payment instrument.
processingInformation.billPaymentProgramEnabled
Set to true to enable the bill payment program.
merchantInformation.merchantDescriptor.alternateName
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
POST /tms/v2/customers/{customerTokenId}/payment-instruments
POST /tms/v2/customers/{customerTokenId}/payment-instruments
POST /tms/v2/customers/{customerTokenId}/payment-instruments
POST /tms/v2/customers/{customerTokenId}/payment-instruments
Required Fields for Add a Default Payment Instrument Using Instrument Identifier
instrumentIdentifier.id
The instrument identifier token ID to link as the default payment instrument.
default
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
POST /pts/v2/payments
Required Fields for Add Default Payment Instrument with Validated Payment
paymentInformation.paymentInstrument.id
The payment instrument token ID.
orderInformation.amountDetails.totalAmount
The total amount for the order.
orderInformation.amountDetails.currency
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
POST /tms/v2/customers/{customerTokenId}/payment-instruments
POST /tms/v2/customers/{customerTokenId}/payment-instruments
POST /tms/v2/customers/{customerTokenId}/payment-instruments
POST /tms/v2/customers/{customerTokenId}/payment-instruments
Required Fields for Add a Non-Default Payment Instrument Using Instrument Identifier
instrumentIdentifier.id
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
POST /pts/v2/payments
Required Fields for Add Non-Default Payment Instrument with Validated Payment
paymentInformation.paymentInstrument.id
The payment instrument token ID.
orderInformation.amountDetails.totalAmount
The total amount for the order.
orderInformation.amountDetails.currency
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}
PATCH /tms/v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId}
PATCH /tms/v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId}
PATCH /tms/v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId}
PATCH /tms/v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId}
Required Fields for Change a Customer's Default Payment Instrument
customerTokenId
The customer token ID in the URL path.
paymentInstrumentTokenId
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}
GET /tms/v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId}
GET /tms/v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId}
GET /tms/v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId}
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": "", "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}
GET /tms/v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId}
GET /tms/v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId}
GET /tms/v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId}
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
GET /tms/v2/customers/{customerTokenId}/payment-instruments
GET /tms/v2/customers/{customerTokenId}/payment-instruments
GET /tms/v2/customers/{customerTokenId}/payment-instruments
GET /tms/v2/customers/{customerTokenId}/payment-instruments
Optional Fields for List Payment Instruments for a Customer
offset
Page offset number for pagination. Defaults to 0.
limit
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}
PATCH /tms/v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId}
PATCH /tms/v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId}
PATCH /tms/v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId}
PATCH /tms/v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId}
Required Fields for Update a Customer Payment Instrument
customerTokenId
The customer token ID in the URL path.
paymentInstrumentTokenId
The payment instrument token ID in the URL path.
Optional Fields for Update a Customer Payment Instrument
bankAccount.type
The bank account type.
billTo.address1
The first line of the billing street address.
billTo.address2
The second line of the billing street address.
billTo.administrativeArea
State or province in the billing address.
billTo.company
The name of the customer's company.
billTo.country
Country of the billing address. Use the two-character ISO Standard Country Code.
billTo.email
The customer's billing email address.
billTo.firstName
The customer's first name.
billTo.lastName
The customer's last name.
billTo.locality
City in the billing address.
billTo.phoneNumber
The customer's phone number.
billTo.postalCode
ZIP or postal code in the billing address.
buyerInformation.companyTaxID
The company tax ID of the customer.
buyerInformation.currency
The default currency for the customer.
buyerInformation.dateOfBirth
The customer's date of birth.
buyerInformation.personalIdentification.id
Personal identification number.
buyerInformation.personalIdentification.issuedBy.administrativeArea
State or province that issued the personal identification.
buyerInformation.personalIdentification.type
Type of personal identification.
card.expirationMonth
Card expiration month in two-digit format. For example, 12.
card.expirationYear
Card expiration year in four-digit format. For example, 2031.
card.issueNumber
Number of times a Maestro (UK Domestic) card has been issued.
card.startMonth
Month of the start of the Maestro (UK Domestic) card validity period.
card.startYear
Year of the start of the Maestro (UK Domestic) card validity period.
card.type
The card type code. For example, 001 for Visa.
card.useAs
How the card is used. For example, credit or debit.
card.tokenizedInformation.requestorID
Token requestor ID for the tokenized card.
card.tokenizedInformation.transactionType
Transaction type for the tokenized card.
default
Set to true if this is the default payment instrument; false otherwise.
instrumentIdentifier.id
The instrument identifier token ID to link to this payment instrument.
processingInformation.billPaymentProgramEnabled
Set to true to enable the bill payment program.
merchantInformation.merchantDescriptor.alternateName
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}
DELETE /tms/v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId}
DELETE /tms/v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId}
DELETE /tms/v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId}
DELETE /tms/v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId}
Thanks for your feedback!
Last published: October 28, 2026