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

{  "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"  }}

Required Fields for Create an Instrument Identifier

card.number string

Primary account number.

Optional Fields for Create an Instrument Identifier

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.

This example creates a bank account instrument identifier:

{  "bankAccount": {    "number": "4100",    "routingNumber": "X71923284"  }}

{  "_links": {    "self": {      "href": "/tms/v1/instrumentidentifiers/A7A91A2CA872B272E05340588D0A0699"    },    "paymentInstruments": {      "href": "/tms/v1/instrumentidentifiers/A7A91A2CA872B272E05340588D0A0699/paymentinstruments"    }  },  "id": "A7A91A2CA872B272E05340588D0A0699",  "object": "instrumentIdentifier",  "state": "ACTIVE",  "bankAccount": {    "number": "XXXX",    "routingNumber": "X71923284"  },  "metadata": {    "creator": "testrest"  }}

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

You must set the Content-Type request header to application/jose.

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"  }}

Required Fields for Create an Instrument Identifier for Enrollable Network Tokens

card.number string

Tokenized card number from the device.

type string

Set to enrollable token.

Optional Fields for Create an Instrument Identifier for Enrollable Network Tokens

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 and Network Token Using EMV Tags

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

Required Fields for Create an Instrument Identifier and Network Token Using EMV Tags

type string

Set to enrollable card when you are provisioning a network token.

pointOfSaleInformation.emvTags.tag string

The EMV tag captured from the card tap.

pointOfSaleInformation.emvTags.value string

The value of the EMV tag captured from the card tap.

pointOfSaleInformation.emvTags.source string

Set to one of these values: CARD, TERMINAL.

Optional Fields for Create an Instrument Identifier and Network Token Using EMV Tags

card.securityCode string

Card security code (CVV).

These examples include the minimum required EMV tags for card information. You can include more EMV tags for the card tap in your request.

{  "pointOfSaleInformation": {    "emvTags": [      {        "tag": "5A",        "value": "4111111111111111",        "source": "CARD"      }    ]  }}

{  "pointOfSaleInformation": {    "emvTags": [      {        "tag": "57",        "value": "4111111111111111D30092011234567890F",        "source": "CARD"      }    ]  }}

{  "type": "enrollable card",  "card": {    "securityCode": "123"  },  "pointOfSaleInformation": {    "emvTags": [      {        "tag": "5A",        "value": "4111111111111111",        "source": "CARD"      },      {        "tag": "5F24",        "value": "YYMMDD",        "source": "CARD"      }    ]  }}

{  "type": "enrollable card",  "card": {    "securityCode": "123"  },  "pointOfSaleInformation": {    "emvTags": [      {        "tag": "57",        "value": "4111111111111111D30092011234567890F",        "source": "CARD"      }    ]  }}

{  "type": "enrollable card",  "source": "CONTACTLESS",  "card": {    "securityCode": "123"  },  "pointOfSaleInformation": {    "emvTags": [      {        "tag": "5A",        "value": "4111111111111111",        "source": "CARD"      },      {        "tag": "5F24",        "value": "YYMMDD",        "source": "CARD"      },      {        "tag": "57",        "value": "4111111111111111D30092011234567890F",        "source": "CARD"      },      {        "tag": "9F35",        "value": "22",        "source": "TERMINAL"      }    ]  }}

{  "id": "7030080000051311515",  "object": "instrumentIdentifier",  "state": "ACTIVE",  "tokenizedCard": {    "id": "09CBCE20D414BB07E063AF598E0A4F1F",    "state": "ACTIVE",    "enrollmentId": "93e7ccff2d64fb4500b4158e45059d02",    "tokenReferenceId": "5eaec012172e13a9aabd19549bde5a02",    "paymentAccountReference": "V0010013019326121174070050420",    "number": "489537XXXXXX0711",    "expirationMonth": "09",    "expirationYear": "2030",    "type": "visa",    "card": {      "suffix": "1111",      "expirationMonth": "09",      "expirationYear": "2030",      "issueDate": "2025-01-01",      "activationDate": "2025-01-01",      "expirationPrinted": "Y",      "securityCodePrinted": "Y",      "termsAndConditions": {        "id": "09CBCE20D414BB07E063AF598E0A4F1F",        "url": "<cardMetaData.contactWebsite>"      }    },    "metadata": {      "cardArt": {        "combinedAsset": {          "id": "84cfb836af434859be62c766bdc9e510",          "_links": {            "self": {              "href": "/tms/v2/tokens/7030080000051311515/vts/assets/card-art-combined"            }          }        }      },      "issuer": {        "name": "issuing bank name",        "shortDescription": "The Bank Card",        "longDescription": "The Bank Card Platinum Rewards",        "country": "Country of issuing Bank",        "accountPrefix": "BIN",        "email": "[email protected]",        "phoneNumber": "1112223333",        "url": "http://www.example.com"      }    }  },  "card": {    "number": "489537XXXXXX1515"  },  "issuer": {    "paymentAccountReference": "V0010013019326121174070050420"  },  "metadata": {    "creator": "creator"  }}

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}

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.

