Customer Tokens

The customer token contains data about the merchant's customer including email address, customer ID, shipping address (stored in a token), and other related fields.

Manage Customer Tokens

This section contains information on managing customer tokens.

The customer token represents customer-related information including details for a payment card

or electronic check

, billing address, shipping address, and merchant defined data. You can create, retrieve, update, or delete a customer by submitting an HTTP

POST

GET

PATCH

, or

DELETE

operation to the

tms/v2/customers

endpoint. Use the TMS REST API to:

Create a customer token

Retrieve a customer token

Update a customer's information

Delete a customer token

For more information on customer tokens, see Customer Tokens.

Create a Customer

This section shows you how to create a customer token with no payment details.

Endpoint

Test:

POST https://apitest.cybersource.com/tms/v2/customers

Production:

POST https://api.cybersource.com/tms/v2/customers

Production in India:

POST https://api.in.cybersource.com/tms/v2/customers

Retrieve a Customer

This section shows you how to retrieve a customer token.

Endpoint

Test:

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

Production:

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

Production in India:

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

The

{customerTokenId}

is the customer token ID returned in the

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

Update a Customer

This section shows you how to update a customer token.

Endpoint

Test:

PATCH https://apitest.cybersource.com/tms/v2/customers/
{customerTokenId}

Production:

PATCH https://api.cybersource.com/tms/v2/customers/
{customerTokenId}

Production in India:

PATCH https://api.in.cybersource.com/tms/v2/customers/
{customerTokenId}

The

{customerTokenId}

is the customer token ID returned in the

field when you created the customer token. For more information, see Create a Customer. Include only the fields you want to add or update in the request.

Delete a Customer

This section shows you how to delete a customer token.

Endpoint

Test:

DELETE https://apitest.cybersource.com/tms/v2/customers/
{customerTokenId}

Production:

DELETE https://api.cybersource.com/tms/v2/customers/
{customerTokenId}

Production in India:

DELETE https://api.in.cybersource.com/tms/v2/customers/
{customerTokenId}

The

{customerTokenId}

is the customer token ID returned in the

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

Retrieve a Customer's Default Payment with an Unmasked Card Number

This section shows you how to retrieve a customer's default payment 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/v2/customers/
{customerTokenId}

Production:

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

Production in India:

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

The

{customerTokenId}

is the customer token ID returned in the

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

Retrieve a Customer's Default Payment and Shipping Details

This section shows you how to retrieve a customer's default payment and shipping details.

Endpoint

Test:

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

Production:

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

Production in India:

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

The

{customerTokenId}

is the customer token ID returned in the

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

Payments with Customer Tokens

This section contains information on making payments with customer tokens.

The customer token represents customer-related information including details for a payment card

or electronic check

, billing address, shipping address, and merchant defined data.

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

Create a Customer Token with Validated Payment Details

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

paymentInformation.customer.id

field. For example:

Authorizing a Payment with a Customer Token

Making a Credit with a Customer Token

For more information on customer tokens, see Customer Tokens.

Create a Customer Token with Validated Payment Details

This section shows you how to create a customer 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

Authorizing a Payment with a Customer Token

This section provides the information you need to authorize a payment with a customer 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 a Customer Token

This section shows you how to make a credit with a customer token.

Endpoint

Test:

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

Production:

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

Production in India:

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