Instrument Identifier Tokens

Instrument identifier tokens represent tokenized payment account numbers. This includes primary account number (PAN) for card payments, or U.S. or Canadian bank account number and routing number for an ACH bank account. An instrument identifier token can exist independently or it can be associated with a payment instrument.

An instrument identifier token can also contain an associated network token.

Instrument identifier tokens are associated with in these features:

Card Art: Display card art is provided by TMS to help your customers identify a card to select. See Card Art.
Enrollable Network Tokens: TMS can enroll certain network tokens
in an instrument identifier token to be used for future payments. Future payments require only the instrument identifier token for the payment information. The types of network tokens you can enroll into an instrument identifier are tokens used for in-app payment methods such as:
Android Pay
Apple Pay
Chase Pay
Google Pay
Samsung Pay
Visa Click to Pay
See Create an Instrument Identifier for Enrollable Network Tokens.

Manage Instrument Identifier Tokens

This section contains information on managing instrument identifier tokens.

The instrument identifier token type represents the tokenized Primary Account Number (PAN) for card payments, or U.S. or Canadian bank account number and routing number. An instrument identifier can contain a credit card, ACH bank account, or tokenized card such as Apple Pay or Android Pay. You can create, retrieve, update, or delete an instrument identifier by submitting an HTTP

POST

GET

PATCH

, or

DELETE

operation to the

/tms/v1/instrumentidentifiers

endpoint.

Use the TMS REST API instrument identifier endpoint to:

Create an instrument identifier token

Retrieve an instrument identifier token

Update an instrument identifier

Delete an instrument identifier

List payment instruments for an instrument identifier

For more information on instrument identifier tokens, see Instrument Identifier Tokens.

Create an Instrument Identifier

This section shows you how to create an instrument identifier.

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

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

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
:

Installment Payments

Recurring Payments

Unscheduled COF Payments

Retrieve an Instrument Identifier

This section shows you how to retrieve an instrument identifier.

Endpoint

Test:

GET https://apitest.cybersource.com/tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}

Production:

GET https://api.cybersource.com/tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}

Production in India:

GET https://api.in.cybersource.com/tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}

{instrumentIdentifierTokenId}

is the instrument identifier token ID returned in the

field when you created the instrument identifier token. For more information, see Create an Instrument Identifier.

Update an Instrument Identifier

This section shows you how to update an instrument identifier.

Endpoint

Test:

PATCH https://apitest.cybersource.com/tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}

Production:

PATCH https://api.cybersource.com/tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}

Production in India:

PATCH https://api.in.cybersource.com/tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}

{instrumentIdentifierTokenId}

is the instrument identifier token ID returned in the

field when you created the instrument identifier token. For more information, see Create an Instrument Identifier.

Retrieve an Instrument Identifier's Payment Instruments

This section shows you how to retrieve the payment instrument tokens associated with an instrument identifier token.

Endpoint

Test:

GET https://apitest.cybersource.com/tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}/paymentinstruments?

Production:

GET https://api.cybersource.com/tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}/paymentinstruments?

Production in India:

GET https://api.in.cybersource.com/tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}/paymentinstruments?

{instrumentIdentifierTokenId}

is the instrument identifier token ID returned in the

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.

Retrieve an Instrument Identifier with an Unmasked Card Number

This section shows you how retrieve an instrument identifier with an unmasked card number.

IMPORTANT

To retrieve unmasked payment details, you must ensure that your MLE key pair and your token vault are configured correctly. For more information on MLE keys, see Message-Level Encryption Keys. For more information on token vaults, see Token Vault Management. If necessary, contact your Cybersource account manager or customer support.

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
} 
 //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).

Endpoint

Test:

GET https://apitest.cybersource.com/tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}

Production:

GET https://api.cybersource.com/tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}

Production in India:

GET https://api.in.cybersource.com/tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}

{instrumentIdentifierTokenId}

is the instrument identifier token ID returned in the

field when you created the instrument identifier token. For more information, see Create an Instrument Identifier.

Delete an Instrument Identifier

This section shows you how to delete an instrument identifier.

Endpoint

Test:

DELETE https://apitest.cybersource.com/tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}

Production:

DELETE https://api.cybersource.com/tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}

Production in India:

DELETE https://api.in.cybersource.com/tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}

{instrumentIdentifierTokenId}

is the instrument identifier token ID returned in the

field in the

field when you created the instrument identifier token. For more information, see Create an Instrument Identifier.

Payments with Instrument Identifier Tokens

This section contains information on making payments using instrument identifier tokens.

An instrument identifier token represents either a payment card number or, in the case of an ACH bank account, the routing and account numbers. The expiration date and billing address fields are pass through fields. The pass-through fields are used for payment network token enrollment with card associations.

You can make a payment using an existing instrument identifier token or create one. To make a payment using a new instrument identifier token, you must include token creation in the authorization request. For example:

Create an Instrument Identifier Token with Validated Payment Details

To process a payment using an existing instrument identifier token, you must include the instrument identifier token ID as the value in the

paymentInformation.instrumentIdentifier.id

field. For example:

Authorize a Payment with an Instrument Identifier

Making a Credit with an Instrument Identifier

For more information on instrument identifier tokens, see Instrument Identifier Tokens.

Create an Instrument Identifier Token with Validated Payment Details

This section shows you how to create a instrument identifier token with validated payment details.

Endpoint

Test:

POST https://apitest.cybersource.com/pts/v2/payments

Production:

POST https://api.cybersource.com/pts/v2/payments

Production in India:

POST https://api.in.cybersource.com/pts/v2/payments

customerTokenId

is the customer tokenID returned in the

field when you created the customer token. For more information, see Create a Customer.

Authorize a Payment with an Instrument Identifier

This section provides the information you need in order to authorize a payment with an instrument identifier token.

Endpoint

Production:

POST https://api.cybersource.com/pts/v2/payments

Test:

POST https://apitest.cybersource.com/pts/v2/payments

Production in India:

POST https://api.in.cybersource.com/pts/v2/payments

Making a Credit with an Instrument Identifier

This section shows you how to make a credit with an instrument identifier token.

Endpoint

Test:

POST https://apitest.cybersource.com/pts/v2/credits

Production:

POST https://api.cybersource.compts/v2/credits

Production in India:

POST https://api.in.cybersource.compts/v2/credits