Payment Instrument Tokens

The payment instrument token contains the complete billing details for the payment type including cardholder name, expiration date, and billing address. These are standalone payment instruments that cannot be associated with a customer.

Manage Payment Instrument Tokens

This section contains information on managing payment instrument tokens.

You can create, retrieve, update, or delete an instrument identifier by submitting an HTTP POST,

GET

PATCH

, or

DELETE

operation to the

tms/v1/paymentinstruments

endpoint. Use the TMS REST API payment instrument endpoint to:

Create a payment instrument token

Retrieve a payment instrument token

Update a payment instrument

Delete a payment instrument

For more information on payment instrument tokens, see Payment Instrument Tokens.

Create a Payment Instrument

This section shows you how to create a payment instrument token.

Endpoint

Test:

POST https://apitest.cybersource.com/tms/v1/paymentinstruments

Production:

POST https://api.cybersource.com/tms/v1/paymentinstruments

Production in India:

POST https://api.in.cybersource.com/tms/v1/paymentinstruments

Retrieve a Payment Instrument

This section shows you how to retrieve a payment instrument token.

Endpoint

Test:

GET https://apitest.cybersource.com/tms/v1/paymentinstruments/
{paymentInstrumentTokenId}

Production:

GET https://api.cybersource.com/tms/v1/paymentinstruments/
{paymentInstrumentTokenId}

Production in India:

GET https://api.in.cybersource.com/tms/v1/paymentinstruments/
{paymentInstrumentTokenId}

The

{paymentInstrumentTokenId}

is the payment instrument token ID you want to retrieve. For more information, see Create a Payment Instrument.

Find Payment Instruments by Card Number

This section shows you how to find payment instruments by card number.

Endpoint

Test:

GET https://apitest.cybersource.com/tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}/paymentinstruments?offset=0&limit=20

Production:

GET https://api.cybersource.com/tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}/paymentinstruments?offset=0&limit=20

Production in India:

GET https://api.in.cybersource.com/tms/v1/instrumentidentifiers/{instrumentIdentifierTokenId}/paymentinstruments?offset=0&limit=20

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 a Payment Instrument with an Unmasked Card Number

This section shows you how to retrieve a payment instrument 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/paymentinstruments/
{paymentInstrumentTokenId}

Production:

GET https://api.cybersource.com/tms/v1/paymentinstruments/
{paymentInstrumentTokenId}

Production in India:

GET https://api.in.cybersource.com/tms/v1/paymentinstruments/
{paymentInstrumentTokenId}

The

{paymentInstrumentTokenId}

is the payment instrument token ID you want to retrieve. For more information, see Create a Payment Instrument.

Update a Payment Instrument

This section shows you how to update a payment instrument token.

Endpoint

Test:

PATCH https://apitest.cybersource.com/tms/v1/paymentinstruments/
{paymentInstrumentTokenId}

Production:

PATCH https://api.cybersource.com/tms/v1/paymentinstruments/
{paymentInstrumentTokenId}

Production in India:

PATCH https://api.in.cybersource.com/tms/v1/paymentinstruments/
{paymentInstrumentTokenId}

The

{paymentInstrumentTokenId}

is the payment instrument token ID you want to retrieve. For more information, see Create a Payment Instrument.

Delete a Payment Instrument

This section shows you how to delete a payment instrument token.

Endpoint

Test:

DELETE https://apitest.cybersource.com/tms/v1/paymentinstruments/
{paymentInstrumentTokenId}

Production:

DELETE https://api.cybersource.com/tms/v1/paymentinstruments/
{paymentInstrumentTokenId}

Production in India:

DELETE https://api.in.cybersource.com/tms/v1/paymentinstruments/
{paymentInstrumentTokenId}

The

{paymentInstrumentTokenId}

is the payment instrument token ID you want to retrieve. For more information, see Create a Payment Instrument.

Payments with Payment Instrument Tokens

This section contains information on making payments with payment instrument tokens.

A payment instrument represents a means of payment and a payment instrument token stores this information using an instrument identifier token. It does not store the card number and cannot exist without an associated instrument identifier. It can include an instrument identifier, expiration date, billing address, and card type. In the case of non-network token transactions, you can use card or bank account information fields with a payment instrument to make a payment transaction.

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

paymentInformation.paymentInstrument.id

field. For example:

Authorizing a Payment with a Payment Instrument

Making a Credit with a Payment Instrument

For more information on payment instrument tokens, see Payment Instrument Tokens.

Authorizing a Payment with a Payment Instrument

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

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 a Payment Instrument

This section shows you how to make a credit with a payment instrument.

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