Create an Instrument Identifier for Enrollable Network Tokens

IMPORTANT
To create an instrument identifier for an enrollable network token using the
Token Management Service
(
TMS
), you must send the request using message-level encryption (MLE). For more information about MLE, see Message-Level Encryption Keys.
TMS
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:
  • Android 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

Test:
POST
https://apitest.cybersource.com
/tms/v1/instrumentidentifiers
Production:
POST
https://api.cybersource.com
/tms/v1/instrumentidentifiers
Production in India:
POST
https://api.in.cybersource.com
/tms/v1/instrumentidentifiers

Header

Set the component type in the request header to
application/jose
.

Response to a Successful Request

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.
Cybersource
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
Cybersource
Reason Codes with REST API response
article.

Merchant-Initiated Transactions

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. For more information about how to create an instrument identifier within an authorization request, see these sections in the
Payments Developer Guide
:

Required Fields for Creating an Instrument Identifier for a Device Token

card.number
type
Set to
enrollable token
.
Create an Instrument Identifier for Enrollable Network Tokens

Optional Fields for Creating an Instrument Identifier

bankAccount.number
bankAccount.routingNumber
billTo.address1
billTo.address2
billTo.administrativeArea
billTo.country
billTo.locality
billTo.postalCode
card.expirationMonth
card.expirationYear
card.securityCode
processingInformation.authorizationOptions.initiator. merchantInitiatedTransaction.previousTransactionID
Create an Instrument Identifier for Enrollable Network Tokens

REST Example: Creating an Instrument Identifier for a Device Token

Request
{ "type": "enrollable token", "card": { "number": "41111XXXX1111111" } }
Response to a Successful Request
{ "_links": { "self": { "href": "
https://apitest.cybersource.com
/tms/v1/instrumentidentifiers/7030000000014911515" }, "paymentInstruments": { "href": "
https://apitest.cybersource.com
/tms/v1/instrumentidentifiers/7030000000014911515/paymentinstruments" } }, "id": "7040000000015027161", "object": "instrumentIdentifier", "state": "ACTIVE", "tokenizedCard": { "source": "TOKEN", "state": "ACTIVE", "enrollmentId": "da1fb810b1b3e01db5b215de5261df01", "tokenReferenceId": "090673c4811a91960f021ad3a24e2e01", "number": "41111XXXX1111111", "type": "visa", "card": { "suffix": "1111" } }, "card": { "number": "41111XXXX1111111" }, "issuer": { "paymentAccountReference": "V0010013024026372674590402581" }, "metadata": { "creator": "testrest" } }
Create an Instrument Identifier for Enrollable Network Tokens