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
POST /tms/v1/paymentinstruments
POST /tms/v1/paymentinstruments
POST /tms/v1/paymentinstruments
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": "", "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": "", "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" } } }}Required Fields for Create a Payment Instrument
instrumentIdentifier.id
The ID of the instrument identifier token to use to create this payment instrument.
Optional Fields for Create a 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.
default
Set to true if this is the default payment instrument; false otherwise.
merchantInformation.merchantDescriptor.alternateName
Alternate name for the merchant descriptor.
processingInformation.bankTransferOptions.SECCode
Standard Entry Class (SEC) code for bank transfer.
processingInformation.billPaymentProgramEnabled
Set to true to enable the bill payment program.
card.tokenizedInformation.requestorID
Token requestor ID for the tokenized card.
card.tokenizedInformation.transactionType
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}
GET /tms/v1/paymentinstruments/{paymentInstrumentTokenId}
GET /tms/v1/paymentinstruments/{paymentInstrumentTokenId}
GET /tms/v1/paymentinstruments/{paymentInstrumentTokenId}
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": "", "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
Retrieve a payment instrument with the full, unmasked card number instead of the default masked value.
The response is BASE 64-encoded JSON web encryption (JWE) token. The decoded JWE has these elements:
{ "alg": "RSA-OAEP-256", //The algorithm used to encrypt the CEK "cty": "json", //The content type "typ": "JWT", //The token type "enc": "A256GCM", //The algorithm that is used to encrypt the message "kid": "keyId" //The serial number of shared public cert for encryption of CEK}<Encrypted Data> //The encrypted payload that matches the JSON response normally returned by the TMS API, except with an unmasked card numberHeader Configuration
You must pass this request header to retrieve unmasked payment details: Accept: application/jose.
The term application/jose refers to Javascript Object Signing and Encryption (JOSE). JOSE is a framework that provides end-to-end security to JavaScript Object Notation (JSON)-based data structures. JOSE achieves this by offering a collection of specifications to encrypt and digitally sign JSON payloads. In this case, the response is message-level encrypted using a JSON Web Token (JWT).
Endpoint
GET /tms/v1/paymentinstruments/{paymentInstrumentTokenId}
GET /tms/v1/paymentinstruments/{paymentInstrumentTokenId}
GET /tms/v1/paymentinstruments/{paymentInstrumentTokenId}
GET /tms/v1/paymentinstruments/{paymentInstrumentTokenId}
GET /tms/v1/paymentinstruments/{paymentInstrumentTokenId}
Find Payment Instruments by Card Number
Endpoint
GET /tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}/paymentinstruments?offset=0&limit=20
GET /tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}/paymentinstruments?offset=0&limit=20
GET /tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}/paymentinstruments?offset=0&limit=20
GET /tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}/paymentinstruments?offset=0&limit=20
GET /tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}/paymentinstruments?offset=0&limit=20
The instrumentIdentifierTokenId is the instrument identifier token ID returned in the id field when you created the instrument identifier token. For more information, see Create an Instrument Identifier.
Use these query string parameters to filter the list of payment instrument tokens:
offset— Page offset number.limit— Maximum number of items you would like returned.
Example
{ "_links": { "self": { "href": "/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstruments?offset=0&limit=5" }, "first": { "href": "/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstruments?offset=0&limit=5" }, "next": { "href": "/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstruments?offset=5&limit=5" }, "last": { "href": "/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstruments?offset=121265&limit=5" } }, "object": "collection", "offset": 0, "limit": 5, "count": 5, "total": 121269, "_embedded": { "paymentInstruments": [ { "_links": { "self": { "href": "/tms/v1/paymentinstruments/F4D5E715F7BD9910E053A2598D0A7278" }, "customer": { "href": "/tms/v1/customers/F4D5E715F75E9910E053A2598D0A7278" } }, "id": "F4D5E715F7BD9910E053A2598D0A7278", "object": "paymentInstrument", "state": "ACTIVE", "card": { "expirationMonth": "12", "expirationYear": "2031", "type": "visa" }, "billTo": { "firstName": "John", "lastName": "Doe", "company": "Visa", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "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": "411111XXXXXX1111" }, "processingInformation": { "authorizationOptions": { "initiator": { "merchantInitiatedTransaction": { "previousTransactionId": "123456789619999" } } } }, "metadata": { "creator": "testrest" } } } }, { "_links": { "self": { "href": "/tms/v1/paymentinstruments/F4D5E70505B30CF9E053AF598E0A005F" }, "customer": { "href": "/tms/v1/customers/F4D5E70505B40CF9E053AF598E0A005F" } }, "id": "F4D5E70505B30CF9E053AF598E0A005F", "object": "paymentInstrument", "state": "ACTIVE", "card": { "expirationMonth": "02", "expirationYear": "2024", "type": "visa" }, "buyerInformation": { "currency": "USD" }, "billTo": { "firstName": "NOREAL", "lastName": "NAME", "address1": "1295 Charleston Road", "locality": "Mountain View", "administrativeArea": "CA", "postalCode": "94043", "country": "US", "email": "[email protected]" }, "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": "411111XXXXXX1111" }, "processingInformation": { "authorizationOptions": { "initiator": { "merchantInitiatedTransaction": { "previousTransactionId": "123456789619999" } } } }, "metadata": { "creator": "testrest" } } } }, { "_links": { "self": { "href": "/tms/v1/paymentinstruments/F4D566EED6D369CCE053AF598E0A495B" }, "customer": { "href": "/tms/v1/customers/F4D5523603862EE0E053AF598E0AE5FE" } }, "id": "F4D566EED6D369CCE053AF598E0A495B", "object": "paymentInstrument", "state": "ACTIVE", "card": { "expirationMonth": "12", "expirationYear": "2031", "type": "visa" }, "buyerInformation": { "currency": "USD" }, "billTo": { "firstName": "JOHN", "lastName": "DOE", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "", "phoneNumber": "4158880000" }, "processingInformation": { "billPaymentProgramEnabled": false }, "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": "411111XXXXXX1111" }, "processingInformation": { "authorizationOptions": { "initiator": { "merchantInitiatedTransaction": { "previousTransactionId": "123456789619999" } } } }, "metadata": { "creator": "testrest" } } } }, { "_links": { "self": { "href": "/tms/v1/paymentinstruments/F4CDBDD6E0A57EC9E053AF598E0AB69F" }, "customer": { "href": "/tms/v1/customers/F4CDBCA630247B2EE053AF598E0ADC91" } }, "id": "F4CDBDD6E0A57EC9E053AF598E0AB69F", "object": "paymentInstrument", "state": "ACTIVE", "card": { "expirationMonth": "12", "expirationYear": "2034", "type": "visa" }, "buyerInformation": { "currency": "USD" }, "billTo": { "firstName": "JOHN", "lastName": "DOE", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "", "phoneNumber": "4158880000" }, "processingInformation": { "billPaymentProgramEnabled": false }, "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": "411111XXXXXX1111" }, "processingInformation": { "authorizationOptions": { "initiator": { "merchantInitiatedTransaction": { "previousTransactionId": "123456789619999" } } } }, "metadata": { "creator": "testrest" } } } }, { "_links": { "self": { "href": "/tms/v1/paymentinstruments/F4CDEF212EAA0B13E053AF598E0AB8F4" }, "customer": { "href": "/tms/v1/customers/F4CDBCA630247B2EE053AF598E0ADC91" } }, "id": "F4CDEF212EAA0B13E053AF598E0AB8F4", "object": "paymentInstrument", "state": "ACTIVE", "card": { "expirationMonth": "12", "expirationYear": "2031", "type": "visa" }, "buyerInformation": { "currency": "USD" }, "billTo": { "firstName": "JOHN", "lastName": "DOE", "address1": "1 Market St", "locality": "san francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "email": "", "phoneNumber": "4158880000" }, "processingInformation": { "billPaymentProgramEnabled": false }, "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": "411111XXXXXX1111" }, "processingInformation": { "authorizationOptions": { "initiator": { "merchantInitiatedTransaction": { "previousTransactionId": "123456789619999" } } } }, "metadata": { "creator": "testrest" } } } } ] }}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}
PATCH /tms/v1/paymentinstruments/{paymentInstrumentTokenId}
PATCH /tms/v1/paymentinstruments/{paymentInstrumentTokenId}
PATCH /tms/v1/paymentinstruments/{paymentInstrumentTokenId}
PATCH /tms/v1/paymentinstruments/{paymentInstrumentTokenId}
Optional Fields for Update a 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.
default
Set to true if this is the default payment instrument; false otherwise.
merchantInformation.merchantDescriptor.alternateName
Alternate name for the merchant descriptor.
processingInformation.bankTransferOptions.SECCode
Standard Entry Class (SEC) code for bank transfer.
processingInformation.billPaymentProgramEnabled
Set to true to enable the bill payment program.
card.tokenizedInformation.requestorID
Token requestor ID for the tokenized card.
card.tokenizedInformation.transactionType
Transaction type for the tokenized card.
Example
{ "card": { "expirationMonth": "12", "expirationYear": "2031", "type": "visa" }, "billTo": { "firstName": "John", "lastName": "Doe", "company": "Company Name", "address1": "1 Market St", "address2": "Unit B", "locality": "San Francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "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", "address2": "Unit B", "locality": "San Francisco", "administrativeArea": "CA", "postalCode": "94105", "country": "US", "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" } } }}Delete a Payment Instrument
Endpoint
DELETE /tms/v1/paymentinstruments/{paymentInstrumentTokenId}
DELETE /tms/v1/paymentinstruments/{paymentInstrumentTokenId}
DELETE /tms/v1/paymentinstruments/{paymentInstrumentTokenId}
DELETE /tms/v1/paymentinstruments/{paymentInstrumentTokenId}
DELETE /tms/v1/paymentinstruments/{paymentInstrumentTokenId}
The {paymentInstrumentTokenId} is the payment instrument token ID you want to delete. For more information, see Create a Payment Instrument.
Thanks for your feedback!
Last published: October 28, 2026