Manage Instrument Identifier Tokens
This page describes how to create, retrieve, update, and delete instrument identifier tokens, including how to create one from an enrollable network token or a tap to add card operation, and how to provision a network token for an existing instrument identifier.
Create an Instrument Identifier
This section describes how to create an instrument identifier.
Endpoint
POST /tms/v1/instrumentidentifiers
POST /tms/v1/instrumentidentifiers
{ "card": { "number": "4XXXXXXXXXXX1111" }}{ "_links": { "self": { "href": "/tms/v1/instrumentidentifiers/7010000000016241111" }, "paymentInstruments": { "href": "/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstruments" } }, "id": "7010000000016241111", "object": "instrumentIdentifier", "state": "ACTIVE", "card": { "number": "411111XXXXXX1111" }, "metadata": { "creator": "testrest" }}| Field | Type | Description |
|---|---|---|
card.number | string | Primary account number. |
Optional Fields
| Field | Type | Description |
|---|---|---|
bankAccount.number | string | Bank account number. |
bankAccount.routingNumber | string | Bank routing number. |
billTo.address1 | string | Billing address line 1. |
billTo.address2 | string | Billing address line 2. |
billTo.administrativeArea | string | State or province in the billing address. |
billTo.country | string | Country of the billing address. Use the two-character ISO Standard Country Code. |
billTo.locality | string | City in the billing address. |
billTo.postalCode | string | ZIP or postal code in the billing address. |
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, 2026. |
card.securityCode | string | Card security code (CVV). |
processingInformation.authorizationOptions.initiator.merchantInitiatedTransaction.previousTransactionID | string | Previous transaction identifier. |
Create an Instrument Identifier for Enrollable Network Tokens
can enroll certain network tokens into an instrument identifier token for future payments. Any future payments will require only the instrument identifier token for the payment information.
Enrollable network tokens can be used for these in-app payment methods:
- Google Pay
- Apple Pay
- Chase Pay
- Google Pay
- Samsung Pay
- Visa Click to Pay
These tokenized payment methods are also referred to as digital payments, digital wallets, and tokenized cards.
Endpoint
POST /tms/v1/instrumentidentifiers
POST /tms/v1/instrumentidentifiers
You can create an instrument identifier that stores a device token while you are requesting an authorization. Such requests are typically performed for follow-on merchant-initiated transactions.
{ "type": "enrollable token", "card": { "number": "4XXXXXXXXXXX1111" }}{ "_links": { "self": { "href": "/tms/v1/instrumentidentifiers/7030000000014911515" }, "paymentInstruments": { "href": "/tms/v1/instrumentidentifiers/7030000000014911515/paymentinstruments" } }, "id": "7030000000014911515", "object": "instrumentIdentifier", "state": "ACTIVE", "tokenizedCard": { "source": "TOKEN", "state": "ACTIVE", "enrollmentId": "da1fb810b1b3e01db5b215de5261df01", "tokenReferenceId": "090673c4811a91960f021ad3a24e2e01", "number": "4111111111111111", "type": "visa", "card": { "suffix": "1111" }, "metadata": { "cardArt": { "combinedAsset": { "id": "8f64614def1a41d39ea8acae4616bf6f", "_links": { "self": { "href": "tms/v2/tokens/7030800000051400580/vts/assets/card-art-combined" } } }, "brandLogoAsset": { "id": "00000000000000000000000000001070", "_links": { "self": { "href": "tms/v2/tokens/7030800000051400580/vts/assets/brand-logo" } } }, "foregroundColor": "1af0f0" }, "issuer": { "name": "Test Issuer", "shortDescription": "shortDescription", "longDescription": "longDescription", "country": "US" }, "features": { "accountFundingSource": "debit card" }, "creator": "sim" } }, "card": { "number": "411111XXXXXX1111" }, "issuer": { "paymentAccountReference": "V0010013024026372674590402581" }, "metadata": { "creator": "testrest" }}| Field | Type | Description |
|---|---|---|
card.number | string | Tokenized card number from the device. |
type | string | Set to enrollable token. |
Optional Fields
| Field | Type | Description |
|---|---|---|
bankAccount.number | string | Bank account number. |
bankAccount.routingNumber | string | Bank routing number. |
billTo.address1 | string | Billing address line 1. |
billTo.address2 | string | Billing address line 2. |
billTo.administrativeArea | string | State or province in the billing address. |
billTo.country | string | Country of the billing address. Use the two-character ISO Standard Country Code. |
billTo.locality | string | City in the billing address. |
billTo.postalCode | string | ZIP or postal code in the billing address. |
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, 2026. |
card.securityCode | string | Card security code (CVV). |
processingInformation.authorizationOptions.initiator.merchantInitiatedTransaction.previousTransactionID | string | Previous transaction identifier. |
A successful response includes the instrument identifier in the id field and the TOKEN indicator in the tokenizedCard.source field. The TOKEN indicator denotes that the instrument identifier was created from a device token. A payment account reference (PAR) number is also returned in the issuer.paymentAccountReference field.
returns a reason code in the details.reason response field to indicate the reason for an API request's status. For more information about all possible reason codes, see the Reason Codes with REST API response article.
Create an Instrument Identifier Using Tap to Add Card
For in-app payment methods, you can create an instrument identifier using EMV data from a tap to add card operation. This allows you to capture payment credentials directly from a physical card via NFC technology.
Endpoint
POST /tms/v1/instrumentidentifiers
POST /tms/v1/instrumentidentifiers
| Field | Type | Description |
|---|---|---|
tokenizedCard.emvData | string | EMV data from the device tap operation. |
Optional Fields
| Field | Type | Description |
|---|---|---|
billTo.address1 | string | Billing address line 1. |
billTo.address2 | string | Billing address line 2. |
billTo.administrativeArea | string | State or province in the billing address. |
billTo.country | string | Country of the billing address. Use the two-character ISO Standard Country Code. |
billTo.locality | string | City in the billing address. |
billTo.postalCode | string | ZIP or postal code in the billing address. |
Retrieve an Instrument Identifier
You can retrieve an instrument identifier by its ID using a GET request to /tms/v1/instrumentidentifiers/{id}.
Endpoint
GET /tms/v1/instrumentidentifiers/{id}
GET /tms/v1/instrumentidentifiers/{id}
{ "_links": { "self": { "href": "/tms/v1/instrumentidentifiers/7010000000016241111" }, "paymentInstruments": { "href": "/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstruments" } }, "id": "7010000000016241111", "object": "instrumentIdentifier", "state": "ACTIVE", "card": { "number": "411111XXXXXX1111" }, "metadata": { "creator": "testrest" }}Retrieve an Instrument Identifier's Payment Instruments
You can retrieve the payment instruments associated with an instrument identifier using a GET request to /tms/v1/instrumentidentifiers/{id}/paymentinstruments.
Endpoint
GET /tms/v1/instrumentidentifiers/{id}/paymentinstruments
GET /tms/v1/instrumentidentifiers/{id}/paymentinstruments
{ "_links": { "self": { "href": "/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstruments" } }, "count": 2, "paymentInstruments": [ { "_links": { "self": { "href": "/tms/v1/paymentinstruments/7010000000016241112" } }, "id": "7010000000016241112", "object": "paymentInstrument", "type": "visa", "state": "ACTIVE" }, { "_links": { "self": { "href": "/tms/v1/paymentinstruments/7010000000016241113" } }, "id": "7010000000016241113", "object": "paymentInstrument", "type": "mastercard", "state": "ACTIVE" } ]}Retrieve an Instrument Identifier with an Unmasked Card Number
You can retrieve an instrument identifier with the unmasked card number using a GET request to /tms/v1/instrumentidentifiers/{id}?returnUnmaskedCardNumber=true. The response includes the full card number instead of the masked version.
Endpoint
GET /tms/v1/instrumentidentifiers/{id}?returnUnmaskedCardNumber=true
GET /tms/v1/instrumentidentifiers/{id}?returnUnmaskedCardNumber=true
{ "_links": { "self": { "href": "/tms/v1/instrumentidentifiers/7010000000016241111" }, "paymentInstruments": { "href": "/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstruments" } }, "id": "7010000000016241111", "object": "instrumentIdentifier", "state": "ACTIVE", "card": { "number": "4111111111111111" }, "metadata": { "creator": "testrest" }}Update an Instrument Identifier
You can update an instrument identifier using a PATCH request to /tms/v1/instrumentidentifiers/{id}.
Endpoint
PATCH /tms/v1/instrumentidentifiers/{id}
PATCH /tms/v1/instrumentidentifiers/{id}
{ "card": { "expirationMonth": "12", "expirationYear": "2031" }}{ "_links": { "self": { "href": "/tms/v1/instrumentidentifiers/7010000000016241111" }, "paymentInstruments": { "href": "/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstruments" } }, "id": "7010000000016241111", "object": "instrumentIdentifier", "state": "ACTIVE", "card": { "number": "411111XXXXXX1111", "expirationMonth": "12", "expirationYear": "2031" }, "metadata": { "creator": "testrest" }}Optional Fields
| Field | Type | Description |
|---|---|---|
billTo.address1 | string | Billing address line 1. |
billTo.address2 | string | Billing address line 2. |
billTo.administrativeArea | string | State or province in the billing address. |
billTo.country | string | Country of the billing address. Use the two-character ISO Standard Country Code. |
billTo.locality | string | City in the billing address. |
billTo.postalCode | string | ZIP or postal code in the billing address. |
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. |
Delete an Instrument Identifier
You can delete an instrument identifier using a DELETE request to /tms/v1/instrumentidentifiers/{id}.
Endpoint
DELETE /tms/v1/instrumentidentifiers/{id}
DELETE /tms/v1/instrumentidentifiers/{id}
{ "id": "7010000000016241111", "object": "instrumentIdentifier", "status": "deleted"}Provision a Network Token for an Existing Instrument Identifier
You can provision a network token for an existing instrument identifier using a POST request to /tms/v1/instrumentidentifiers/{id}/network-tokens.
Endpoint
POST /tms/v1/instrumentidentifiers/{id}/network-tokens
POST /tms/v1/instrumentidentifiers/{id}/network-tokens
{ "source": "VISA_NETWORK_TOKEN_SERVICE"}{ "id": "7010000000016241112", "object": "networkToken", "state": "ACTIVE", "source": "VISA_NETWORK_TOKEN_SERVICE", "tokenReferenceId": "090673c4811a91960f021ad3a24e2e01", "metadata": { "creator": "testrest" }}| Field | Type | Description |
|---|---|---|
source | string | The token vault provider. For example, VISA_NETWORK_TOKEN_SERVICE. |
Optional Fields
| Field | Type | Description |
|---|---|---|
enrollmentId | string | Enrollment identifier from the token service. |
metadata | object | Additional metadata for the network token. |
tokenRequestorId | string | Identifier of the entity requesting the network token. |
Thanks for your feedback!
Last published: September 29, 2026