Customer Payment Instrument Tokens

Customer payment instruments are payment instruments that are linked to a specific customer token. Supported payment instruments include payment cards, tokenized cards (Apple Pay and Android Pay), or ACH bank accounts.

Manage Customer Payment Instrument Tokens

This section contains information on managing customer payment instrument tokens.

Customer payment instruments are payment instruments that are linked to a specific customer token. The following payment instruments are supported:

Payment card

Tokenized card (Apple Pay and Android Pay)

ACH bank account

You can create, retrieve, update, or delete a payment instrument by submitting an HTTP

POST

GET

PATCH

, or

DELETE

operation to the

tms/v2/customers/
{customerTokenId}
/payment-instruments

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

Create a customer payment instrument token

Retrieve a customer payment instrument token

Update a customer payment instrument

Delete a customer payment instrument

For more information on customer tokens and payment instrument tokens, see Customer Tokens and Payment Instrument Tokens, respectively.

Create a Customer Payment Instrument

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

Endpoint

Test:

POST https://apitest.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments

Production:

POST https://api.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments

Production in India:

POST https://api.in.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments

The

{customerTokenId}

is the customer token ID returned in the

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

Add a Default Payment Instrument Using Instrument Identifier

This section shows you how add a default payment instrument using an instrument identifier.

Endpoint

Test:

POST https://apitest.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments

Production:

POST https://api.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments

Production in India:

POST https://api.in.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments

The

{customerTokenId}

is the customer token ID returned in the

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

Add a Default Payment Instrument with Validated Payment

This section shows you how to add a default payment instrument with a validated payment method.

Endpoint

Test:

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

Production:

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

Production in India:

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

Add a Non-Default Payment Instrument Using Instrument Identifier

This section shows you how to add a non-default payment instrument using instrument identifier.

Endpoint

Test:

POST https://apitest.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments/
{paymentInstrumentTokenId}

Production:

POST https://api.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments/
{paymentInstrumentTokenId}

Production in India:

POST https://api.in.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments/
{paymentInstrumentTokenId}

The

{customerTokenId}

is the customer token ID returned in the

field when you created the customer token. The

{paymentInstrumentTokenId}

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

Add a Non-Default Payment Instrument with Validated Payment

This section shows you how to add a non-default payment instrument with a validated payment.

Endpoint

Test:

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

Production:

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

Production in India:

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

The

{customerTokenId}

is the customer token ID returned in the

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

Change a Customer's Default Payment Instrument

This section shows you how to change a customer's default payment instrument.

Endpoint

Test:

PATCH https://apitest.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments/
{paymentInstrumentTokenId}

Production:

PATCH https://api.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments/
{paymentInstrumentTokenId}

Production in India:

PATCH https://api.in.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments/
{paymentInstrumentTokenId}

The

{customerTokenId}

is the customer token ID returned in the

Retrieve a Customer Payment Instrument

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

Endpoint

Test:

GET https://apitest.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments/
{paymentInstrumentTokenId}

Production:

GET https://api.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments/
{paymentInstrumentTokenId}

Production in India:

GET https://api.in.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments/
{paymentInstrumentTokenId}

The

{customerTokenId}

is the customer token ID returned in the

Retrieve a Customer Payment Instrument with Unmasked Card Number

This section shows you how to retrieve a payment instrument with unmasked card number.

Endpoint

Test:

GET https://apitest.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments/
{paymentInstrumentTokenId}

Production:

GET https://api.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments/
{paymentInstrumentTokenId}

Production in India:

GET https://api.in.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments/
{paymentInstrumentTokenId}

The

{customerTokenId}

is the customer token ID returned in the

IMPORTANT

You must pass the following request header to get this functionality:

Accept: application/jose

List Payment Instruments for a Customer

This section shows you how to retrieve a customer's payment instruments.

Endpoint

Test:

GET https://apitest.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments

Production:

GET https://api.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments

Production in India:

GET https://api.in.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments

The

{customerTokenId}

is the customer token ID returned in the

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

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.

Update a Customer Payment Instrument

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

Endpoint

Test:

PATCH https://apitest.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments/
{paymentInstrumentTokenId}

Production:

PATCH https://api.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments/
{paymentInstrumentTokenId}

Production in India:

PATCH https://api.in.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments/
{paymentInstrumentTokenId}

The

{customerTokenId}

is the customer token ID returned in the

Delete a Customer Payment Instrument

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

Endpoint

Test:

DELETE https://apitest.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments/
{paymentInstrumentTokenId}

Production:

DELETE https://api.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments/
{paymentInstrumentTokenId}

Production in India:

DELETE https://api.in.cybersource.com/tms/v2/customers/
{customerTokenId}
/payment-instruments/
{paymentInstrumentTokenId}

The

{customerTokenId}

is the customer token ID returned in the

IMPORTANT

If you have more than one payment Instrument, then the default payment Instrument cannot be deleted without first selecting a new default payment instrument.

Payments with Customer Payment Instrument Tokens

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

Customer payment instruments are payment instruments that are linked to a specific customer token. The following payment instruments are supported:

Payment card

Tokenized card (Apple Pay and Android Pay)

ACH bank account

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. You can make payments using non-default payment instruments associated with the customer. For example:

Authorizing a Payment with a Non-Default Payment Instrument

Making a Credit with a Non-Default Payment Instrument

For more information on customer tokens and payment instrument tokens, see Customer Tokens and Payment Instrument Tokens, respectively.

Authorizing a Payment with a Non-Default Payment Instrument

This section provides the information you need in order to authorize a payment with a non-default 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 Non-Default Payment Instrument

This section shows you how to make a credit with a non-default 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