{  "_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

You can include these query parameters in the request:

offset: Page offset number.
limit: Maximum number of items you would like returned.

GET /tms/v1/instrumentidentifiers/7010000000016241111/paymentinstruments?offset=0&limit=5

{  "_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=120820&limit=5"    }  },  "object": "collection",  "offset": 0,  "limit": 5,  "count": 5,  "total": 120825,  "_embedded": {    "paymentInstruments": [      {        "_links": {          "self": {            "href": "/tms/v1/paymentinstruments/F396A4DD49CA23ADE053A2598D0AECC4"          },          "customer": {            "href": "/tms/v1/customers/F396A4DD49CB23ADE053A2598D0AECC4"          }        },        "id": "F396A4DD49CA23ADE053A2598D0AECC4",        "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": "123456789012345"                  }                }              }            },            "metadata": {              "creator": "testrest"            }          }        }      },      {        "_links": {          "self": {            "href": "/tms/v1/paymentinstruments/F3969009C44DED0DE053AF598E0AD4E0"          },          "customer": {            "href": "/tms/v1/customers/F396A109D27377A5E053AF598E0AA34A"          }        },        "id": "F3969009C44DED0DE053AF598E0AD4E0",        "object": "paymentInstrument",        "state": "ACTIVE",        "card": {          "type": "visa"        },        "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": "123456789012345"                  }                }              }            },            "metadata": {              "creator": "testrest"            }          }        }      },      {        "_links": {          "self": {            "href": "/tms/v1/paymentinstruments/F396A109F3637776E053AF598E0A87E4"          },          "customer": {            "href": "/tms/v1/customers/F396A109D27377A5E053AF598E0AA34A"          }        },        "id": "F396A109F3637776E053AF598E0A87E4",        "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": "411111XXXXXX1111"            },            "processingInformation": {              "authorizationOptions": {                "initiator": {                  "merchantInitiatedTransaction": {                    "previousTransactionId": "123456789012345"                  }                }              }            },            "metadata": {              "creator": "testrest"            }          }        }      },      {        "_links": {          "self": {            "href": "/tms/v1/paymentinstruments/F3965253C47640F5E053AF598E0AA05A"          }        },        "id": "F3965253C47640F5E053AF598E0AA05A",        "object": "paymentInstrument",        "state": "ACTIVE",        "card": {          "expirationMonth": "02",          "expirationYear": "2028",          "type": "visa"        },        "billTo": {          "firstName": "John",          "lastName": "Snow"        },        "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": "123456789012345"                  }                }              }            },            "metadata": {              "creator": "testrest"            }          }        }      },      {        "_links": {          "self": {            "href": "/tms/v1/paymentinstruments/F395F6426D9A30AEE053AF598E0A5BD4"          }        },        "id": "F395F6426D9A30AEE053AF598E0A5BD4",        "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": "411111XXXXXX1111"            },            "processingInformation": {              "authorizationOptions": {                "initiator": {                  "merchantInitiatedTransaction": {                    "previousTransactionId": "123456789012345"                  }                }              }            },            "metadata": {              "creator": "testrest"            }          }        }      }    ]  }}

Retrieve an Instrument Identifier with an Unmasked Card Number

This section describes how to retrieve an instrument identifier with an unmasked card number.

Endpoint

GET /tms/v1/instrumentidentifiers/{id}

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 payment details

Header 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).

Example

GET /tms/v1/instrumentidentifiers/7010000000016241111

eyJraWQiOiJiYTE1ZDRmMTIzMTM0NjlkZjg5MDM1Nzk2YWE4Nzc4ZGM0NTY4ODlkIiwiY3R5IjoianNvbiIsInR5cCI6IkpXVCIsImVuYyI6IkEyNTZHQ00iLCJhbGciOiJSU0EtT0FFUC0yNTYifQ...

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}

{  "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 for Update an Instrument Identifier

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, 2031.

card.securityCode string

Card security code (CVV).

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}

The {id} is the instrument identifier token ID you want to delete.

Provision a Network Token for an Existing Instrument Identifier

This section describes how to provision a network token for an existing instrument identifier.

Endpoint

POST /tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}/enrollment

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

{  "type": "enrollable card",  "card": {    "expirationMonth": "12",    "expirationYear": "2031",    "securityCode": "089"  }}

Required Fields for Provision a Network Token for an Existing Instrument Identifier

card.expirationMonth string

The expiration month of the card.

card.expirationYear string

The expiration year of the card.

instrumentIdentifierTokenId string

Include the ID of the instrument identifier token you want to retrieve in the URL path.

type string

Set to enrollable card.

Optional Fields for Provision a Network Token for an Existing Instrument Identifier

card.securityCode string

The card verification number.

Was this page helpful?

Last published: October 28, 2026

Create an Instrument Identifier

Endpoint

Create an Instrument Identifier for Enrollable Network Tokens

Endpoint

Create an Instrument Identifier and Network Token Using EMV Tags

Endpoint

Retrieve an Instrument Identifier

Endpoint

Retrieve an Instrument Identifier's Payment Instruments

Endpoint

Retrieve an Instrument Identifier with an Unmasked Card Number

Endpoint

Header Configuration

Example

Update an Instrument Identifier

Endpoint

Delete an Instrument Identifier

Endpoint

Provision a Network Token for an Existing Instrument Identifier

Endpoint

Not available for your audience