Manage Payment Instrument Tokens

This page describes how to create, retrieve, update, and delete payment instrument tokens, including how to retrieve a payment instrument with an unmasked card number and how to find payment instruments by card number.

Create a Payment Instrument

Endpoint

POST /tms/v1/paymentinstruments

Example

{  "card": {    "expirationMonth": "12",    "expirationYear": "2031"  },  "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/v1/paymentinstruments/F39763E8CFDF2354E053AF598E0AF684"    }  },  "id": "F39763E8CFDF2354E053AF598E0AF684",  "object": "paymentInstrument",  "state": "ACTIVE",  "card": {    "expirationMonth": "12",    "expirationYear": "2031",    "type": "visa"  },  "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"  },  "metadata": {    "creator": "testrest"  },  "_embedded": {    "instrumentIdentifier": {      "_links": {        "self": {          "href": "/tms/v1/instrumentidentifiers/7010000000016241111"        },        "paymentInstruments": {          "href": "/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstruments"        }      },      "id": "7010000000016241111",      "object": "instrumentIdentifier",      "state": "ACTIVE",      "card": {        "number": "4XXXXXXXXXXX1111"      },      "processingInformation": {        "authorizationOptions": {          "initiator": {            "merchantInitiatedTransaction": {              "previousTransactionId": "123456789619999"            }          }        }      },      "metadata": {        "creator": "testrest"      }    }  }}

Field	Type	Description
`instrumentIdentifier.id`	string	The ID of the instrument identifier token to use to create this payment instrument.

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`.
`default`	boolean	Set to `true` if this is the default payment instrument; `false` otherwise.
`merchantInformation.merchantDescriptor.alternateName`	string	Alternate name for the merchant descriptor.
`processingInformation.bankTransferOptions.SECCode`	string	Standard Entry Class (SEC) code for bank transfer.
`processingInformation.billPaymentProgramEnabled`	boolean	Set to `true` to enable the bill payment program.
`card.tokenizedInformation.requestorID`	string	Token requestor ID for the tokenized card.
`card.tokenizedInformation.transactionType`	string	Transaction type for the tokenized card.

Retrieve a Payment Instrument

The {paymentInstrumentTokenId} is the payment instrument token ID you want to retrieve. For more information, see Create a Payment Instrument.

Endpoint

GET /tms/v1/paymentinstruments/{paymentInstrumentTokenId}

Example

{  "_links": {    "self": {      "href": "/tms/v1/paymentinstruments/F39763E8CFDF2354E053AF598E0AF684"    }  },  "id": "F39763E8CFDF2354E053AF598E0AF684",  "object": "paymentInstrument",  "state": "ACTIVE",  "card": {    "expirationMonth": "12",    "expirationYear": "2031",    "type": "visa"  },  "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"  },  "metadata": {    "creator": "testrest"  },  "_embedded": {    "instrumentIdentifier": {      "_links": {        "self": {          "href": "/tms/v1/instrumentidentifiers/7010000000016241111"        },        "paymentInstruments": {          "href": "/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstruments"        }      },      "id": "7010000000016241111",      "object": "instrumentIdentifier",      "state": "ACTIVE",      "card": {        "number": "4XXXXXXXXXXX1111"      },      "processingInformation": {        "authorizationOptions": {          "initiator": {            "merchantInitiatedTransaction": {              "previousTransactionId": "123456789619999"            }          }        }      },      "metadata": {        "creator": "testrest"      }    }  }}

Retrieve a Payment Instrument with an Unmasked Card Number

Use the returnUnmaskedCardNumber=true query parameter to retrieve a payment instrument with an unmasked card number.

Endpoint

GET /tms/v1/paymentinstruments/{paymentInstrumentTokenId}?returnUnmaskedCardNumber=true

Find Payment Instruments by Card Number

The instrumentIdentifierTokenId is the instrument identifier token ID returned in the id field when you created the instrument identifier token.

Endpoint

GET /tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}/paymentinstruments?offset=0&limit=20

Use these query string parameters to filter the list of payment instrument tokens:

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`.

Update a Payment Instrument

The {paymentInstrumentTokenId} is the payment instrument token ID you want to update. For more information, see Create a Payment Instrument.

Endpoint

PATCH /tms/v1/paymentinstruments/{paymentInstrumentTokenId}

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`.
`default`	boolean	Set to `true` if this is the default payment instrument; `false` otherwise.
`merchantInformation.merchantDescriptor.alternateName`	string	Alternate name for the merchant descriptor.
`processingInformation.bankTransferOptions.SECCode`	string	Standard Entry Class (SEC) code for bank transfer.
`processingInformation.billPaymentProgramEnabled`	boolean	Set to `true` to enable the bill payment program.
`card.tokenizedInformation.requestorID`	string	Token requestor ID for the tokenized card.
`card.tokenizedInformation.transactionType`	string	Transaction type for the tokenized card.

Delete a Payment Instrument

Endpoint

DELETE /tms/v1/paymentinstruments/{paymentInstrumentTokenId}

Field	Type	Description
`paymentInstrumentTokenId`	string	The payment instrument token ID to delete, included in the URL path.

Was this page helpful?

Last published: September 29, 2026