Token Management Service

REST API

Developer Guide
© 2024. Cybersource Corporation. All rights reserved.

Cybersource Corporation (Cybersource) furnishes this document and the software described in this document under
the applicable agreement between the reader of this document (You) and Cybersource (Agreement). You may use this
document and/or software only in accordance with the terms of the Agreement. Except as expressly set forth in the
Agreement, the information contained in this document is subject to change without notice and therefore should not be
interpreted in any way as a guarantee or warranty by Cybersource. Cybersource assumes no responsibility or liability
for any errors that may appear in this document. The copyrighted software that accompanies this document is licensed
to You for use only in strict accordance with the Agreement. You should read the Agreement carefully before using the
software. Except as permitted by the Agreement, You may not reproduce any part of this document, store this document
in a retrieval system, or transmit this document, in any form or by any means, electronic, mechanical, recording, or
otherwise, without the prior written consent of Cybersource.

Restricted Rights Legends

For Government or defense agencies: Use, duplication, or disclosure by the Government or defense agencies is subject to
restrictions as set forth the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 and in similar
clauses in the FAR and NASA FAR Supplement.

For civilian agencies: Use, reproduction, or disclosure is subject to restrictions set forth in subparagraphs (a) through (d)
of the Commercial Computer Software Restricted Rights clause at 52.227-19 and the limitations set forth in Cybersource
Corporation's standard commercial agreement for this software. Unpublished rights reserved under the copyright laws of
the United States.

Trademarks

Authorize.Net, eCheck.Net, and The Power of Payment are registered trademarks of Cybersource Corporation.
Cybersource and Cybersource Decision Manager are trademarks and/or service marks of Cybersource Corporation. Visa,
Visa International, Cybersource, the Visa logo, the Cybersource logo, and 3-D Secure are the registered trademarks of
Visa International in the United States and other countries. All other trademarks, service marks, registered marks, or
registered service marks are the property of their respective owners.

Version: 24.05

Token Management Service | 2

Contents
Token Management Service............................................................................................................................. 12
Recent Revisions to This Document........................................................................................................................12
VISA Platform Connect: Specifications and Conditions for Resellers/Partners................................... 15
TERMS OF USE APPLICABLE TO CARD NETWORK TOKENS..................................................................16
Introduction to the Token Management Service...................................................................................... 18
Types of Tokens................................................................................................................................................................20
Customer Tokens....................................................................................................................................................21
Shipping Address Tokens................................................................................................................................... 21
Payment Instrument Tokens.............................................................................................................................21
Instrument Identifier Tokens............................................................................................................................22
Network Tokens......................................................................................................................................................22
Token Management Service Workflows....................................................................................................... 24
PAN Tokenization Process Using TMS....................................................................................................................25
Network Token Tokenization Process.................................................................................................................... 26
Network Token Provisioning for Merchants........................................................................................................27
Network Token CIT Authorizations for Merchants...........................................................................................30
Network Token MIT Authorizations for Merchants......................................................................................... 31
Network Token Provisioning for Partners............................................................................................................32
Network Token CIT Authorizations for Partners...............................................................................................35
Network Token MIT Authorizations for Partners............................................................................................. 37
Requesting the Token Management Service API...................................................................................... 39
HTTP Response Headers.............................................................................................................................................. 39
Case Sensitivity................................................................................................................................................................. 40
Metadata...............................................................................................................................................................................40
Patching Considerations............................................................................................................................................... 41
Pagination.................................................................................................................................................................. 46
Supported Processors.................................................................................................................................................... 51
Test Card Numbers..........................................................................................................................................................51
Token Management Service Onboarding.....................................................................................................53
Merchant ID Hierarchy..................................................................................................................................................53
Merchant ID Registration............................................................................................................................................. 54
Portfolio MIDs for Partners.........................................................................................................................................54

Token Management Service | Contents | 3

Contents | 4

Token Vault Management.............................................................................................................................................55

Message-Level Encryption Keys................................................................................................................................ 55
Creating a Message-Level Encryption Key..................................................................................................56
Network Tokenization........................................................................................................................................ 57
Network Token Enablement....................................................................................................................................... 57
Network Token Onboarding—Partner Model.....................................................................................................57
Network Token Life-Cycle Management................................................................................................................59
Network Token Life-Cycle Management Reports.............................................................................................. 60
Token Requestor IDs...................................................................................................................................................... 60
Manage Webhook Subscriptions.................................................................................................................... 62
Create Keys for Digital Signature..............................................................................................................................64
Required Fields for Creating Keys for Digital Signature Using the REST API ............................. 64
REST Example: Creating Keys for Digital Signature............................................................................... 64
Create Webhook Subscription....................................................................................................................................66
Required Fields for Creating Webhook Subscription Using the REST API ...................................66
REST Example: Creating a Webhook Subscription..................................................................................66
Retrieve Webhook Subscription Details................................................................................................................ 69
Required Field for Retrieving Webhook Subscription Details Using the REST API ..................69
REST Example: Retrieving Webhook Subscription Details..................................................................69
Update Webhook Subscription.................................................................................................................................. 71
Required Field for Updating Webhook Subscription Using the REST API ................................... 71
REST Example: Updating Webhook Subscriptions..................................................................................71
Delete Webhook Subscription....................................................................................................................................73
Required Field for Deleting a Webhook Subscription Using the REST API...................................73
REST Example: Deleting a Webhook Subscription..................................................................................73
Customer Tokens..................................................................................................................................................75
Manage Customer Tokens............................................................................................................................................ 75
Create a Customer........................................................................................................................................................... 76
Required Fields for Creating a Customer Using the REST API...........................................................76
REST Example: Creating a Customer............................................................................................................ 76
REST Interactive Example: Creating a Customer..................................................................................... 78
Retrieve a Customer....................................................................................................................................................... 79
REST Example: Retrieving a Customer........................................................................................................ 79
Update a Customer..........................................................................................................................................................81
Required Fields for Updating a Customer ................................................................................................. 81

Token Management Service | Contents | 4

 Contents | 5

Optional Fields for Updating a Customer....................................................................................................81

REST Example: Updating a Customer...........................................................................................................82
REST Interactive Example: Updating a Customer....................................................................................83
Delete a Customer........................................................................................................................................................... 84
Required Fields for Deleting a Customer Token ..................................................................................... 84
REST Example: Deleting a Customer.............................................................................................................84
Retrieve a Customer's Default Payment with Unmasked Card Number..................................................86
REST Example: Retrieving a Customer's Default Payment with Unmasked Card
Number....................................................................................................................................................................... 86
Retrieve a Customer's Default Payment and Shipping Details ................................................................... 89
REST Example: Retrieving a Customer's Default Payment and Shipping Details.......................89
Payments with Customer Tokens............................................................................................................................. 93
Create a Customer Token with Validated Payment Details........................................................................... 94
Required Fields for Creating a Customer Token with Validated Payment Details Using the
REST API.................................................................................................................................................................... 94
REST Example: Creating a Customer Token with Validated Payment Details............................. 95
Authorizing a Payment with a Customer Token................................................................................................ 99
Required Fields for Authorizing a Payment with a Customer Token.............................................. 99
REST Example: Authorizing a Payment with a Customer Token...................................................... 99
REST Example: Authorizing a Payment Using a Customer Token Linked to a Network
Token......................................................................................................................................................................... 102
Making a Credit with a Customer Token............................................................................................................ 106
Required Fields for Making a Credit with a Customer Token..........................................................106
REST Example: Making a Credit with a Customer Token.................................................................. 106
Shipping Address Tokens................................................................................................................................110
Manage Shipping Address Tokens.........................................................................................................................110
Create a Customer Shipping Address...................................................................................................................110
Required Fields for Creating a Customer Shipping Address ...........................................................111
REST Example: Creating a Customer Shipping Address.................................................................... 112
REST Interactive Example: Creating a Customer Shipping Address............................................. 113
Add a Default Shipping Address.............................................................................................................................114
Required Fields for Adding a Default Shipping Address Using the REST API........................... 114
REST Example: Adding a Default Shipping Address............................................................................ 115
Add a Non-Default Shipping Address...................................................................................................................117
Required Fields for Adding a Non-Default Shipping Address Using the REST API................. 117
REST Example: Adding a Non-Default Shipping Address..................................................................118

Token Management Service | Contents | 5

Contents | 6

Change a Default Shipping Address......................................................................................................................120

Required Fields for Changing a Default Shipping Address Using the REST API.......................120
REST Example: Changing Default Shipping Address........................................................................... 121
Retrieve a Customer Shipping Address...............................................................................................................122
REST Example: Retrieving a Shipping Address......................................................................................124
Retrieve All Customer Shipping Addresses....................................................................................................... 125
REST Example: Retrieving All Customer Shipping Addresses.........................................................126
Update a Customer Shipping Address................................................................................................................. 128
Required Fields for Updating a Customer Shipping Address ......................................................... 128
REST Example: Updating a Customer Shipping Address...................................................................130
REST Interactive Example: Updating a Customer Shipping Address............................................131
Delete a Customer Shipping Address...................................................................................................................131
Required Fields for Deleting a Customer Shipping Address ........................................................... 131
REST Example: Deleting a Customer Shipping Address.....................................................................132
Payments with Shipping Address Tokens.......................................................................................................... 132
Authorizing a Payment with a Non-Default Shipping Address................................................................. 133
Required Fields for Authorizing a Payment with a Non-Default Shipping Address............... 133
REST Example: Authorizing a Payment with a Non-Default Shipping Address....................... 133
Customer Payment Instrument Tokens..................................................................................................... 137
Manage Customer Payment Instrument Tokens............................................................................................. 137
Create a Customer Payment Instrument............................................................................................................ 137
Required Fields for Creating a Customer Payment Instrument Using the REST API ............ 138
Optional Fields for Creating a Customer Payment Instrument Using the REST API ............. 138
REST Example: Creating a Customer Payment Instrument.............................................................. 140
REST Interactive Example: Creating a Customer Payment Instrument.......................................142
Add a Default Payment Instrument Using Instrument Identifier............................................................ 143
Required Fields for Adding a Default Payment Instrument Using Instrument Identifier Using
the REST API ........................................................................................................................................................143
Optional Fields for Adding a Default Payment Instrument Using Instrument Identifier Using
the REST API ........................................................................................................................................................143
REST Example: Adding a Default Payment Instrument Using Instrument Identifier............ 145
Add a Default Payment Instrument with Validated Payment....................................................................148
Required Fields for Adding a Default Payment Instrument with Validated Payment Using the
REST API ................................................................................................................................................................ 148
REST Example: Adding a Default Payment Instrument with Validated Payment.................... 149
Add a Non-Default Payment Instrument Using Instrument Identifier.................................................. 153

Token Management Service | Contents | 6

 Contents | 7

Required Fields for Adding a Non-Default Payment Instrument Using Instrument Identifier
Using the REST API ...........................................................................................................................................153
Optional Fields for Adding a Non-Default Payment Instrument Using Instrument Identifier
Using the REST API ...........................................................................................................................................153
REST Example: Adding a Non-Default Payment Instrument Using Instrument
Identifier.................................................................................................................................................................. 155
Add a Non-Default Payment Instrument with Validated Payment..........................................................158
Required Fields for Adding a Non-Default Payment Instrument with Validated Payment
Using the REST API ...........................................................................................................................................158
REST Example: Adding a Non-Default Payment Instrument with Validated Payment.......... 159
Change a Customer's Default Payment Instrument....................................................................................... 163
Required Fields for Changing a Customer's Default Payment Instrument Using the REST API
......................................................................................................................................................................................163
REST Example: Changing a Customer's Default Payment Instrument......................................... 164
Retrieve a Customer Payment Instrument........................................................................................................ 166
REST Example: Retrieving a Customer Payment Instrument.......................................................... 167
Retrieve a Customer Payment Instrument with Unmasked Card Number..........................................170
REST Example: Retrieving a Customer Payment Instrument with Unmasked Card
Number.....................................................................................................................................................................170
List Payment Instruments for a Customer.........................................................................................................171
Required Fields for Listing Payment Instruments for a Customer Using the REST API .......172
REST Example: Listing Payment Instruments for a Customer ....................................................... 173
Update a Customer Payment Instrument...........................................................................................................178
Required Fields for Updating a Customer Payment Instrument Using the REST API ...........179
Optional Fields for Updating a Customer Payment Instrument Using the REST API ............179
REST Example: Updating a Customer Payment Instrument.............................................................181
REST Interactive Example: Updating a Customer Payment Instrument..................................... 183
Delete a Customer Payment Instrument............................................................................................................ 183
Required Fields for Deleting a Customer Payment Instrument Using the REST API ............ 184
REST Example: Deleting a Customer Payment Instrument.............................................................. 185
Payments with Customer Payment Instrument Tokens...............................................................................186
Authorizing a Payment with a Non-Default Payment Instrument...........................................................187
Required Fields for Authorizing a Payment with a Non-Default Payment Instrument......... 187
Optional Fields for Authorizing a Payment with a Non-Default Payment Instrument.......... 187
REST Example: Authorizing a Payment with a Non-Default Payment Instrument................. 188
Making a Credit with a Non-Default Payment Instrument......................................................................... 192
Required Fields for Making a Credit with a Non-Default Payment Instrument....................... 192

Token Management Service | Contents | 7

Contents | 8

Optional Fields for Making a Credit with a Non-Default Payment Instrument........................ 192
REST Example: Making a Credit with a Non-Default Payment Instrument................................193
Payment Instrument Tokens......................................................................................................................... 197
Manage Payment Instrument Tokens...................................................................................................................197
Create a Payment Instrument..................................................................................................................................197
Required Fields for Creating a Payment Instrument Using the REST API .................................198
Optional Fields for Creating a Payment Instrument Using the REST API ..................................198
REST Example: Creating a Payment Instrument................................................................................... 200
REST Interactive Example: Creating a Payment Instrument............................................................202
Retrieve a Payment Instrument..............................................................................................................................202
REST Example: Retrieving a Payment Instrument............................................................................... 203
Find Payment Instruments by Card Number....................................................................................................206
Required Fields for Finding Payment Instruments by Card Number Using the REST API
......................................................................................................................................................................................206
REST Example: Finding Payment Instruments by Card Number................................................... 206
Retrieve a Payment Instrument with Unmasked Card Number...............................................................216
REST Example: Retrieving a Payment Instrument with Unmasked Card Number................. 216
Update a Payment Instrument................................................................................................................................ 217
Required Fields for Updating a Payment Instrument Using the REST API ............................... 218
Optional Fields for Updating a Payment Instrument Using the REST API ................................ 218
REST Example: Updating a Payment Instrument..................................................................................220
REST Interactive Example: Updating a Payment Instrument.......................................................... 222
Delete a Payment Instrument..................................................................................................................................222
Required Fields for Deleting a Payment Instrument Using the REST API .................................223
REST Example: Deleting a Payment Instrument................................................................................... 224
Payments with Payment Instrument Tokens....................................................................................................225
Authorizing a Payment with a Payment Instrument.....................................................................................226
Required Fields for Authorizing a Payment with a Payment Instrument...................................226
Optional Fields for Authorizing a Payment with a Payment Instrument....................................226
REST Example: Authorizing a Payment with a Payment Instrument........................................... 227
Making a Credit with a Payment Instrument................................................................................................... 231
Required Fields for Making a Credit with a Payment Instrument................................................. 231
REST Example: Making a Credit with a Payment Instrument......................................................... 231
Instrument Identifier Tokens........................................................................................................................235
Manage Instrument Identifier Tokens................................................................................................................. 235

Token Management Service | Contents | 8

 Contents | 9

Create an Instrument Identifier..............................................................................................................................235

Required Fields for Creating an Instrument Identifier Using the REST API..............................236
Optional Fields for Creating an Instrument Identifier Using the REST API............................... 237
REST Example: Creating a Card Instrument Identifier.......................................................................238
REST Interactive Example: Creating an Instrument Identifier........................................................238
REST Example: Creating a Bank Account Instrument Identifier ...................................................239
Retrieve an Instrument Identifier..........................................................................................................................240
REST Example: Retrieving an Instrument Identifier........................................................................... 241
REST Interactive Example: Retrieving an Instrument Identifier....................................................243
Update an Instrument Identifier............................................................................................................................ 243
Required Fields for Updating an Instrument Identifier Using the REST API............................ 243
Optional Fields for Updating an Instrument Identifier Using the REST API..............................243
REST Example: Updating an Instrument Identifier..............................................................................245
REST Interactive Example: Updating an Instrument Identifier...................................................... 246
Retrieve an Instrument Identifier's Payment Instruments........................................................................ 247
REST Example: Retrieving an Instrument Identifier's Payment Instruments.......................... 248
REST Interactive Example: Retrieving an Instrument Identifier's Payment Instruments... 256
Retrieve an Instrument Identifier with Unmasked Card Number...........................................................257
REST Example: Retrieving an Instrument Identifier with Unmasked Card Number............. 257
Delete an Instrument Identifier..............................................................................................................................258
Required Fields for Deleting an Instrument Identifier Using the REST API.............................. 258
REST Example: Deleting an Instrument Identifier............................................................................... 260
REST Interactive Example: Deleting an Instrument Identifier........................................................261
Payments with Instrument Identifier Tokens.................................................................................................. 261
Create an Instrument Identifier Token with Validated Payment Details.............................................. 262
Required Fields for Creating an Instrument Identifier Token with Validated Payment Details
Using the REST API............................................................................................................................................ 262
REST Example: Creating an Instrument Identifier with Validated Payment Details.............. 263
Authorize a Payment with an Instrument Identifier.....................................................................................267
Required Fields for Authorizing a Payment with an Instrument Identifier...............................267
REST Interactive Example: Authorizing a Payment with an Instrument Identifier................ 267
REST Example: Authorizing a Payment with an Instrument Identifier.......................................267
REST Example: Authorizing a Payment with an Instrument Identifier While Creating TMS
Tokens.......................................................................................................................................................................270
Making a Credit with an Instrument Identifier............................................................................................... 274

Token Management Service | Contents | 9

Contents | 10

Required Fields for Making a Credit with an Instrument Identifier............................................. 274

REST Interactive Example: Making a Credit with an Instrument Identifier.............................. 274
REST Example: Making a Credit with an Instrument Identifier..................................................... 274
Legacy Tokens.....................................................................................................................................................278
Payments with Legacy Tokens................................................................................................................................ 278
Authorizing a Payment with a Legacy Token................................................................................................... 279
Required Fields for Authorizing a Payment with a Legacy Token................................................. 279
REST Interactive Example: Authorizing a Payment with a Legacy Token.................................. 279
REST Example: Authorizing a Payment with a Legacy Token......................................................... 279
Making a Credit with a Legacy Token..................................................................................................................283
Required Fields for Making a Credit with a Legacy Token................................................................283
REST Example: Making a Credit with a Legacy Token........................................................................283
Network Tokens for Merchants.................................................................................................................... 287
Payments with Network Tokens for Merchants.............................................................................................. 287
Authorize a Payment While Ignoring Network Token..................................................................................288
Required Fields for Authorizing a Payment While Ignoring Network Token Using the REST
API .............................................................................................................................................................................288
REST Example: Authorizing a Payment While Ignoring Network Token....................................289
Manage Merchant-Initiated Transactions and Network Tokens.............................................................. 291
Update Merchant-Initiated Transaction Authorization Options.............................................................. 292
Required Fields for Updating MIT Authorization Options Using the REST API....................... 292
REST Example: Updating MIT Authorization Options........................................................................ 293
Network Tokens for Partners........................................................................................................................295
Manage Network Tokens for Partners.................................................................................................................295
Provision a Network Token for a Card Number..............................................................................................296
Required Fields for Provisioning a Network Token for a Card Number Using the REST API
......................................................................................................................................................................................296
Optional Fields for Provisioning a Network Token for a Card Number Using the REST API
......................................................................................................................................................................................296
REST Example: Provisioning a Network Token for a Card Number..............................................297
Provision a Network Token for an Existing Instrument Identifier..........................................................299
Required Fields for Provisioning a Network Token for an Existing Instrument Identifier
Using the REST API............................................................................................................................................ 299
Optional Fields for Provisioning a Network Token for an Existing Instrument Identifier
Using the REST API............................................................................................................................................ 299
REST Example: Provisioning a Network Token for an Existing Instrument Identifier..........300

Token Management Service | Contents | 10

 Contents | 11

REST Interactive Example: Provisioning a Network Token for an Existing Instrument

Identifier.................................................................................................................................................................. 301
Retrieve a Network Token for Payment Credentials..................................................................................... 302
REST Example: Retrieving a Network Token for Payment Credentials....................................... 302
Retrieve an Instrument Identifier..........................................................................................................................305
REST Example: Retrieving an Instrument Identifier........................................................................... 306
REST Interactive Example: Retrieving an Instrument Identifier....................................................308
Delete an Instrument Identifier..............................................................................................................................308
Required Fields for Deleting an Instrument Identifier Using the REST API.............................. 308
REST Example: Deleting an Instrument Identifier............................................................................... 309
REST Interactive Example: Deleting an Instrument Identifier........................................................310
Network Token Provision Failures........................................................................................................................ 310
Using Token Management Service with Wallet Apps............................................................................315
Manage Tokens with Wallet Apps......................................................................................................................... 315
Create a New Customer Account .......................................................................................................................... 315
Add a New Shipping Address.................................................................................................................................. 316
Edit or Delete a Shipping Address........................................................................................................................ 316
Create a New Payment Instrument with the Payments API...................................................................... 316
Edit or Delete a Payment Method......................................................................................................................... 317
Change the Default Payment Method...................................................................................................................317
Add a New Payment Method Address................................................................................................................. 318
View Wallet...................................................................................................................................................................... 318
Payments with Tokens and Wallet Apps............................................................................................................ 318
Authorize a Payment................................................................................................................................................... 319
Reference Information.....................................................................................................................................320
Encrypt and Decrypt Data.........................................................................................................................................320
HTTP Status Codes....................................................................................................................................................... 321
Supported Processors...................................................................................................................................... 323

Token Management Service | Contents | 11

Token Management Service
This developer guide is written for merchants who want to tokenize customers’ sensitive personal
information and eliminate payment data from their networks to ensure that it is not compromised.
The purpose of this guide is to help you create and manage tokens.

Conventions

These special statements are used in this document:

Important: An Important statement contains information essential to successfully

completing a task or learning a concept.

Warning: A Warning contains information or instructions, which, if not heeded, can result in
a security risk, irreversible loss of data, or significant cost in time or revenue or both.

Related Documentation

Refer to the Technical Documentation Hub in the Cybersource Developer Center for additional
technical documentation:

https://developer.cybersource.com/docs.html

Customer Support

For support information about any service, visit the Support Center:

http://support.cybersource.com

Recent Revisions to This Document

24.05

Network Tokens

Token Management Service | Token Management Service | 12

 Updated terms of use for network tokens. See TERMS OF USE APPLICABLE TO CARD
NETWORK TOKENS (on page 16).

Added note for processing network tokens with American Express. See Network
Tokens (on page 22)

24.04

Network Tokens
Added terms of use for network tokens. See TERMS OF USE APPLICABLE TO CARD
NETWORK TOKENS (on page 16).

24.03
Removed required fields from token retrieval topics See:

• Retrieve a Customer (on page 79)

• Retrieve a Customer's Default Payment with Unmasked Card Number (on page
86)

• Retrieve a Customer's Default Payment and Shipping Details (on page 89)

• Retrieve a Customer Shipping Address (on page 122)

• Retrieve All Customer Shipping Addresses (on page 125)

• Retrieve a Customer Payment Instrument (on page 166)

• Retrieve a Customer Payment Instrument with Unmasked Card Number (on page
170)

• Retrieve a Payment Instrument (on page 202)

• Retrieve a Payment Instrument with Unmasked Card Number (on page 216)

• Retrieve an Instrument Identifier (on page 240)

• Retrieve an Instrument Identifier's Payment Instruments (on page 247)

• Retrieve an Instrument Identifier with Unmasked Card Number (on page 257)

• Retrieve a Network Token for Payment Credentials (on page 302)

24.02
Message-Level Encryption Keys

Token Management Service | Token Management Service | 13

 Added information about creating message-level encryption keys. See Creating a
Message-Level Encryption Key (on page 56).
Token Management Service Introduction
Updated the graphic in the introduction to Token Management Service. See
Introduction to the Token Management Service (on page 18).
Instrument Identifier Tokens
Added an example for authorizing a payment using an instrument identifier and
creating tokens. See REST Example: Authorizing a Payment with an Instrument
Identifier While Creating TMS Tokens (on page 270).

24.01
Added Network Token Life-Cycle Management reports. See Network Token Life-Cycle
Management Reports (on page 60).

23.05
Updated internal organization to ensure all use cases showed as a single web page.

23.04
Added a note about Indian merchants and the storage of primary account numbers
(PANs). See Introduction to the Token Management Service (on page 18).

23.03
This revision contains only editorial changes and no technical updates.

Token Management Service | Token Management Service | 14

VISA Platform Connect: Specifications and Conditions for
Resellers/Partners
The following are specifications and conditions that apply to a Reseller/Partner enabling its
merchants through Cybersource for Visa Platform Connect (“VPC”) processing. Failure to meet any
of the specifications and conditions below is subject to the liability provisions and indemnification
obligations under Reseller/Partner’s contract with Visa/Cybersource.

1. Before boarding merchants for payment processing on a VPC acquirer’s connection, Reseller/
Partner and the VPC acquirer must have a contract or other legal agreement that permits
Reseller/Partner to enable its merchants to process payments with the acquirer through the
dedicated VPC connection and/or traditional connection with such VPC acquirer.

2. Reseller/Partner is responsible for boarding and enabling its merchants in accordance with the
terms of the contract or other legal agreement with the relevant VPC acquirer.

3. Reseller/Partner acknowledges and agrees that all considerations and fees associated with
chargebacks, interchange downgrades, settlement issues, funding delays, and other processing
related activities are strictly between Reseller and the relevant VPC acquirer.

4. Reseller/Partner acknowledges and agrees that the relevant VPC acquirer is responsible for
payment processing issues, including but not limited to, transaction declines by network/
issuer, decline rates, and interchange qualification, as may be agreed to or outlined in the
contract or other legal agreement between Reseller/Partner and such VPC acquirer.

DISCLAIMER: NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR

ANY ERRORS OR OMISSIONS BY THE VISA PLATFORM CONNECT ACQUIRER IN PROCESSING
TRANSACTIONS. NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR
RESELLER/PARTNER BOARDING MERCHANTS OR ENABLING MERCHANT PROCESSING IN
VIOLATION OF THE TERMS AND CONDITIONS IMPOSED BY THE RELEVANT VISA PLATFORM
CONNECT ACQUIRER.

Token Management Service | Token Management Service | 15

TERMS OF USE APPLICABLE TO CARD NETWORK TOKENS
The following terms and conditions govern your use, receipt and/or possession of Card Network
Tokens.

1. DEFINTIONS. Capitalized terms used herein shall have the following meanings:

a. “Card Network PAN” means a number that is associated with a Payment Network for
purposes of card transactions, all in accordance with Payment Network Rules.

b. “Card Network Token” means a number provided by Cybersource pursuant to your use
of Token Management Service (“TMS”) that (i) is mapped to and is a surrogate for a Card
Network PAN; and (ii) to use the underlying Card Network PAN number in accordance
with the Cybersource Documentation.

c. “Payment Network Rules” means the operating rules, bylaws, schedules, supplements
and addenda, manuals, instructions, releases, specifications and other requirements, as
may be amended from time to time, of any of the Payment Networks.

d. “Payment Network(s)” means Visa, MasterCard, American Express, Discover Financial

Services, and any affiliates thereof or any other payment network applicable to these
Terms.

2. LIMITATIONS ON USE OF CARD NETWORK TOKENS. You agree to the following with respect
to your use, receipt and/or possession of Card Network Tokens:

a. You shall not maintain or create a mapping of the Card Network Token to the associated
Card Network PAN.

b. Upon request by Cybersource and/or the applicable Payment Network, you shall use
commercially reasonable efforts to delete any or all of the Card Network Tokens. You
acknowledge and agree that Cybersource or the applicable Payment Network may
request that you delete any Card Network Token at their sole discretion.

c. You shall not initiate any transaction with a Card Network Token without appropriate
consent from and disclosures to the cardholder, including any necessary consents in
order for the applicable Payment Network to receive, store, process and share any data in
order to deliver the token service. Except as authorized in accordance with the applicable
Payment Network Rules, you must use the Card Network Token only for transactions that
are authorized, cleared and settled through the applicable Payment Network.

d. You shall not use a Card Network Token in a manner that a Card Network PAN cannot be
used under the applicable Payment Network Rules. You agree that your responsibility
for use of Card Network Tokens is the same as your responsibilities for use of Account
Numbers under the applicable Payment Network Rules.

Token Management Service | Token Management Service | 16

e. You agree that the Payment Network Rules govern your relationship with the applicable
Payment Network and use of Card Network Tokens as if the Card Network Tokens were
Card Network PANs. You must comply with all applicable Payment Network Rules, as
determined by the applicable Payment Network.

f. You agree that any Card Network Tokens will be stored in compliance with PCI-DSS and
such storage is subject to your representations and warranties set forth in the applicable
agreement between you and Cybersource.

g. If you are a Reseller or Partner, to enable American Express Network Tokens, you must
have a direct acquiring or processing agreement signed with American Express in order
to support American Express Network Tokens on behalf of your merchants.

Token Management Service | Token Management Service | 17

Introduction to the Token Management Service
The Token Management Service (TMS) enables you to replace personally identifiable information
(PII), such as the primary account numbers (PANs), with unique tokens. These tokens do not include
the PII data, but act as a placeholder for the personal information that would otherwise need to be
shared. By using tokens, businesses can provide a secure payment experience, reduce the risk of
fraud, and comply with industry consumer security regulations such as PCI-DSS.

TMS links tokens across service providers, payment types, and channels for sellers, acquirers, and
technology partners. TMS tokenizes, securely stores, and manages the primary account number
(PAN), the payment card expiration date, electronic check details, and customer data. TMS also
enables you to create a network token of a customer's payment card.

Important: Due to mandates from the Reserve Bank of India, Indian merchants cannot store
PANs. Use network tokenization instead.

You can manage sensitive data securely by creating, retrieving, updating, and deleting tokens through
the TMS API.

TMS simplifies your PCI DSS compliance. TMS passes tokens back to you that represent this data.
You then store these tokens in your environment and databases instead of storing customer payment
details.

TMS protects sensitive payment information through tokenization and secures and manages
customer data using these token types:

• Customer tokens

• Instrument identifier tokens

• Payment instrument tokens

• Shipping address tokens

These TMS tokens can be used individually, or they can be associated with one customer token:

Token Management Service | Introduction to the Token Management Service | 18

TMS Token Types

Token Management Service | Introduction to the Token Management Service | 19

Types of Tokens
These tokens comprise the types of TMS tokens:

• Customer Token: Contains customer's email address, customer ID, shipping address (stored in
a token), and other related data.

• Shipping Address Token: Contains the shipping address associated with a customer token.

• Payment Instrument Token: Contains the complete billing details for the payment type
including cardholder name, expiration date, and billing address.

• Instrument Identifier Token: Contains the tokenized primary account number (PAN) for card
payments as well as the associated network token or U.S. or Canadian bank account number
and routing number.

• Network Token: Network tokens pass through an acquirer and are de-tokenized by the
payment network or issuer. For customer-initiated transactions, they require a cryptogram.
Network tokens are mapped to instrument identifier tokens.

TMS Token Types

Token Management Service | Introduction to the Token Management Service | 20

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.

Related information
Manage Customer Tokens (on page 75)
Payments with Customer Tokens (on page 93)

Shipping Address Tokens

The shipping address token contains the shipping address information associated with a customer
token. This token includes any shipping address details, including the recipient's first and last name,
company, shipping address, email, and phone number. A customer can have one or more shipping
addresses, with one allocated as the customer's default shipping address.

Related information
Manage Shipping Address Tokens (on page 110)
Payments with Shipping Address Tokens (on page 132)

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.

Related information
Manage Payment Instrument Tokens (on page 197)
Payments with Payment Instrument Tokens (on page 225)

Token Management Service | Introduction to the Token Management Service | 21

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.

Related information
Manage Instrument Identifier Tokens (on page 235)
Payments with Instrument Identifier Tokens (on page 261)

Network Tokens
When a TMS token is used in a transaction, the TMS token is de-tokenized, and the PAN is sent to the
issuer for authorization. The PAN is still exchanged as the transaction is processed. With network
tokens, the PAN is removed from the transaction processing and replaced with network tokens,
making the transaction more secure.

The network scheme generates network tokens. A token replaces customer card information for
secure transactions. Network tokens are mapped to instrument identifier tokens. The minimum card
data required in order to request a network token is the PAN and the expiration date.

Using a network token has benefits:

• Improved authorization rates for credential-on-file (COF) and recurring payments.

• Real-time card information updates via Network Token Life-Cycle Management (on page
59). When the customer's card details change, you can receive the updated information
automatically. See Manage Webhook Subscriptions (on page 62) for more information on
managing webhooks.

• Improved customer tracking through the payment account reference (PAR), which is a
consumer identifier that is less sensitive than the PAN. The PAR can be exchanged as the
transaction is processed.

Network tokens can be provided for merchants and partners.

Important: American Express does not support the Payfac model for processing network
tokens. Contact your American Express representative for more information.

Token Management Service | Introduction to the Token Management Service | 22

Related information
Payments with Network Tokens for Merchants (on page 287)
Manage Network Tokens for Partners (on page 295)
Manage Merchant-Initiated Transactions and Network Tokens (on page 291)

Token Management Service | Introduction to the Token Management Service | 23

Token Management Service Workflows
Tokenization workflows:

• PAN Tokenization Process Using TMS (on page 25)

• Network Token Tokenization Process (on page 26)

Network tokens workflows—merchant model:

• Network Token Provisioning—Merchant Model (on page 27)

• Network Token Authorizations (CIT)—Merchant Model (on page 30)

• Network Token Authorizations (MIT)—Merchant Model (on page 31)

Network tokens workflows—partner model:

• Network Token Onboarding—Partner Model (on page 57)

• Network Token Provisioning—Partner Model (on page 32)

• Network Token Authorizations (CIT)—Partner Model (on page 35)

• Network Token Authorizations (MIT)—Partner Model (on page 37)

Token Management Service | Token Management Service Workflows | 24

PAN Tokenization Process Using TMS
This workflow shows the tokenization process for TMS tokens.

PAN Tokenization Process with TMS

1. The customer makes a purchase on the merchant's website using a PAN.

2. The merchant sends the PAN to the gateway.

3. TMS creates a token. The merchant then stores the TMS token.

4. The tokenized PAN is exchanged across the payment ecosystem.

Token Management Service | Token Management Service Workflows | 25

Network Token Tokenization Process
This workflow shows the tokenization process for network tokens.

Network Token Tokenization Process

1. The customer makes a purchase on the merchant's website using a PAN.

2. The merchant sends the PAN to the gateway.

3. TMS creates a token.

4. TMS provisions a network token and links it to the TMS token.

5. The merchant stores the TMS token for subsequent transactions.

6. The network token and cryptogram are exchanged throughout the payment ecosystem.

Token Management Service | Token Management Service Workflows | 26

Network Token Provisioning for Merchants
This workflow shows the process of network token provisioning for merchants.

Network Token Provisioning for Merchants-Tokenizing PAN

Tokenizing PAN

1. The customer enters their card data and sends the PAN to the merchant.

2. The merchant sends the PAN to Token Management Service.

3. Token Management Service generates a TMS token and synchronously provisions a network
token from the card brand.

4. Token Management Service sends the merchant the TMS token, expiration date, suffix, and
payment account reference (PAR).

5. The merchant stores the TMS token ID and network token flag and sends the customer the
masked card number.

Token Management Service | Token Management Service Workflows | 27

 Network Token Provisioning for Merchants-Cryptogram Retrieval

Cryptogram Retrieval

1. The merchant requests the cryptogram using a TMS token from Token Management Service.

2. Token Management Service looks up the network token and sends the token metadata to the
card brand.

3. The card brand generates the cryptogram and sends it to Token Management Service.

4. Token Management Service sends the network token and cryptogram to the merchant.

5. The merchant uses the network token along with the cryptogram to start the authorization.

Network Token Provisioning for Merchants-PAR Retrieval

Token Management Service | Token Management Service Workflows | 28

PAR Retrieval

1. The merchant retrieves the TMS token and sends to Token Management Service.

2. Token Management Service looks up the token and retrieves the PAR.

3. Token Management Service sends the PAR to the merchant.

4. The merchant stores the PAR.

Token Management Service | Token Management Service Workflows | 29

Network Token CIT Authorizations for Merchants
This workflow shows a credentials-on-file (COF) authorization using a network token for a customer-
initiated transaction (CIT).

Network Token CIT Authorizations for Merchants

1. The customer makes a purchase and selects COF.

2. The merchant submits an authorization to the payment processor using a TMS token.

3. The payment processor uses the TMS token to look up the network token.

4. The payment processor requests the cryptogram generated by the card brand.

5. The payment processor sends the network token, cryptogram, and 3-D Secure data to the
acquirer in the authorization request.

6. The acquirer processes the authorization and sends the authorization result to the payment
processor.

7. The payment processor sends the authorization result to the merchant.

8. The merchant updates the order and advises the customer on how to proceed depending on
the authorization result.

Token Management Service | Token Management Service Workflows | 30

Network Token MIT Authorizations for Merchants
This workflow shows a credentials-on-file (COF) authorization using a network token for a
merchant-initiated transaction (MIT).

The workflow begins when the merchant submits an authorization using a TMS token.

Network Token MIT Authorizations for Merchants

1. The merchant sends the TMS token to the payment processor.

2. The payment processor looks up the network token associated with the TMS token.

3. The payment processor sends the network token and MIT COF data to the acquirer in the
authorization request.

4. The acquirer processes the authorization and sends the authorization result to the payment
processor.

5. The payment processor sends the authorization result to the merchant.

6. The merchant updates the system to reflect the status of the transaction.

7. The customer provides goods/service.

Token Management Service | Token Management Service Workflows | 31

Network Token Provisioning for Partners
This workflow shows the process of network token provisioning for partners.

Network Token Provisioning for Partners-Tokenizing PAN

Tokenizing PAN

1. The customer enters their card data and sends the PAN to the merchant.

2. The merchant sends the PAN to Token Management Service.

3. Token Management Service generates a TMS token and synchronously provisions a network
token from the card brand.

4. Token Management Service sends the merchant the TMS token, expiration date, suffix, and
payment account reference (PAR).

5. The merchant stores the TMS token ID and network token flag and sends the customer the
masked card number.

Token Management Service | Token Management Service Workflows | 32

 Network Token Provisioning for Partners-Cryptogram Retrieval

Cryptogram Retrieval

1. The merchant requests the payment credentials using a TMS token from Token Management
Service.

2. Token Management Servicelooks up the network token and sends the token metadata to the
card brand.

3. The card brand generates the cryptogram and sends it to Token Management Service.

4. Token Management Service sends the network token and cryptogram to the merchant.

5. The merchant uses the network token along with the cryptogram to start the authorization.

Network Token Provisioning for Partners-PAR Retrieval

PAR Retrieval

Token Management Service | Token Management Service Workflows | 33

1. The merchant retrieves TMS token and sends it to Token Management Service.

2. Token Management Service looks up the token and retrieves the PAR.

3. Token Management Service sends the PAR to the merchant.

4. The merchant stores the PAR.

Token Management Service | Token Management Service Workflows | 34

Network Token CIT Authorizations for Partners
This workflow shows a credentials-on-file (COF) authorization using a network token for a customer-
initiated transaction (CIT).

The workflow begins when the customer makes a purchase from the merchant and selects a COF
during payment.

Network Token CIT Authorizations for Partners

1. The customer makes a purchase and selects COF.

2. The merchant requests the payment credentials and sends the TMS token to the payment
processor.

3. The payment processor uses the TMS token to look up the network token.

4. The payment processor requests the cryptogram generated by the card brand.

5. The payment processor sends the network token and cryptogram to the merchant.

6. The merchant uses the network token along with the cryptogram to start the authorization.

Token Management Service | Token Management Service Workflows | 35

7. The merchant sends the network token, cryptogram, and 3-D Secure data to the acquirer in the
authorization request.

8. The acquirer processes the authorization and sends the authorization result to the merchant.

9. The merchant sends the customer the authorization result from the acquirer.

Token Management Service | Token Management Service Workflows | 36

Network Token MIT Authorizations for Partners
This workflow shows a credentials-on-file (COF) authorization using a network token for a
merchant-initiated transaction (MIT).

The workflow begins when the customer makes a purchase from the merchant and selects a COF
during payment.

Network Token MIT Authorizations for Partners

1. The customer makes a purchase and selects COF.

2. The merchant requests the payment credentials and sends the TMS token to the payment
processor.

3. The payment processor uses the TMS token to look up the network token.

4. The payment processor sends the network token and cryptogram to the merchant.

5. The merchant uses the network token along with the cryptogram to start the authorization.

Token Management Service | Token Management Service Workflows | 37

6. The merchant sends the network token and MIT COF data to the acquirer in the authorization
request.

7. The acquirer processes the authorization and sends the authorization result to the merchant.

8. The merchant sends the customer the authorization result from the acquirer.

Token Management Service | Token Management Service Workflows | 38

Requesting the Token Management Service API
Before requesting the Token Management Service (TMS) API, you must already have a Business
Center account. If you do not, you can create an evaluation account.

To request the TMS API:

1. Authenticate to the API using either HTTP signature authentication or JSON Web Token (JWT)
authentication.

a. A Base64-encoded shared secret key is passed in the headers you generate for HTTP
signature authentication.

See Creating a Shared Secret Key Pair in Getting Started with the REST API for
instructions.

b. A P12 Certificate is passed in the headers you generate for JWT authentication.

See Creating a P12 Certificate in the Getting Started with the REST API for instructions.

2. Specify one of the following hosts in the URL:

a. Sandbox: POST https://apitest.cybersource.com

b. Production: POST https://api.cybersource.com

c. Production in India: POST https://api.in.cybersource.com/

3. Append the resource, such as, /tms/v2/customer to the host URL. For example, https://
api.cybersource.com/tms/v2/customer.

4. Pass your request using a HTTP GET, POST, PATCH or DELETE method as specified in each API
operation.

HTTP Response Headers

Response Header Possible Values Description

instrumentidentifier-created true or false This value indicates whether a new
instrument identifier was created. For
example, you have never tokenized this
PAN or bank account, or an existing one was
returned.

Token Management Service | Requesting the Token Management Service API | 39

Related information
Getting Started with the REST API—Secure Communication Requirements

Case Sensitivity

Token IDs are not case-sensitive. The following requests return the same resource:

GET /instrumentidentifiers/49C26351BF7D8765E05333B9d30AA9DB

GET /instrumentidentifiers/49c26351bf7d8765e05333b9d30aa9db

Important: Unlike the token ID in the request URL, all request fields are case-sensitive.

List matching rules:

• Accept any case (web, WEB, WeB).

• Store the expected case (WEB).

• Return the expected case (WEB) metadata.

Metadata
Token type structures such as instrument identifiers and payment instruments contain a metadata
map that contains data about the creator.

A metadata map is returned for every token type in a response to an HTTP POST, GET, and PATCH
request.

Example: Metadata from a Response

"metadata": {
"creator": "mid1"
}

Token Management Service | Requesting the Token Management Service API | 40

Patching Considerations

Patching within TMS is based on JSON Merge Patch (RFC7396), in which changes follow the same
structure being modified as that of a POST request, rather than JavaScript Object Notation (JSON)
Patch (RFC6902), in which changes are expressed as a set of actions.

A PATCH request is different from a PUT request in that only the fields that must be changed need to
be provided in the request, and those changes are merged with the existing record.

Here are some rules to consider:

• When a field is to be removed, you can remove a field by entering a value of null.

• When a field is set to null, and it does not exist in the current record, it is ignored.

• You can remove groups of fields by setting the parent container to null.

Important: Array values are patched as a whole, so in the patch request, provide the final
value that is expected after the patch.

Patching Examples

Below are some use-case examples of patching rules.

Example: Updating Expiration Month and Year Values

You can get the existing values by sending a GET request to the payment instrument ID as shown
below:

GET /tms/v1/paymentinstrument/<id>

The response is shown below:

{
"_links": {
"self": {
"href": "https://api.cybersource.com/tms/v1/paymentinstruments/9000000000000
000002001"
}
},
"id": "9000000000000000002001",
"object": "paymentInstrument",
"state": "ACTIVE",

Token Management Service | Requesting the Token Management Service API | 41

 "card": {
"expirationMonth": "09",
"expirationYear": "2017",
"type": "visa",
"issueNumber": "01"
},
"_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {
"href": "https://api.cybersource.com/tms/v1/instrumentidentifiers/900000
0000000000001001"
}
},
"id": "9000000000000000001001",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXX11112"
}
}
}
}

To update just the card.expirationMonth and card.expirationYear fields, send the following PATCH
request:

PATCH /tms/v1/paymentinstrument/<id>
{
"card": {
"expirationMonth": "10",
"expirationYear": "2020"
}
}

You can see the new values by issuing another GET request to /tms/v1/paymentinstrument/<id>. The
response is shown below.

{
"_links": {
"self": {
"href": "https://api.cybersource.com/tms/v1/paymentinstruments/9000000000000
000002001"
}
},
"id": "9000000000000000002001",
"object": "paymentInstrument",

Token Management Service | Requesting the Token Management Service API | 42

 "state": "ACTIVE",
"card": {
"expirationMonth": "10",
"expirationYear": "2020",
"type": "visa",
"issueNumber": "01"
}, "_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {
"href": "https://api.cybersource.com/tms/v1/instrumentidentifiers/900000
0000000000001001"
}
},
"id": "9000000000000000001001",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXX11112"
}
}
}
}

Example: Removing Card Issue Number (Single Field) and Buyer Information (Container)

First, send a GET request to /tms/v1/paymentinstrument/<id> to see the current values:

{
"_links": {
"self": {
"href": "https://api.cybersource.com/tms/v1/paymentinstruments/9000000000000
000002001"
}
},
"id": "9000000000000000002001",
"object": "paymentInstrument",
"state": "ACTIVE",
"card": {
"expirationMonth": "09",
"expirationYear": "2017",
"type": "visa",
"issueNumber": "01"
},
"buyerInformation": {
"companyTaxID": "12345",
"currency": "USD"
},

Token Management Service | Requesting the Token Management Service API | 43

 "_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {
"href": "https://api.cybersource.com/tms/v1/instrumentidentifiers/900000
0000000000001001"
}
},
"id": "9000000000000000001001",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXX11112"
}
}
}
}

Then send a PATCH request to /tms/v1/paymentinstrument/<id> and include the following payload:

{
"card": {
"issueNumber": null
},
"buyerInformation": null
}

The result can be seen in the next GET request to /tms/v1/paymentinstrument/<id>:

{
"_links": {
"self": {
"href": "https://api.cybersource.com/tms/v1/paymentinstruments/9000000000000
000002001"
}
},
"id": "9000000000000000002001",
"object": "paymentInstrument",
"state": "ACTIVE",
"card": {
"expirationMonth": "09",
"expirationYear": "2017",
"type": "visa"
}
"_embedded": {
"instrumentIdentifier": {
"_links": {

Token Management Service | Requesting the Token Management Service API | 44

 "self": {
"href": "https://api.cybersource.com/tms/v1/instrumentidentifiers/900000
0000000000001001"
}
},
"id": "9000000000000000001001",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXX11112"
}
}
}
}

Example: Patching an Array

Original value:

{
"a": [
{
"b": "c",
"d": "e"
}
]
}

Patch payload:

{
"a": [
{
"z": "y"
}
]
}

Final value:

{
"a": [
{
"z": "y"

Token Management Service | Requesting the Token Management Service API | 45

 }
]
}

Pagination

Responses can indicate pagination by including the limit and offset fields in your request.

Parameter Description
limit
Controls the maximum number of items that can be returned for a single
request. The default is 20; the maximum is 100.

If you set a limit greater than 100, the following error results:

Http Status: 400 Bad Request

Body
{
"errors": [
{
"type": "invalidParameters",
"message": "Invalid parameter values",
"details": [
{
"name": "limit"
}
]
}
]
}

offset
Controls the starting point within the collection of results. Defaults to 0.

Setting a zero offset retrieves the first item in the collection.

For example, if you have a collection of 15 items to be retrieved from a

resource, and you specify limit=5 , you can retrieve the entire set of results
in three successive requests by varying the offset value: offset=0, offset=5,
and offset=10.
An offset greater than the number of results does not return an embedded
object.

Token Management Service | Requesting the Token Management Service API | 46

Pagination Response Header

Header Description
X-total-count Returns total records count regardless of pagination.

Pagination Response Body Fields

Field Description
"object":"collection" Shows that the response is a collection of objects.
"offset": 40 The offset parameter used in the request.
"limit": 20 The limit parameter used in the request.
"count": 20 The number of objects returned.
"total": 87 The total number of objects.

Examples

Pagination Example 1

This example shows a request for objects 41 to 60.

Request

GET https://api.cybersource.com/tms/v1/instrumentidentifiers/5BAAD18F8091052CE0539
399D30AAB2F/paymentinstruments?offset=40&limit=20

For merchants in India, the Production endpoint is https://api.in.cybersource.com/

Important:

• If you are on the first collection, the previous link would not be included.

• If you are on the last collection, the next link would not be included.

• All other links are always included. For example, if there was only one collection of
results, the URL for self, first, and last links would be the same.

Response

Token Management Service | Requesting the Token Management Service API | 47

 {
"_links": {
"self": {
"href":
"https://api.cybersource.com/tms/v1/instrumentidentifiers/5BAAD18F8091052CE053939
9D30AAB2F/paymentinstruments?offset=40&limit=20"
},
"first": {
"href":
"https://api.cybersource.com/tms/v1/instrumentidentifiers/5BAAD18F8091052CE053939
9D30AAB2F/paymentinstruments?offset=0&limit=20"
},
"prev": {
"href":
"https://api.cybersource.com/tms/v1/instrumentidentifiers/5BAAD18F8091052CE053939
9D30AAB2F/paymentinstruments?offset=20&limit=20"
},
"next": {
"href":
"https://api.cybersource.com/tms/v1/instrumentidentifiers/5BAAD18F8091052CE053939
9D30AAB2F/paymentinstruments?offset=60&limit=20"
},
"last": {
"href":
"https://api.cybersource.com/tms/v1/instrumentidentifiers/5BAAD18F8091052CE053939
9D30AAB2F/paymentinstruments?offset=80&limit=20"
}
},
"object":"collection",
"offset": 40,
"limit": 20,
"count": 20,
"total": 87,
"_embedded": {
<array data>
}
}

Pagination Example 2 - Offset to Limit Relationship

This example shows a request for objects 3 to 6, from a total of 8 objects.

The example below shows the second collection of results and highlights that the previous page link
will not change the user’s original limit parameter value.

This means that the previous collection will contain objects 0-3, and therefore collection 1 and
collection 2 will both contain object 3.

Token Management Service | Requesting the Token Management Service API | 48

Request

GET https://api.cybersource.com/tms/v1/instrumentidentifiers/5BAAD18F8091052CE0539
399D30AAB2F/paymentinstruments?offset=3&limit=4

Offset to Limit Relationship

Response

{
"_links": {
"self": {
"href":
"https://api.cybersource.com/tms/v1/instrumentidentifiers/5BAAD18F8091052CE053939
9D30AAB2F/paymentinstruments?offset=3&limit=4"
},
"first": {
"href":
"https://api.cybersource.com/tms/v1/instrumentidentifiers/5BAAD18F8091052CE053939
9D30AAB2F/paymentinstruments?offset=0&limit=4"
},
"prev": {
"href":
"https://api.cybersource.com/tms/v1/instrumentidentifiers/5BAAD18F8091052CE053939
9D30AAB2F/paymentinstruments?offset=0&limit=4"
},
"next": {
"href":
"https://api.cybersource.com/tms/v1/instrumentidentifiers/5BAAD18F8091052CE053939
9D30AAB2F/paymentinstruments?offset=7&limit=4"
},
"last": {
"href":
"https://api.cybersource.com/tms/v1/instrumentidentifiers/5BAAD18F8091052CE053939
9D30AAB2F/paymentinstruments?offset=7&limit=4"
}
},
"object":"collection",
"offset": 3,

Token Management Service | Requesting the Token Management Service API | 49

 "limit": 4,
"count": 4,
"total": 8,
"_embedded": {
<array data>
}
}

Token Management Service | Requesting the Token Management Service API | 50

Supported Processors
The processors listed below support customer and instrument identifier tokens, unless noted
otherwise.

Processor Payment Method

Visa Platform
Connect • Credit card—supports 0.00 pre-authorizations for Visa and Mastercard
cards.

• Credit card—supports 1.00 pre-authorizations for American Express,

Discover, Diners Club, and JCB card types.

• Debit card and prepaid card.

• Payouts.

Test Card Numbers

Use these test card numbers to provision and test TMS tokens and network tokens. Replace Xs with
0s to use the card numbers.

Successful Network Token Provisioning

Use these test card numbers to provision network tokens.

Test Card Numbers for Successful Network Token Provisioning

Card Brand Number Expiration CVV
Date
American Any Any Any
Express
Mastercard 512X342233150747 Any Any
Mastercard 512X343287499758 Any Any
Mastercard 51203501XXX64594 Any Any
Mastercard 222269042006459X Any Any
Visa 489537998XXXX580 12/23 518

Token Management Service | Requesting the Token Management Service API | 51

Test Card Numbers for Successful Network Token Provisioning
(continued)
Card Brand Number Expiration CVV
Date
Visa 489537998XXXX572 12/23 841
Visa 489537998XXXX564 12/23 011

Important: Once a Network Token has been successfully provisioned for one of the
above test PANs there is no way to delete the network token to further attempt successful
provisioning. Please be aware of this when testing.

Unsuccessful Network Token Provisioning

Use these test card numbers to test unsuccessful provisioning of network tokens.

Test Card Numbers for Unsuccessful Network Token Provisioning

Card Brand PAN Failure Reason
American 370000000XXXX28 CARD_NOT_ELIGIBLE
Express
American 3700000000XXXX2 DECLINED
Express
American 37000000XXXX119 SERVICE_UNAVAILA
Express BLE
American 370000000XXXX36 CARD_NOT_ALLOWED
Express

Token Management Service | Requesting the Token Management Service API | 52

Token Management Service Onboarding
This section contains information necessary to onboard merchants and TMS vault management:

• Merchant ID Hierarchy (on page 53)

• Merchant ID Registration (on page 54)

• Portfolio MIDs for Partners (on page 54)

• Token Vault Management (on page 55)

• Message-Level Encryption Keys (on page 55)

Merchant ID Hierarchy
The Business Center is an online portal provisioned to partners and end merchants. This portal
can be used to onboard merchants, view transactional activity and generate and download reports
among other things.

There are two environments associated with the Business Center. Each has its own corresponding
URL in order to gain access to the Business Center for the relevant environment:

Test: https://businesscentertest.cybersource.com

Production: https://businesscenter.cybersource.com

In order to gain access to Business Center partners/merchants must be provisioned with an

Organization ID, otherwise known as a merchant ID (MID). There are multiple types of MIDs:

• Portfolio: typically a MID that provisioned to partners. Allows partners to onboard merchants
into in either a test or production environment.

• Merchant: This is a parent MID that can house multiple transactional MIDs. This will be
directly associated with the end merchant and will be created by the partner under the
portfolio MID. This MID will be attached to specific functionality such as the token vault (Token
Management Service vault).

• Transactional: This is a child MID. Each partner’s end merchant may have multiple
transactional MIDs. The transactional MID is typically used for processing into Token
Management Service, for example, to provision a network token via the Token Management
Service API. This will be directly associated with the partners end merchant and will be created
by the partner under the portfolio MID.

Token Management Service | Token Management Service Onboarding | 53

Merchant ID Registration
A Cybersource MID is a unique value within Cybersource that you define during account registration.
Your MID identifies your merchant account and payment configuration within Cybersource systems.
You provide this identifier when you sign in to the Business Center and submit transactions to
Cybersource.

Multiple MIDs can be configured for various token types. You receive the instrument identifier token
regardless of your account’s token type. Reasons for multiple MIDs include:

• You have multiple processors.

• Point-of-sale terminals have unique MIDs, which are usually configured for the PAN-only
instrument identifier token.

When you have multiple MIDs, you can set up one token vault to which all of your MIDs have access
or set up multiple vaults to limit access to tokens. See Token Vault Management (on page 55) for
more information on setting up and managing your token vault.

Create an Evaluation Account

To create an evaluation account, visit the Business Center Evaluation Account Sign-Up page.

To complete the registration process, follow the email instructions that you received to activate your
merchant account, and log in to the Business Center.

Send your merchantID to TMS representative supporting you with integration to create a vault and
enable Token Management Service with network tokens.

Portfolio MIDs for Partners

Partners will need to onboard merchants using a portfolio MID. To create a portfolio MID, contact
Cybersource support. For information about creating a portfolio MID, visit the Support Center:

http://support.cybersource.com

Customer support will respond with a questionnaire. The below information will need to be
completed:

• Organization ID: Portfolio MID name

• Environment: Test and Production

• Business information: The business name and address

Token Management Service | Token Management Service Onboarding | 54

 • Business contact: The contact that receives an email registration link to gain access to
Business Center through the portfolio MID.

• Technical contact: The contact that receives automatically generated notifications, such as
product updates, as well as non-urgent notifications.

• Emergency contact: The contact that receives urgent messages such as service outage
notifications

• Merchant notifications: This will send a welcome email to the business contact associated
with the end merchant.

• Processing information: Not applicable.

• Product information: TMS only

• Customer Support: Not applicable.

• Branding: Not applicable.

Token Vault Management

Token vaults are where merchants store their customer and payment data. A Business Center
internal user can enable the TMS vault.

Vaults are assigned to an owner, and all data within the vault belongs to the owner. You can grant
permission to individual MIDs to create, retrieve, update, and delete tokens within a vault. Created
tokens belong to the owner of the vault, not the creator of the token. If you remove a MID from a
vault, it can no longer access any tokens within that vault, including tokens created under that MID.

Important: It is not currently possible to merge vaults, so ensure that merchants are set up
with the correct vault by creating a new vault or granting access to an existing vault.

Message-Level Encryption Keys

When events contain personally identifiable information, such as payment information, the
notifications are sent using message-level encryption. Before you can send requests for Cybersource
services using message-level encryption (MLE), you must go to the Business Center and create an
MLE security key for your Cybersource merchant account.

MLE keys expire after 3 years.

Token Management Service | Token Management Service Onboarding | 55

Security keys can be used to make any request, including payments. Treat your security keys as you
would any secure password.

You must use separate keys for the test and production environments.

To create an MLE key, see Creating a Message-Level Encryption Key (on page 56).

Creating a Message-Level Encryption Key

Follow these steps to create a message-level encryption key:

1. Log in to the Business Center.

2. On the left navigation panel, click Payment Configuration.

3. Click Key Management.

The Key Management page appears.

4. Click + Generate Key.

The Create Key page appears.

5. Select Message-Level Encryption and click Generate Key.

6. Enter the string into the text field, and click Create Key.

Token Management Service | Token Management Service Onboarding | 56

Network Tokenization
This section contains information on network tokenization:

• Network Token Enablement (on page 57)

• Network Token Onboarding—Partner Model (on page 57)

• Token Requestor IDs (on page 60)

Network Token Enablement

Network token enablement is currently a manual process and requires a request to be sent to
Cybersource support. For more information about network token enablement, visit the Support
Center:

http://support.cybersource.com

Important: Before sending the request, you must ensure that the merchant/parent MID has
been created and the TMS product is enabled.

Network Token Onboarding—Partner Model

This workflow shows the merchant onboarding process.

The workflow begins when the partner creates a merchant profile on the Cybersource platform using
TMS templates.

Token Management Service | Network Tokenization | 57

 Network Token Onboarding for Partners

1. The gateway sets up templates for TMS.

2. partner creates merchant profile using TMS templates.

3. The partner submits a request to Cybersource via API.

4. Cybersource creates a merchant based on the API request and confirms boarding success with
partner.

5. The partner provides merchant details via email to enable network tokenization and submits
email to Cybersource support.

6. Cybersource verifies the request, generates the onboarding request, and sends the request to
the card brand.

7. The card brand completes the registration process and responds to Cybersource with the
confirmation and token requestor ID (TRID).

8. Cybersource notifies the partner that onboarding is complete.

9. The partner completes merchant setup.

Token Management Service | Network Tokenization | 58

Network Token Life-Cycle Management
Life-cycle management is a key feature of credentials-on-file (COF) network tokenization. Issuers can
keep COF network tokens updated as changes are made to their cardholders' accounts. TMS notifies
you in real time when updates are made to a card represented by the COF network token in your TMS
vault. Issuers push the life-cycle management updates either in real time or via a batch process to the
card brands. Life-cycle updates and timelines will vary by issuer based on their update process. For
example, TMS notifies you when a card becomes inactive.

There are two distinct types of life-cycle management events:

• COF token status changes. Token statuses are:

◦ ACTIVE: The account and network token are active and in good standing.

When COF network tokens are active, merchants can process transactions according to
their COF agreement.

◦ SUSPENDED: This status is temporary for COF network tokens and can change to ACTIVE
or DELETED. Merchants should not send authorizations on suspended tokens. However,
these tokens can be re-activated by the issuer later. Suspended COF network token events
are usually triggered according to cardholder instruction or flagged by the issuer for
suspected fraudulent activity. When the status changes from SUSPENDED to ACTIVE or
DELETED, a merchant receives a life-cycle management update.

Merchants can proactively contact a cardholder to update the credential or have them
contact the issuer to reactivate the credential.

◦ DELETED: This is the final state for a network token. A network token can be deleted when
the account is closed or on cardholder instruction.

Merchants must request a new credential from the cardholder.

• PAN updates to the COF network token:

◦ NEW PAYMENT ACCOUNT NUMBER: A new PAN has been provisioned for the network token.

Merchants can retrieve the new PAN suffix (last four digits) and the new expiration date
to store in their cardholder records.

◦ NEW PAYMENT ACCOUNT EXPIRY: A new expiration date has been provided by the issuer
associated with the PAN.

Merchants can retrieve the new expiration date and store it in their cardholder records.

Token Management Service | Network Tokenization | 59

Network Token Life-Cycle Management Reports
You can generate reports that contain Life-Cycle Management events for Network Tokens.
These reports include network token-related fields that are updated as a result of the Life-Cycle
Management events sent to the Token Management Service.

For more information about how to generate these reports in the Business Center, see the Reporting
User Guide.

For more information about how to generate these reports using the Reporting API, see the Reporting
API.

The Reporting User Guide and the Reporting Developer Guide contain these relevant topics:

• Downloading Available Reports

• Creating Custom Reports

• Subscribing to Standard Reports

• Fields and Descriptions for Downloadable Reports

Token Requestor IDs

A token requestor ID (TRID) is a unique identifier to allow entities such as merchants to request
network tokens from token providers and is a prerequisite for enabling network tokenization.

Each entity must register with the token provider to get the TRID. Contact a Cybersource
representative to onboard a merchant as a token requestor.

Visa and Mastercard TRIDs

An internal user can enroll a merchant as a VISA or Mastercard token requestor through the Business
Center:

1. Navigate to Token Management.

2. Select Vault Management.

3. Under the TMS Vault and Network Tokenization option, select Enroll to VISA/Mastercard
token services.

After enroll is submitted, the relationshipID and TRID is filled on the screen for VTS and TRID for
Mastercard.

Token Management Service | Network Tokenization | 60

In order to request a TRID to the token provider, Cybersource uses merchant business details already
stored. If any of the details are not present, a dialog form should appear prompting you to complete
the missing fields.

American Express TRIDs

Enrollment as a token requestor for American Express tokens is still a manual process. Contact your
Cybersource representative to request the TRID to American Express.

Please allow 2 to 3 days for the completion of your request.

Important: SE Numbers are required to process American Express card transactions.

Token Management Service | Network Tokenization | 61

Manage Webhook Subscriptions
This section contains information on creating, retrieving, and updating webhook subscriptions.
You can create, retrieve, update, or delete notification subscriptions different events by submitting
an HTTP POST, GET, PATCH, or DELETE request to the notification-subscriptions/v1/webhooks
endpoint. Use the webhooks REST API to:

• Create Keys for Digital Signature (on page 64)

• Create Webhook Subscription (on page 66)

• Retrieve Webhook Subscription Details (on page 69)

• Update Webhook Subscription (on page 71)

• Delete Webhook Subscription (on page 73)

When you send an API request to create a webhooks subscription, you must include the product and
its associated events to which you are subscribing.

You can create webhooks subscriptions for these Token Management Service network token events:

Token Management Service

Product ID Event Types Description
tokenManagement tms.networktoken.updated Notifies you
of a network
token's change
in expiration
date or status
(suspend, resume,
or deactivate).
tms.networktoken.provisioned Notifies you when
a network token
provision for
an instrument
identifier
token has been
successful.

Token Management Service | Manage Webhook Subscriptions | 62

Example: Product and Network Token Events in a Webhook Subscription

"productId": "tokenManagement",
"eventTypes": [
"tms.networktoken.provisioned",
"tms.networktoken.updated"
]

For more info, see the Webhooks Developer Guide .

Token Management Service | Manage Webhook Subscriptions | 63

Create Keys for Digital Signature
This section shows you how to create keys for digital signature.

Endpoint

Test: POST https://apitest.cybersource.com/kms/egress/v2/keys-sym

Production: POST https://api.cybersource.com/kms/egress/v2/keys-sym

Production in India: POST https://api.in.cybersource.com/kms/egress/v2/keys-sym

Required Fields for Creating Keys for Digital Signature Using the REST
API
clientRequestAction

keyInformation.provider

keyInformation.tenant

keyInformation.keyType

keyInformation.organizationId

REST Example: Creating Keys for Digital Signature

Request

POST https://apitest.cybersource.com/kms/egress/v2/keys-sym

{
"clientRequestAction": "CREATE",
"keyInformation": {
"provider": "nrtd",
"tenant": "testrest",
"keyType": "sharedSecret",
"organizationId": "testrest"
}
}

Token Management Service | Manage Webhook Subscriptions | 64

Response to a Successful Request

{
"submitTimeUtc": "2023-02-10T21:26:58Z",
"status": "SUCCESS",
"keyInformation": {
"provider": "nrtd",
"tenant": "testrest",
"organizationId": "testrest",
"keyId": "f4602849-1466-7937-e053-5a588d0ac970",
"key": "CWK8MHJbHldt74kftIP/+0tTG89We+SWkS7qXjiVJJA=",
"keyType": "sharedSecret",
"status": "active",
"expirationDate": "2026-02-09T21:26:58Z"
}
}

Token Management Service | Manage Webhook Subscriptions | 65

Create Webhook Subscription
This section shows you how to create a webhook subscription.

Endpoint

Test: POST https://apitest.cybersource.com/notification-subscriptions/v1/webhooks

Production: POST https://api.cybersource.com/notification-subscriptions/v1/webhooks

Production in India: POST https://api.in.cybersource.com/notification-subscriptions/

v1/webhooks

Required Fields for Creating Webhook Subscription Using the REST

API
clientRequestAction

keyInformation.provider

keyInformation.tenant
The value must be set to nrtd.
keyInformation.keyType

keyInformation.organizationId

keyInformation.expiryDuration

REST Example: Creating a Webhook Subscription

Request

POST https://apitest.cybersource.com/notification-subscriptions/v1/webhooks

{
"organization": {"organizationId": "testrest"},
"product": {"productId": "tokenManagement"},
"webhook": {
"webhookId": "e33b4ff7-f94a-2de4-e053-a2588e0a0403",
"webhookUrl": "https://URL",
"createdOn": "2021-12-15 23:46:00.053",

Token Management Service | Manage Webhook Subscriptions | 66

 "eventTypes": [
{"name": "tms.networktoken.provisioned"},
{"name": "tms.networktoken.updated"}
],
"status": "ACTIVE",
"retryPolicy": {
"algorithm": "ARITHMETIC",
"firstRetry": 5,
"interval": 5,
"numberOfRetries": 4,
"deactivateFlag": false,
"repeatSequenceCount": 4,
"repeatSequenceWaitTime": 5
},
"securityPolicy": [ {
"digitalSignatureEnabled": "yes",
"proxyType": "external",
"security_id": "c05cc30a-ce9b-487f-be38-65ab5977b5bc",
"security_type": "key"
}]
}
}

Token Management Service | Manage Webhook Subscriptions | 67

Response to a Successful Request

{
"organizationId": "testrest",
"productId": "terminalManagement",
"eventTypes": [
"tms.networktoken.provisioned",
"tms.networktoken.updated"
],
"webhookId": "e33b4ff7-f94a-2de4-e053-a2588e0a0403",
"webhookUrl": "https://NewURL",
"healthCheckUrl": "https://URL",
"createdOn": "2022-07-07 17:24:05.116",
"status": "ACTIVE",
"retryPolicy": {
"algorithm": "ARITHMETIC",
"firstRetry": 1,
"interval": 1,
"numberOfRetries": 3,
"deactivateFlag": false,
"repeatSequenceCount": 0,
"repeatSequenceWaitTime": 0
},
"securityPolicy": {
"securityType": "KEY",
"proxyType": "external",
"digitalSignatureEnabled": "yes"
},
"version": "3",
"deliveryType": "nrtdCentral",
"notificationScope": "DESCENDANTS"
}

Token Management Service | Manage Webhook Subscriptions | 68

Retrieve Webhook Subscription Details
This section shows you how to retrieve webhook subscription details.

Endpoint

Test: GET https://apitest.cybersource.com/notification-subscriptions/v1/webhooks/{webhookID}

Production: GET https://api.cybersource.com/notification-subscriptions/v1/webhooks/

{webhookID}

Production in India: GET https://api.in.cybersource.com/notification-subscriptions/

v1/webhooks/{webhookID}

Required Field for Retrieving Webhook Subscription Details Using the

REST API
webhookID
Include the ID of the webhook you would like to update.

REST Example: Retrieving Webhook Subscription Details

Request

GET https://
apitest.cybersource.com/notification-subscriptions/v1/webhooks/e33b4ff7-f94a-2de4-e053-a25
88e0a0403

Token Management Service | Manage Webhook Subscriptions | 69

Response to a Successful Request

{
"organizationId": "testrest",
"productId": "tokenManagement",
"eventTypes": [
"tms.networktoken.provisioned",
"tms.networktoken.updated"
],
"webhookId": "e33b4ff7-f94a-2de4-e053-a2588e0a0403",
"webhookUrl": "https://URL",
"healthCheckUrl": "https://jURL",
"createdOn": "2022-07-07 17:24:05.116",
"status": "ACTIVE",
"retryPolicy": {
"algorithm": "ARITHMETIC",
"firstRetry": 1,
"interval": 1,
"numberOfRetries": 3,
"deactivateFlag": false,
"repeatSequenceCount": 0,
"repeatSequenceWaitTime": 0
},
"securityPolicy": {
"securityType": "KEY",
"proxyType": "external",
"digitalSignatureEnabled": "yes"
},
"version": "3",
"deliveryType": "nrtdCentral",
"notificationScope": "DESCENDANTS"
}

Token Management Service | Manage Webhook Subscriptions | 70

Update Webhook Subscription
This section shows you how to update a webhook subscription.

Endpoint

Test: GET https://apitest.cybersource.com/notification-subscriptions/v1/webhooks/{webhookID}

Production: GET https://api.cybersource.com/notification-subscriptions/v1/webhooks/

{webhookID}

Production in India: GET https://api.in.cybersource.com/notification-subscriptions/

v1/webhooks/{webhookID}

Required Field for Updating Webhook Subscription Using the REST

API
webhookID
Include the ID of the webhook you would like to update.

REST Example: Updating Webhook Subscriptions

Request

PATCH https://
apitest.cybersource.comnotification-subscriptions/v1/webhooks/e33b4ff7-f94a-2de4-e053-a258
8e0a0403

{
"description": "Update to my sample webhook",
"organizationId": "testrest",
"productId": "terminalManagement",
"webhookUrl": "https://NewURL"
}

Token Management Service | Manage Webhook Subscriptions | 71

Response to a Successful Request

{
"organizationId": "testrest",
"productId": "terminalManagement",
"eventTypes": [
"tms.networktoken.provisioned",
"tms.networktoken.updated"
],
"webhookId": "e33b4ff7-f94a-2de4-e053-a2588e0a0403",
"webhookUrl": "https://NewURL",
"healthCheckUrl": "https://URL",
"createdOn": "2022-07-07 17:24:05.116",
"status": "ACTIVE",
"retryPolicy": {
"algorithm": "ARITHMETIC",
"firstRetry": 1,
"interval": 1,
"numberOfRetries": 3,
"deactivateFlag": false,
"repeatSequenceCount": 0,
"repeatSequenceWaitTime": 0
},
"securityPolicy": {
"securityType": "KEY",
"proxyType": "external",
"digitalSignatureEnabled": "yes"
},
"version": "3",
"deliveryType": "nrtdCentral",
"notificationScope": "DESCENDANTS"
}

Token Management Service | Manage Webhook Subscriptions | 72

Delete Webhook Subscription
This section shows you how to delete a webhook subscription.

Endpoint

Test: DELETE https://apitest.cybersource.com/notification-subscriptions/v1/webhooks/

{webhookID}

Production: DELETE https://api.cybersource.com/notification-subscriptions/v1/webhooks/

{webhookID}

Production in India: DELETE https://api.in.cybersource.com/notification-subscriptions/

v1/webhooks/{webhookID}

Required Field for Deleting a Webhook Subscription Using the REST

API
webhookID
Include the ID of the webhook you would like to update.

REST Example: Deleting a Webhook Subscription

Request

DELETE https://
apitest.cybersource.com/notification-subscriptions/v1/webhooks/{{tms-webhook-id}}

Token Management Service | Manage Webhook Subscriptions | 73

Response to a Successful Request

A successful delete response returns an empty HTTP 204 No Content status. For more information, see
HTTP Status Codes (on page 321).

Token Management Service | Manage Webhook Subscriptions | 74

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.

Related information
Manage Customer Tokens (on page 75)
Payments with Customer Tokens (on page 93)

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 (on page 76)

• Retrieve a customer token (on page 79)

• Update a customer's information (on page 81)

• Delete a customer token (on page 84)

For more information on customer tokens, see Customer Tokens (on page 21).

Token Management Service | Customer Tokens | 75

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

Required Fields for Creating a Customer Using the REST API

You can include any of the following fields in the body of the request:
buyerInformation.merchantCustomerID

buyerInformation.email

clientReferenceInformation.code

merchantDefinedInformation.name

merchantDefinedInformation.value

Related Information

• API Field Reference for the REST API

REST Example: Creating a Customer

Request

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

{
"buyerInformation": {
"merchantCustomerID": "Your customer identifier",
"email": "[email protected]"
},

Token Management Service | Customer Tokens | 76

 "clientReferenceInformation": {
"code": "123456"
},
"merchantDefinedInformation": [
{
"name": "data1",
"value": "Your customer data"
}
]
}

Token Management Service | Customer Tokens | 77

Response to a Successful Request

{
"_links": {
"self": {
"href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078"
},
"paymentInstruments": {
"href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/payment-instruments"
},
"shippingAddresses": {
"href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/shipping-addresses"
}
},
"id": "F2F3ADA770102B51E053A2598D0A9078",
"buyerInformation": {
"merchantCustomerID": "Your customer identifier",
"email": "[email protected]"
},
"clientReferenceInformation": {
"code": "TC50171_3"
},
"merchantDefinedInformation": [
{
"name": "data1",
"value": "Your customer data"
}
],
"metadata": {
"creator": "testrest"
}
}

REST Interactive Example: Creating a Customer

Live Console URL: https://developer.cybersource.com/api-reference-assets/index.html#token-
management_customer_create-a-customer

Token Management Service | Customer Tokens | 78

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 id field when you created the
customer token. For more information, see Create a Customer (on page 76).

REST Example: Retrieving a Customer

Request

Pass the customer token ID in the URL path.

GET https://apitest.cybersource.com/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078

Token Management Service | Customer Tokens | 79

Response to a Successful Request

{
"_links": {
"self": {
"href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078"
},
"paymentInstruments": {
"href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/payment-instruments"
},
"shippingAddresses": {
"href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/shipping-addresses"
}
},
"id": "F2F3ADA770102B51E053A2598D0A9078",
"buyerInformation": {
"merchantCustomerID": "Your customer identifier",
"email": "[email protected]"
},
"clientReferenceInformation": {
"code": "TC50171_3"
},
"merchantDefinedInformation": [
{
"name": "data1",
"value": "Your customer data"
}
],
"metadata": {
"creator": "testrest"
}
}

Token Management Service | Customer Tokens | 80

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 id field when you created the
customer token. For more information, see Create a Customer (on page 76). Include only the fields
you want to add or update in the request.

Required Fields for Updating a Customer

customerTokenId
Include the ID of the customer token you want to retrieve in the URL path.

Related information
API Field Reference for the REST API

Optional Fields for Updating a Customer

You can include any of the following fields in the body of the request:
buyerInformation.merchantCustomerID

buyerInformation.email

clientReferenceInformation.code

merchantDefinedInformation.name

merchantDefinedInformation.value

Related Information

• API Field Reference for the REST API

Token Management Service | Customer Tokens | 81

REST Example: Updating a Customer

Request

Pass the customer token ID in the URL path.

PATCH https://apitest.cybersource.com/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078

Token Management Service | Customer Tokens | 82

Response to a Successful Request

{
"_links": {
"self": {
"href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078"
},
"paymentInstruments": {
"href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/payment-instruments"
},
"shippingAddresses": {
"href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/shipping-addresses"
}
},
"id": "F2F3ADA770102B51E053A2598D0A9078",
"buyerInformation": {
"merchantCustomerID": "Your customer identifier",
"email": "[email protected]"
},
"clientReferenceInformation": {
"code": "TC50171_3"
},
"merchantDefinedInformation": [
{
"name": "data1",
"value": "Your customer data"
}
],
"metadata": {
"creator": "testrest"
}
}

REST Interactive Example: Updating a Customer

Live Console URL: https://developer.cybersource.com/api-reference-assets/index.html#token-
management_customer_update-a-customer

Token Management Service | Customer Tokens | 83

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 id field when you created the
customer token. For more information, see Create a Customer (on page 76).

Required Fields for Deleting a Customer Token

customerTokenId
Include the ID of the customer token you want to retrieve in the URL path.

Related Information

• API Field Reference for the REST API

REST Example: Deleting a Customer

Request

Pass the customer token ID in the URL path.

DELETE https://apitest.cybersource.com/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078

Token Management Service | Customer Tokens | 84

Response to a Successful Request

A successful delete response returns an empty HTTP 204 No Content status. For more information, see
HTTP Status Codes (on page 321).

Token Management Service | Customer Tokens | 85

Retrieve a Customer's Default Payment with Unmasked Card
Number
This section shows you how to retrieve a customer's default payment with unmasked card number.

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 id field when you created the
customer token. For more information, see Create a Customer (on page 76).

Important: You must pass the following request header to get this functionality: Accept:
application/jose.

REST Example: Retrieving a Customer's Default Payment with

Unmasked Card Number

Request

GET https://apitest.cybersource.com/tms/v2/customers/F45FB3E443AC3C57E053A2598D0A9CFF

Token Management Service | Customer Tokens | 86

Response to a Successful Request

eyJraWQiOiJiYTE1ZDRmMTIzMTM0NjlkZjg5MDM1Nzk2YWE4Nzc4ZGM0NTY4ODlkIiwiY3R5IjoianNvbiIsInR5cC
I6IkpXVCIsImVuYyI
6IkEyNTZHQ00iLCJhbGciOiJSU0EtT0FFUC0yNTYifQ.zxPTNWvHt40Dbtwlx2T53Jd-vazzEeN7v_6nyyPE8FpAyl
O9dMCQL0XOG_1AQZR
ZPhrAvilhV2Gp8xc1OuF6w0w8LtDQGcgoTVQM0HitMXSs05b_0FzYNZXHr9OPwmJxzizNoptI-Arlw55yfJNM8QNBL
YGIEJkKI061P84Dk9
by-c3bfo8z8D0xO4LpA51dndSkk5QFIWaNSz5CC0nuANyPPJzGVLguBx8HYNLMH4g_dx6SEVw-QYBO0-s_Xfmv3wRj
GpH0STzn7j_1MxpW7
tfXaYcrglPNCoOiSHc6dg141lHGSdvALS71qZTo49WVWbuO2kBYyhxVD1x_1P4ztQ.D1H34AH9Rwu1cr5F.dqCwRR8
Ug8uv1Ow437anK8br
Ye7KPWfcw_R7ShoIlNhWCmQcQ9mVK8UCKcbuVbxt7S6_whJHOfWlm1jqwIvA7ZYtHfVyVHsG11wRZZd3vn4HGJ4rAU
a3T0d_EnvF2Jeffpj
cTG6MZN5_nB4z2Ism4dLcxsnWIdzU2993hscS5641wvX3GYAhqD5OqweT1hqW8URyuSQh27WDJSlMmARE0s3hVq6O0
XcdejOmulyVKMNFFp
Wpcif3G-VnTMzDI7iMx448u2tClA895cvG-E4ISDvRZ3eIjH4wgRE5Btxy5SwbS7VfCYDyRLa9z1LewRV3EwFxvb6_
POtq2Da5QYSG7U-XO
aSNie6bZ7oTYKn7lD-1-crcfQY6ieSWUxMKcsi3bD0_yz1Y_Lc0Wc4M7MCIRwDmbctmZvxZuRwiBiSMsKll9gQdKTn
8sEeGv7DWooJBxqiZ
kbPlzkHnw2El4Z9HETIGH1Iq0nsKC78NzTiT96i0SHN22iqZGYdIUPwB9zZJQGJNxZ3ag_Cf4C6ATAubJG4jVtdQ_J
tbhHLYwhXlQFTiPMQ
rqnoh7GZDaOX3jEP9_LQiNam8U-ZNGuQby2jgqPyLQKb4dsB31eBz9TLCa7SkXqWp5_a18QVpNxeQEB0mJC7s0iy3X
XB7GxxzrKLgqsxhmJ
ZjLaKUo1-Sen3HG_9oWTlXXh2r2C0b3AzX1HQ8POC5E8RcK7e-tLtvMJrLNHMZXRVAeREbVah13b1Fs-CIDWnw9QcC
UxjfYNCwwOZUAZTIX
tq4YnaQYkSE6OJV-yRrajbo7CzM1HXZEioW9S9eFRJmqKpu_vtatwJXme3XjyjAqahSYCBtIx2__8688MpTmSm1_WE
OZrNXoV0-htOqQAQ4
IIza4FpWfpevUJUs8hOu2FIr_Adm0-IIE2MsSptXrNvxmahuDwNpmapNUeLg7aZoQVlp33TrwcQ0AfQeD36s1nkWOh
RmPfjVfXvKCeJxmD2
ndXBJxLzko0BkqWwe9WSH-RDyaN3u7TXHgyp2EDO0p6rRO8F2veRv76T6ppMrGWK9xjZLFaA1kNNt_RTlsn1hedb_R
-ztOw-4y4u405yv8E
2z0W0mE58FLlWJ7AORSQjEtVANrlnwzLjE4xi_xv41CrwI8_uhlyQFfy0aj13bOyFg5nQd7k1MsawzFJfsNBRrCNwf
07cpP_4nH_yv4UvV4
qSaf1DR0epfQ4iWvaZOWqhN_vJeAxXAasChiuZJ8gN2qrq_p1fO4lGIUjLcyvn9W1fqDVcgLLZUVCcHdHiFpZT7C6i
KqDQBjUaAQ6E-jsES
0t2EmwkkJ21jxnwUtwCQLShXNUjXDjwKrbAiFAiHrBALXJnBY5Yd0JkJ7srB4dWR4lZxb5M5g9n-gUkto8O_u1JtII
34EgbKbOHbpbOgCEN
rGUnjaIXrTVHy1uWBBTV7gmkkqd1HD9lwqbmj4IDyIdUwjkUJ4ZX9MB_E7PJ_asWnye5-RO3vFlL7_dSQkmJAiseNr
ve0bTlynMZW-KsC9s
0We-jjDqJP52uZ-jmJwL1hhIUef3Yt40IytfuyxiIWkGJB0qM2cppdh6F8bdbFxomWeOxFW8qllZ-1hhp5ISoW6oy8
f6OyvIxFQMjkXMfoh
CdBwB3wOZYoCPq2JmrXYExQcStI3MHMkvBkNP5slTX-uT-mJlx5XHLLOPdO9io58D0CEcmdDAiZqPtQssaFKsj4Z6E
MlgewmC8E7mO6LLhF
Fcof_qDaJ7d6ZNnUiVUq0tAQnxiBH6NfKybQ64O_j2yq4bE1Fzc_aOM5YcQqch8riYU0VWeS0xzgdetta8AYTjmIGE
1SKhvEh_KxngNK6Rn
4GiE_-g6tQaI65ZJ9OMfVdzVbuBJ04IU1VI9KPZhAAd_xZYOnKzkaKHlogkMOaI-Pz-CKP4Ij-hrjzNIHHI8dHtXcL
T5e4BGFksN87UGvJu

Token Management Service | Customer Tokens | 87

PDJEqpCOXcvxRKe5C0129SSMGq_MefP04pkHAnKQ1qg_gIlxz7H2lvCKGBrgnm6yfE1kD9CYqtHdDZlgcZY_dl56MR
pW8fOs5xtaDVgTlme
kd4qtt59R6FpN1LQFmpKIqza5AJqPinUaZJSxvF6nkK76xx8ozxFIFitygAkK6eh8fTiuArXkTul0E3277fg-gCv9h
2xz0CnDnNV5ubLfJp
2QDboy-JRE_NFN3E0eqr5MkGETtiXeGyQTGwFtr0KuvsZu4V8qg1DxiF_pPdlszTyhGL2q21Vcr2IBDzrgNKkGDLPv
PXUVIjHA1XM-4dnv9
ZIx0Eb5jsGQhecQrmQaH4wcM3ZE2sWPGwLJutbVuywSnQg6YWz-PAQDk2Er4icNuybTrdw4RoZPNzY-2BGxWrpbo4J
4SMK84jmsxPatCI1s
I12uhXp27LrtHEUfHHLVlFw2KHIpCWirQ7mLicp7Be1dAx3ak-RapHaH9qTVkDuMVuWIzvaj6ulY2mBltcSMyFpr7_
vEGYY3LEU8_Udnvyn
SwKuXqt3MiHE0h2bEeL6X6YXC2D8iOEgsIEh6naEyKxhdfzk0BpM1MyLnAqkr34BoJhyrM_P0ZfRF4YNauqVqvr0qA
ZN757nRwHcPfDal22
jnVdxd65TRUtymqV5gnfKNVBFF5NfjU0zcuK3kr3llkSHaULobBOlJ3W-tBx37-0cjuXqci_ZgbRnVCbF3TnOe_kUL
rPLrGakcjOfVOXNhg
ckSR6Rz3At7MIhzAhKCtZm3qyxcARxrMGMrIcW3ShE62DfOOlTLotq9TJCkyI6LI93TBtQOlYnDZNcU4KW9hFqo0ZA
Cy9cbEHA_LNUFtwUL
spFw_gu3AlUTFp3LDRDAGu9_4Ip-aw4xCPOWN7-oNuzfpasdFx7IioHahxvBi1HmMUsn09p96finQndMoByC8enwwB
ILNKJ9BBEgS0jaQn7
Ymag4G1xArMNnECF2ip7CDWc9dvivhHxS_AftERedVYksH7XP3YEMUoOlsOrwVhGGArZrWpHmNcX0woTvK9lJLjxHM
l9w6lhhcvY3X-glV5
AKJczoDnVJe-6Q9cnH0BYE8b_0LgdlcN7dVGEXkjR9EAm0bsytEO6zm53u-zRwq5wzBVBA7WMBuQLPjyvUB9WPueBf
KPhJhnYIYKCZZplRw
RxGg04RKkwl8nKGMSfpITD0L6NiYWg-aS7aSQVa21RpYxZoCr9t2lFo8gxe0Lhr5mGZRLv_toZ5wuxViHUPTvtG-UV
v6IS3M4k6GTzSh90j
OOBeDfChJzPLXzQWLsIYTUfzmEbkcncuo7c8auEgEabcfo4q7loiCuK_QODY_wB6_PDh6rWhINsAN0KC27sPcv0rIk
ADo9uDGhKCPb314EK
9RhUUsGBJjOvxX1oKfy0OXfURdYeG8DC6zCZtazrX6DO12rcsZlCPu2Fj1ZPWoAdKYqUAaeX8DdYBAFhvmhxuLlmXY
W4zPj89ZhDrbSDCxs
e0w6rlWbXTaEkiqc3-4S8Az3DJG73jSMB58PtAKUHfpjWR9sp0TLtpfxw_XPtwbE_7EHmchQqNq9zFiB0F6Cxu1
eF-5eObABh-EEpQ68Ppp
3zuorFSSNUuW-nKGl_Eio6gPyUYuMSen8zA.BARlPgBMj068Dt6OGEiPnA

Token Management Service | Customer Tokens | 88

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 id field when you created the
customer token. For more information, see Create a Customer (on page 76).

REST Example: Retrieving a Customer's Default Payment and Shipping

Details

Request

GET https://apitest.cybersource.com/tms/v2/customers/F45FB3E443AC3C57E053A2598D0A9CFF

Token Management Service | Customer Tokens | 89

Response to a Successful Request

{
"_links": {
"self": {
"href": "/tms/v2/customers/F45FB3E443AC3C57E053A2598D0A9CFF"
},
"paymentInstruments": {

"href": "/tms/v2/customers/F45FB3E443AC3C57E053A2598D0A9CFF/payment-instruments"
},
"shippingAddresses": {

"href": "/tms/v2/customers/F45FB3E443AC3C57E053A2598D0A9CFF/shipping-addresses"
}
},
"id": "F45FB3E443AC3C57E053A2598D0A9CFF",
"clientReferenceInformation": {
"code": "TC50171_3"
},
"defaultPaymentInstrument": {
"id": "F45FC6785E3C31A2E053A2598D0A5346"
},
"defaultShippingAddress": {
"id": "F45FB3E443AF3C57E053A2598D0A9CFF"
},
"metadata": {
"creator": "testrest"
},
"_embedded": {
"defaultPaymentInstrument": {
"_links": {
"self": {

"href": "/tms/v2/customers/F45FB3E443AC3C57E053A2598D0A9CFF/payment-instruments/F45FC678
5E3C31A2E053A2598D0A5346"
},
"customer": {
"href": "/tms/v2/customers/F45FB3E443AC3C57E053A2598D0A9CFF"
}
},
"id": "F45FC6785E3C31A2E053A2598D0A5346",
"default": true,
"state": "ACTIVE",
"card": {
"expirationMonth": "12",
"expirationYear": "2031",
"type": "001"
},

Token Management Service | Customer Tokens | 90

 "buyerInformation": {
"currency": "USD"
},
"billTo": {
"firstName": "JOHN",
"lastName": "DEO",
"address1": "201 S. Division St.",
"address2": "Address 2",
"locality": "Ann Arbor",
"administrativeArea": "MI",
"postalCode": "48104-2201",
"country": "US",
"email": "[email protected]",
"phoneNumber": "999999999"
},
"processingInformation": {
"billPaymentProgramEnabled": false
},
"instrumentIdentifier": {
"id": "7030000000014911515"
},
"metadata": {
"creator": "testrest"
},
"_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {
"href": "/tms/v1/instrumentidentifiers/7030000000014911515"
},
"paymentInstruments": {

"href": "/tms/v1/instrumentidentifiers/7030000000014911515/paymentinstruments"
}
},
"id": "7030000000014911515",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"tokenizedCard": {
"state": "ACTIVE",
"number": "489537XXXXXX5914",
"expirationMonth": "12",
"expirationYear": "2022",
"type": "visa",
"requestorId": "40010052236",
"card": {
"suffix": "1515",
"expirationMonth": "12",
"expirationYear": "2031"

Token Management Service | Customer Tokens | 91

 }
},
"card": {
"number": "489537XXXXXX1515"
},
"issuer": {
"paymentAccountReference": "V0010013019326121174070050420"
},
"processingInformation": {
"authorizationOptions": {
"initiator": {
"merchantInitiatedTransaction": {
"previousTransactionId": "123456789619999"
}
}
}
},
"metadata": {
"creator": "testrest"
}
}
}
},
"defaultShippingAddress": {
"_links": {
"self": {

"href": "/tms/v2/customers/F45FB3E443AC3C57E053A2598D0A9CFF/shipping-addresses/F45FB3E44
3AF3C57E053A2598D0A9CFF"
},
"customer": {
"href": "/tms/v2/customers/F45FB3E443AC3C57E053A2598D0A9CFF"
}
},
"id": "F45FB3E443AF3C57E053A2598D0A9CFF",
"default": true,
"shipTo": {
"firstName": "JOHN",
"lastName": "DEO",
"company": "Visa",
"address1": "201 S. Division St.",
"address2": "Address 2",
"locality": "Ann Arbor",
"administrativeArea": "MI",
"postalCode": "48104-2201",
"country": "US"
},
"metadata": {
"creator": "testrest"

Token Management Service | Customer Tokens | 92

 }
}
}
}

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 (on page 94)

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 (on page 99)

• Making a Credit with a Customer Token (on page 106)

For more information on customer tokens, see Customer Tokens (on page 21).

Token Management Service | Customer Tokens | 93

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

Required Fields for Creating a Customer Token with Validated

Payment Details Using the REST API
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount

orderInformation.billTo.address1

orderInformation.billTo.administrativeArea

orderInformation.billTo.country

orderInformation.billTo.email

orderInformation.billTo.firstName

orderInformation.billTo.lastName

orderInformation.billTo.locality

orderInformation.billTo.postalCode

paymentInformation.card.expirationMonth

paymentInformation.card.expirationYear

paymentInformation.card.number

paymentInformation.card.type

processingInformation.actionList
Set the value to TOKEN_CREATE.
processingInformation.actionTokenTypes
Set the value to customer.

Token Management Service | Customer Tokens | 94

Related Information

• API Field Reference for the REST API

REST Example: Creating a Customer Token with Validated Payment

Details

Request

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

{
"clientReferenceInformation": {
"code": "TC50171_3"
},
"processingInformation": {
"commerceIndicator": "internet",
"actionList": [
"TOKEN_CREATE"
],
"actionTokenTypes": [
"customer",
"paymentInstrument",
"shippingAddress"
]
},
"orderInformation": {
"billTo": {
"country": "US",
"lastName": "Deo",
"address2": "Address 2",
"address1": "201 S. Division St.",
"postalCode": "48104-2201",
"locality": "Ann Arbor",
"administrativeArea": "MI",
"firstName": "John",
"phoneNumber": "999999999",
"district": "MI",
"buildingNumber": "123",
"company": "Visa",
"email": "[email protected]"
},
"shipTo": {
"country": "US",
"lastName": "Deo",

Token Management Service | Customer Tokens | 95

 "address2": "Address 2",
"address1": "201 S. Division St.",
"postalCode": "48104-2201",
"locality": "Ann Arbor",
"administrativeArea": "MI",
"firstName": "John",
"phoneNumber": "999999999",
"district": "MI",
"buildingNumber": "123",
"company": "Visa",
"email": "[email protected]"
},
"amountDetails": {
"totalAmount": "102.00",
"currency": "USD"
}
},
"paymentInformation": {
"card": {
"expirationYear": "2031",
"number": "4895379987X11515",
"securityCode": "089",
"expirationMonth": "12",
"type": "001"
}
}
}

Token Management Service | Customer Tokens | 96

Response to a Successful Request

{
"_links": {
"authReversal": {
"method": "POST",
"href": "/pts/v2/payments/6760630088136127303955/reversals"
},
"self": {
"method": "GET",
"href": "/pts/v2/payments/6760630088136127303955"
},
"capture": {
"method": "POST",
"href": "/pts/v2/payments/6760630088136127303955/captures"
}
},
"clientReferenceInformation": {
"code": "TC50171_3"
},
"id": "6760630088136127303955",
"orderInformation": {
"amountDetails": {
"authorizedAmount": "102.00",
"currency": "USD"
}
},
"paymentAccountInformation": {
"card": {
"type": "001"
}
},
"paymentInformation": {
"tokenizedCard": {
"type": "001"
},
"card": {
"type": "001"
}
},
"pointOfSaleInformation": {
"terminalId": "111111"
},
"processorInformation": {
"paymentAccountReferenceNumber": "V0010013019326121174070050420",
"approvalCode": "888888",
"networkTransactionId": "123456789619999",
"transactionId": "123456789619999",
"responseCode": "100",

Token Management Service | Customer Tokens | 97

 "avs": {
"code": "X",
"codeRaw": "I1"
}
},
"reconciliationId": "69816012FDTK35GM",
"status": "AUTHORIZED",
"submitTimeUtc": "2023-02-10T21:03:29Z",
"tokenInformation": {
"instrumentidentifierNew": false,
"instrumentIdentifier": {
"state": "ACTIVE",
"id": "7030000000014911515"
},
"shippingAddress": {
"id": "F45FB3E443AF3C57E053A2598D0A9CFF"
},
"paymentInstrument": {
"id": "F45FC6785E3C31A2E053A2598D0A5346"
},
"customer": {
"id": "F45FB3E443AC3C57E053A2598D0A9CFF"
}
}
}

Token Management Service | Customer Tokens | 98

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

Required Fields for Authorizing a Payment with a Customer Token

clientReferenceInformation.code

orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount

paymentInformation.customer.id
Set to the ID of the customer token you want to use.

Related Information

• API field reference guide for the REST API

REST Example: Authorizing 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

Request

{
"clientReferenceInformation": {
"code": "12345678"
},

Token Management Service | Customer Tokens | 99

 "paymentInformation": {
"customer": {
"id": "F45FB3E443AC3C57E053A2598D0A9CFF"
}

},
"orderInformation": {
"amountDetails": {
"currency": "USD",
"totalAmount": "10.00"
}
}
}

Token Management Service | Customer Tokens | 100

Response to a Successful Request

The request response returns the payment instrument and shipping address IDs that are used as the
customer's defaults.

{
"_links": {
"authReversal": {
"method": "POST",
"href": "/pts/v2/payments/7055928871556818104953/reversals"
},
"self": {
"method": "GET",
"href": "/pts/v2/payments/7055928871556818104953"
},
"capture": {
"method": "POST",
"href": "/pts/v2/payments/7055928871556818104953/captures"
}
},
"clientReferenceInformation": {
"code": "12345678"
},
"id": "7055928871556818104953",
"orderInformation": {
"amountDetails": {
"authorizedAmount": "10.00",
"currency": "USD"
}
},
"paymentAccountInformation": {
"card": {
"type": "001"
}
},
"paymentInformation": {
"tokenizedCard": {
"type": "001"
},
"instrumentIdentifier": {
"id": "7010000000016241111",
"state": "ACTIVE"
},
"shippingAddress": {
"id": "0F35F0D99AD088B5E063A2598D0AE066"
},
"paymentInstrument": {
"id": "0F35E9CFEA463E34E063A2598D0A3FC2"
},

Token Management Service | Customer Tokens | 101

 "card": {
"type": "001"
},
"customer": {
"id": "B21E6717A6F03479E05341588E0A303F"
}
},
"pointOfSaleInformation": {
"terminalId": "111111"
},
"processorInformation": {
"approvalCode": "888888",
"networkTransactionId": "123456789619999",
"transactionId": "123456789619999",
"responseCode": "100",
"avs": {
"code": "X",
"codeRaw": "I1"
}
},
"reconciliationId": "67467352CRIISD1G",
"status": "AUTHORIZED",
"submitTimeUtc": "2024-01-18T15:48:07Z"
}

REST Example: Authorizing a Payment Using a Customer Token Linked

to a Network Token
Endpoint:

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

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

Request

{
"clientReferenceInformation": {
"code": "12345678"
},
"paymentInformation": {
"customer": {
"id": "F60328413BAB09A4E053AF598E0A33DB"
}
},

Token Management Service | Customer Tokens | 102

 "orderInformation": {
"amountDetails": {
"totalAmount": "102.21",
"currency": "USD"
}
}
}

Token Management Service | Customer Tokens | 103

Response to a Successful Request

The request response returns the payment instrument and shipping address IDs that are used as the
customer's defaults.

{
"_links": {
"authReversal": {
"method": "POST",
"href": "/pts/v2/payments/6778647071126384904953/reversals"
},
"self": {
"method": "GET",
"href": "/pts/v2/payments/6778647071126384904953"
},
"capture": {
"method": "POST",
"href": "/pts/v2/payments/6778647071126384904953/captures"
}
},
"clientReferenceInformation": {
"code": "TC50171_3"
},
"id": "6778647071126384904953",
"issuerInformation": {
"responseRaw": "0110322000000E100002000....."
},
"orderInformation": {
"amountDetails": {
"authorizedAmount": "102.21",
"currency": "USD"
}
},
"paymentAccountInformation": {
"card": {
"type": "002"
}
},
"paymentInformation": {
"tokenizedCard": {
"type": "002"
},
"instrumentIdentifier": {
"id": "7020000000010603216",
"state": "ACTIVE"
},
"shippingAddress": {
"id": "F60328413BAE09A4E053AF598E0A33DB"
},

Token Management Service | Customer Tokens | 104

 "paymentInstrument": {
"id": "F6032841BE33098EE053AF598E0AB0A5"
},
"card": {
"type": "002"
},
"customer": {
"id": "F60328413BAB09A4E053AF598E0A33DB"
}
},
"pointOfSaleInformation": {
"terminalId": "08244117"
}, "processingInformation": { "paymentSolution": "014" },
"processorInformation": {
"paymentAccountReferenceNumber": "50015OU4U5UYXLV127XTONYN49CL1",
"merchantNumber": "000844028303882",
"approvalCode": "831000",
"networkTransactionId": "0602MCC603474",
"transactionId": "0602MCC603474",
"responseCode": "00",
"avs": {
"code": "Y",
"codeRaw": "Y"
}
},
"reconciliationId": "EUHW1EMHIZ3O",
"status": "AUTHORIZED",
"submitTimeUtc": "2023-03-03T17:31:48Z"
}

Token Management Service | Customer Tokens | 105

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

Required Fields for Making a Credit with a Customer Token

clientReferenceInformation.code

orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount

paymentInformation.customer.id
Set to the ID of the customer token you want to use.

Related Information

• API field reference guide for the REST API

REST Example: Making a Credit with a Customer Token

Endpoint:

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

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

Request

{
"clientReferenceInformation": {
"code": "12345678"
},

Token Management Service | Customer Tokens | 106

 "paymentInformation": {
"customer": {
"id": "F45FB3E443AC3C57E053A2598D0A9CFF"
}
},
"orderInformation": {
"amountDetails": {
"currency": "USD",
"totalAmount": "10.00"
}
}
}

Token Management Service | Customer Tokens | 107

Response to a Successful Request

{
"_links": {
"void": {
"method": "POST",
"href": "/pts/v2/credits/7055967677826132904951/voids"
},
"self": {
"method": "GET",
"href": "/pts/v2/credits/7055967677826132904951"
}
},
"clientReferenceInformation": {
"code": "12345678"
},
"creditAmountDetails": {
"currency": "USD",
"creditAmount": "10.00"
},
"id": "7055967677826132904951",
"orderInformation": {
"amountDetails": {
"currency": "USD"
}
},
"paymentAccountInformation": {
"card": {
"type": "001"
}
},
"paymentInformation": {
"tokenizedCard": {
"type": "001"
},
"instrumentIdentifier": {
"id": "7030000000014831523",
"state": "ACTIVE"
},
"shippingAddress": {
"id": "F45FD8DE51B99E9CE053A2598D0AFDFA"
},
"paymentInstrument": {
"id": "F45FE45E7993C7DBE053A2598D0AED19"
},
"card": {
"type": "001"
},
"customer": {

Token Management Service | Customer Tokens | 108

 "id": "F45FB3E443AC3C57E053A2598D0A9CFF"
}
},
"processorInformation": {
"paymentAccountReferenceNumber": "V0010013019326121538313096266",
"approvalCode": "888888",
"responseCode": "100"
},
"reconciliationId": "67444961BRIL0BB8",
"status": "PENDING",
"submitTimeUtc": "2024-01-18T16:52:48Z"
}

Token Management Service | Customer Tokens | 109

Shipping Address Tokens
The shipping address token contains the shipping address information associated with a customer
token. This token includes any shipping address details, including the recipient's first and last name,
company, shipping address, email, and phone number. A customer can have one or more shipping
addresses, with one allocated as the customer's default shipping address.

Related information
Manage Shipping Address Tokens (on page 110)
Payments with Shipping Address Tokens (on page 132)

Manage Shipping Address Tokens

This section contains information managing shipping address tokens.

A shipping address token is associated with a customer token. You can create, retrieve, update, or
delete an instrument identifier by submitting an HTTP POST, GET, PATCH, or DELETE operation to the /
tms/v2/customers/{customerTokenId}/shipping-addresses endpoint. Use the TMS REST API shipping
address endpoint to:

• Create a shipping address token (on page 110)

• Retrieve a shipping address token (on page 122) or multiple shipping address tokens for a
specific customer (on page 125)

• Update a shipping address (on page 128)

• Delete a shipping address (on page 131)

For more information on shipping address tokens, see Shipping Address Tokens (on page 21).

Create a Customer Shipping Address

This section shows you how to create a customer shipping address.

Endpoint

Test: POST https://apitest.cybersource.com/tms/v2/customers/{customerTokenId}/shipping-

addresses

Token Management Service | Shipping Address Tokens | 110

Production: POST https://api.cybersource.com/tms/v2/customers/{customerTokenId}/shipping-
addresses

Production in India: POST https://api.in.cybersource.com/tms/

v2/customers/{customerTokenId}/shipping-addresses

The {customerTokenId} is the customer token ID returned in the id field when you created the
customer token. For more information, see Create a Customer (on page 76).

Required Fields for Creating a Customer Shipping Address

You can include any of the following fields in the body of the request:
shipTo.address1

shipTo.address2

shipTo.administrativeArea

shipTo.company

shipTo.country

shipTo.email

shipTo.firstName

shipTo.lastName

shipTo.locality

shipTo.phoneNumber

shipTo.postalCode

Related Information

• API Field Reference for the REST API

Token Management Service | Shipping Address Tokens | 111

REST Example: Creating a Customer Shipping Address

Request

Pass the customer token ID in the URL path. If the default field is not supplied and the customer does
not already have a shipping address, then the shipping address will become the default. Otherwise, it
will become a customer's non-default shipping address.

POST https://
apitest.cybersource.com/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/shipping-addres
ses

Token Management Service | Shipping Address Tokens | 112

Response to a Successful Request

{
"_links": {
"self": {

"href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/shipping-addresses/F2F4C2D1B
966D631E053A2598D0AB155"
},
"customer": {
"href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078"
}
},
"id": "F2F4C2D1B966D631E053A2598D0AB155",
"default": true,
"shipTo": {
"firstName": "John",
"lastName": "Doe",
"company": "Company Name",
"address1": "1 Market St",
"locality": "San Francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"metadata": {
"creator": "testrest"
}
}

REST Interactive Example: Creating a Customer Shipping Address

Live Console URL: https://developer.cybersource.com/api-reference-assets/index.html#token-
management_customer-shipping-address_create-a-customer-shipping-address

Token Management Service | Shipping Address Tokens | 113

Add a Default Shipping Address
This section shows you how to add a default customer shipping address.

Endpoint

Test: POST https://apitest.cybersource.com/tms/v2/customers/{customerTokenId}/shipping-

addresses

Production: POST https://api.cybersource.com/tms/v2/customers/{customerTokenId}/shipping-

addresses

Production in India: POST https://api.in.cybersource.com/tms/

v2/customers/{customerTokenId}/shipping-addresses

The {customerTokenId} is the customer token ID returned in the id field when you created the
customer token. For more information, see Create a Customer (on page 76).

Required Fields for Adding a Default Shipping Address Using the REST
API
You can include any of the following fields in the body of the request:
customerTokenId
Include the ID of the customer token you want to retrieve in the URL path.
default
Set to true.
shipTo.address1

shipTo.address2

shipTo.administrativeArea

shipTo.company

shipTo.country

shipTo.email

shipTo.firstName

shipTo.lastName

shipTo.locality

Token Management Service | Shipping Address Tokens | 114

 shipTo.phoneNumber

shipTo.postalCode

Related Information

• API Field Reference for the REST API

REST Example: Adding a Default Shipping Address

Request

Pass the customer token ID in the URL path.

POST /tms/v2/customers/F45FB3E443AC3C57E053A2598D0A9CFF/shipping-addresses

{
"default": true,
"shipTo": {
"firstName": "John",
"lastName": "Doe",
"company": "Visa",
"address1": "1 Market St",
"locality": "san francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"phoneNumber": "4158880000",
"email": "[email protected]"
}
}

Token Management Service | Shipping Address Tokens | 115

Response to a Successful Request

{
"_links": {
"self": {

"href": "/tms/v2/customers/F45FB3E443AC3C57E053A2598D0A9CFF/shipping-addresses/F45FD8DE5
1A89E9CE053A2598D0AFDFA"
},
"customer": {
"href": "/tms/v2/customers/F45FB3E443AC3C57E053A2598D0A9CFF"
}
},
"id": "F45FD8DE51A89E9CE053A2598D0AFDFA",
"default": true,
"shipTo": {
"firstName": "John",
"lastName": "Doe",
"company": "Visa",
"address1": "1 Market St",
"locality": "san francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"metadata": {
"creator": "testrest"
}
}

Token Management Service | Shipping Address Tokens | 116

Add a Non-Default Shipping Address
This section shows you how to add a non-default customer shipping address.

Endpoint

Test: POST https://apitest.cybersource.com/tms/v2/customers/{customerTokenId}/shipping-

addresses

Production: POST https://api.cybersource.com/tms/v2/customers/{customerTokenId}/shipping-

addresses

Production in India: POST https://api.in.cybersource.com/tms/

v2/customers/{customerTokenId}/shipping-addresses

The {customerTokenId} is the customer token ID returned in the id field when you created the
customer token. For more information, see Create a Customer Shipping Address (on page 110).

Required Fields for Adding a Non-Default Shipping Address Using the

REST API
You can include any of the following fields in the body of the request:
default
Set to false.
shipTo.address1

shipTo.address2

shipTo.administrativeArea

shipTo.company

shipTo.country

shipTo.email

shipTo.firstName

shipTo.lastName

shipTo.locality

shipTo.phoneNumber

shipTo.postalCode

Token Management Service | Shipping Address Tokens | 117

Related Information

• API Field Reference for the REST API

REST Example: Adding a Non-Default Shipping Address

Request

Pass the customer token ID in the URL path.

POST https://
apitest.cybersource.com/tms/v2/customers/F45FB3E443AC3C57E053A2598D0A9CFF/shipping-addres
ses

{
"default": false,
"shipTo": {
"firstName": "John",
"lastName": "Doe",
"company": "Visa",
"address1": "1 Market St",
"locality": "san francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"phoneNumber": "4158880000",
"email": "[email protected]"
}
}

Token Management Service | Shipping Address Tokens | 118

Response to a Successful Request

{
"_links": {
"self": {

"href": "/tms/v2/customers/F45FB3E443AC3C57E053A2598D0A9CFF/shipping-addresses/F45FD8DE5
1B99E9CE053A2598D0AFDFA"
},
"customer": {
"href": "/tms/v2/customers/F45FB3E443AC3C57E053A2598D0A9CFF"
}
},
"id": "F45FD8DE51B99E9CE053A2598D0AFDFA",
"default": false,
"shipTo": {
"firstName": "John",
"lastName": "Doe",
"company": "Visa",
"address1": "1 Market St",
"locality": "san francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"metadata": {
"creator": "testrest"
}
}

Token Management Service | Shipping Address Tokens | 119

Change a Default Shipping Address
This section shows you how to change a default customer shipping address.

Endpoint

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

addresses/{shippingAddressTokenId}

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

addresses/{shippingAddressTokenId}

Production in India: PATCH https://api.in.cybersource.com/tms/

v2/customers/{customerTokenId}/shipping-addresses/{shippingAddressTokenId}

The {customerTokenId} is the customer token ID returned in the id field when you created the
customer token. In the customerTokenId path parameter, pass the shipping address token ID response
field returned when you created a shipping address token. For more information, see Create a
Customer (on page 76) and Create a Customer Shipping Address (on page 110).

Required Fields for Changing a Default Shipping Address Using the

REST API
You must include the following field in the body of the request:
default
Set to true.
customerTokenId
Include the ID of the customer token you want to retrieve in the URL path.
shippingAddressTokenId
Include the ID of the shipping address token you want to retrieve in the URL path.

Related Information

• API Field Reference for the REST API

Token Management Service | Shipping Address Tokens | 120

REST Example: Changing Default Shipping Address

Request
Pass the customer token ID and shipping address token ID in the URL path.

PATCH https://
apitest.cybersource.com/tms/v2/customers/F45FB3E443AC3C57E053A2598D0A9CFF/shipping-address
es/F45FD8DE51B99E9CE053A2598D0AFDFA

{
"default": true
}

Token Management Service | Shipping Address Tokens | 121

Response to a Successful Request

{
"_links": {
"self": {

"href": "/tms/v2/customers/F45FB3E443AC3C57E053A2598D0A9CFF/shipping-addresses/F45FD8DE5
1B99E9CE053A2598D0AFDFA"
},
"customer": {
"href": "/tms/v2/customers/F45FB3E443AC3C57E053A2598D0A9CFF"
}
},
"id": "F45FD8DE51B99E9CE053A2598D0AFDFA",
"default": true,
"shipTo": {
"firstName": "John",
"lastName": "Doe",
"company": "Visa",
"address1": "1 Market St",
"locality": "san francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"metadata": {
"creator": "testrest"
}
}

Retrieve a Customer Shipping Address

This section shows you how to retrieve a customer shipping address.

Endpoint

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

addresses/{shippingAddressTokenId}

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

addresses/{shippingAddressTokenId}

Token Management Service | Shipping Address Tokens | 122

Production in India: GET https://api.in.cybersource.com/tms/
v2/customers/{customerTokenId}/shipping-addresses/{shippingAddressTokenId}

The {customerTokenId} is the customer token ID returned in the id field when you created the
customer token. In the shippingAddressTokenId path parameter, pass the shipping address token
ID response field returned when you created a shipping address token. For more information, see
Create a Customer (on page 76) and Create a Customer Shipping Address (on page 110).

Token Management Service | Shipping Address Tokens | 123

REST Example: Retrieving a Shipping Address

Request

Pass the customer token ID and shipping address token ID in the URL path.

GET https://
apitest.cybersource.com/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/shipping-address
es/F2F4C2D1B966D631E053A2598D0AB155

Token Management Service | Shipping Address Tokens | 124

Response to a Successful Request

{
"shipTo": {
"firstName": "Jane",
"lastName": "Smith",
"company": "Lear Group, LLC",
"address1": "123 Mountain Peaks Rd",
"address2": "",
"locality": "Mountain Peaks",
"administrativeArea": "CA",
"postalCode": "90212",
"country": "US",
"email": "[email protected]",
"phoneNumber": "123-456-7890"
}
}

Retrieve All Customer Shipping Addresses

This section shows you how to retrieve all customer shipping addresses.

Endpoint

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

addresses

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

addresses

Production in India: GET https://api.in.cybersource.com/tms/

v2/customers/{customerTokenId}/shipping-addresses

The {customerTokenId} is the customer token ID returned in the id field when you created the
customer token. For more information, see Create a Customer (on page 76).

Token Management Service | Shipping Address Tokens | 125

REST Example: Retrieving All Customer Shipping Addresses

Request

Pass the customer token ID in the URL path. 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.

GET https://
apitest.cybersource.com/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/shipping-address
es?offset=0&limit=20

Token Management Service | Shipping Address Tokens | 126

Response to a Successful Request

The shipping address in the first array element is the default shipping address.

{
"_links": {
"self": {

"href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/shipping-addresses?offset=0&
limit=20"
},
"first": {

"href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/shipping-addresses?offset=0&
limit=20"
},
"last": {

"href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/shipping-addresses?offset=0&
limit=20"
}
},
"offset": 0,
"limit": 20,
"count": 1,
"total": 1,
"_embedded": {
"shippingAddresses": [
{
"_links": {
"self": {

"href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/shipping-addresses/F2F4C2D1B
966D631E053A2598D0AB155"
},
"customer": {
"href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078"
}
},
"id": "F2F4C2D1B966D631E053A2598D0AB155",
"default": true,
"shipTo": {
"firstName": "John",
"lastName": "Doe",
"company": "Company Name",
"address1": "1 Market St",
"locality": "San Francisco",
"administrativeArea": "CA",
"postalCode": "94105",

Token Management Service | Shipping Address Tokens | 127

 "country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"metadata": {
"creator": "testrest"
}
}
]
}
}

Update a Customer Shipping Address

This section shows you how to update a customer shipping address.

Endpoint

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

addresses/{shippingAddressTokenId}

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

addresses/{shippingAddressTokenId}

Production in India: PATCH https://api.in.cybersource.com/tms/

v2/customers/{customerTokenId}/shipping-addresses/{shippingAddressTokenId}

The {customerTokenId} is the customer token ID returned in the id field when you created the
customer token. In the customerTokenId path parameter, pass the shipping address token ID response
field returned when you created a shipping address token. For more information, see Create a
Customer (on page 76) and Create a Customer Shipping Address (on page 110).

Required Fields for Updating a Customer Shipping Address

customerTokenId
Include the ID of the customer token you want to retrieve in the URL path.
shippingAddressTokenId
Include the ID of the shipping address token you want to retrieve in the URL path.
shipTo.address1

shipTo.address2

Token Management Service | Shipping Address Tokens | 128

 shipTo.administrativeArea

shipTo.company

shipTo.country

shipTo.email

shipTo.firstName

shipTo.lastName

shipTo.locality

shipTo.phoneNumber

shipTo.postalCode

Related Information

• API Field Reference for the REST API

Token Management Service | Shipping Address Tokens | 129

REST Example: Updating a Customer Shipping Address

Request

Pass the customer token ID and shipping address token ID in the URL path.

PATCH https://
apitest.cybersource.com/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/shipping-address
es/F2F4C2D1B966D631E053A2598D0AB155

{
"shipTo": {
"firstName": "Jane",
"lastName": "Smith",
"company": "Lear Group, LLC",
"address1": "123 Mountain Peaks Rd",
"address2": "Unit B",
"locality": "Mountain Peaks",
"administrativeArea": "CA",
"postalCode": "90212",
"country": "US",
"email": "[email protected]",
"phoneNumber": "123-456-7890"
}
}

Response to a Successful Request

{
"shipTo": {
"firstName": "Jane",
"lastName": "Smith",
"company": "Lear Group, LLC",
"address1": "123 Mountain Peaks Rd",
"address2": "Unit B",
"locality": "Mountain Peaks",
"administrativeArea": "CA",
"postalCode": "90212",
"country": "US",
"email": "[email protected]",
"phoneNumber": "123-456-7890"
}
}

Token Management Service | Shipping Address Tokens | 130

REST Interactive Example: Updating a Customer Shipping Address
Live Console URL: https://developer.cybersource.com/api-reference-assets/index.html#token-
management_customer-shipping-address_update-a-customer-shipping-address

Delete a Customer Shipping Address

This section shows you how to delete a customer shipping address.

Endpoint

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

addresses/{shippingAddressTokenId}

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

addresses/{shippingAddressTokenId}

Production in India: DELETE https://api.in.cybersource.com/tms/

v2/customers/{customerTokenId}/shipping-addresses/{shippingAddressTokenId}

The {customerTokenId} is the customer token ID returned in the id field when you created the
customer token. In the customerTokenId path parameter, pass the shipping address token ID response
field returned when you created a shipping address token. For more information, see Create a
Customer (on page 76) and Create a Customer Shipping Address (on page 110).

Important: If you have more than one shipping address, the default shipping address cannot
be deleted without first selecting a new default shipping address.

Required Fields for Deleting a Customer Shipping Address

customerTokenId
Include the ID of the customer token you want to retrieve in the URL path.
shippingAddressTokenId
Include the ID of the shipping address token you want to retrieve in the URL path.

Related Information

• API Field Reference for the REST API

Token Management Service | Shipping Address Tokens | 131

REST Example: Deleting a Customer Shipping Address

Request

Pass the customer token ID and shipping address token ID in the URL path.

DELETE https://
apitest.cybersource.com/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/shipping-address
es/F2F4C2D1B966D631E053A2598D0AB155

Response to a Successful Request

A successful delete response returns an empty HTTP 204 No Content status. For more information, see
HTTP Status Codes (on page 321).

Payments with Shipping Address Tokens

This section contains information on making payments with shipping address tokens.

A shipping address token is associated with a specific customer token. This includes any shipping
address details, including first and last name, company, shipping address, email, and phone number.

To make a payment using a shipping address token, you must either create the token
in the authorization request or include the customer token ID as the value in the
paymentInformation.customer.id and paymentInformation.shippingAddress.id fields. You can make
payments using non-default shipping address tokens. For example:

• Authorizing a Payment with a Non-Default Shipping Address (on page 133)

For more information on shipping address tokens, see Shipping Address Tokens (on page 21).

Token Management Service | Shipping Address Tokens | 132

Authorizing a Payment with a Non-Default Shipping Address
This section provides the information you need in order to make a payment with a non-default
shipping address.

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

Required Fields for Authorizing a Payment with a Non-Default

Shipping Address
clientReferenceInformation.code

orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount

paymentInformation.customer.id
Set to the ID of the customer token you want to use.
paymentInformation.shippingAddress.id
Set to the ID of the shipping address token you want to use.

Related Information

• API field reference guide for the REST API

REST Example: Authorizing a Payment with a Non-Default Shipping

Address
Endpoint:

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

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

Token Management Service | Shipping Address Tokens | 133

Request

{
"clientReferenceInformation": {
"code": "12345678"
},
"paymentInformation": {
"customer": {
"id": "F45FB3E443AC3C57E053A2598D0A9CFF"
},
"shippingAddress": {
"id": "F45FD8DE51B99E9CE053A2598D0AFDFA"
}
},
"orderInformation": {
"amountDetails": {
"currency": "USD",
"totalAmount": "10.00"
}
}
}

Token Management Service | Shipping Address Tokens | 134

Response to a Successful Request

{
"_links": {
"authReversal": {
"method": "POST",
"href": "/pts/v2/payments/7055949037316786904953/reversals"
},
"self": {
"method": "GET",
"href": "/pts/v2/payments/7055949037316786904953"
},
"capture": {
"method": "POST",
"href": "/pts/v2/payments/7055949037316786904953/captures"
}
},
"clientReferenceInformation": {
"code": "12345678"
},
"id": "7055949037316786904953",
"orderInformation": {
"amountDetails": {
"authorizedAmount": "10.00",
"currency": "USD"
}
},
"paymentAccountInformation": {
"card": {
"type": "001"
}
},
"paymentInformation": {
"tokenizedCard": {
"type": "001"
},
"instrumentIdentifier": {
"id": "7030000000014831523",
"state": "ACTIVE"
},
"shippingAddress": {
"id": "F45FD8DE51B99E9CE053A2598D0AFDFA"
},
"paymentInstrument": {
"id": "F45FE45E7993C7DBE053A2598D0AED19"
},
"card": {
"type": "001"
},

Token Management Service | Shipping Address Tokens | 135

 "customer": {
"id": "F45FB3E443AC3C57E053A2598D0A9CFF"
}
},
"pointOfSaleInformation": {
"terminalId": "111111"
},
"processorInformation": {
"approvalCode": "888888",
"networkTransactionId": "123456789619999",
"transactionId": "123456789619999",
"responseCode": "100",
"avs": {
"code": "X",
"codeRaw": "I1"
}
},
"reconciliationId": "674679208RIKQ52K",
"status": "AUTHORIZED",
"submitTimeUtc": "2024-01-18T16:21:44Z"
}

Token Management Service | Shipping Address Tokens | 136

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 (on page 137)

• Retrieve a customer payment instrument token (on page 166)

• Update a customer payment instrument (on page 178)

• Delete a customer payment instrument (on page 183)

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

Create a Customer Payment Instrument

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

Token Management Service | Customer Payment Instrument Tokens | 137

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 id field when you created the
customer token. For more information, see Create a Customer (on page 76).

Required Fields for Creating a Customer Payment Instrument Using

the REST API
card.type
Required if the instrument identifier ID being linked to is card-based.
customerTokenId
Include the ID of the customer token you want to retrieve in the URL path.

Related Information

• API Field Reference for the REST API

Optional Fields for Creating a Customer Payment Instrument Using

the REST API
bankAccount.type

billTo.address1

billTo.address2

billTo.aminstrativeArea

billTo.company

billTo.country

billTo.email

Token Management Service | Customer Payment Instrument Tokens | 138

 billTo.firstName

billTo.lastName

billTo.locality

billTo.phoneNumber

billTo.postalCode

buyerInformation.companyTaxID

buyerInformation.currency

buyerInformation.dateOfBirth

buyerInformation.personalIdentification.id

buyerInformation.personalIdentification.issuedBy.administrativeArea

buyerInformation.personalIdentification.type

card.expirationMonth

card.expirationYear

card.issueNumber

card.startMonth

card.startYear

card.useAs

card.tokenizedInformation.requestorID

card.tokenizedInformation.transactionType

default
If you do not include this field, the first payment instrument for a customer becomes
the default. A subsequent payment instrument becomes the non-default option.
instrumentIdentifier.id

processingInformation.billPaymentProgramEnabled

merchantInformation.merchantDescriptor.alternateName

Related Information

• API Field Reference for the REST API

Token Management Service | Customer Payment Instrument Tokens | 139

REST Example: Creating a Customer Payment Instrument

Request

POST https://
apitest.cybersource.com/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/payment-instrume
nts

{
"card": {
"expirationMonth": "12",
"expirationYear": "2031",
"type": "001"
},
"billTo": {
"firstName": "John",
"lastName": "Doe",
"company": "Company Name",
"address1": "1 Market St",
"locality": "San Francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"instrumentIdentifier": {
"id": "7010000000016241111"
}
}

Token Management Service | Customer Payment Instrument Tokens | 140

Response to a Successful Request

{
"_links": {
"self": {

"href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/payment-instruments/F39732BE
4BDA9A1EE053AF598E0A4081"
},
"customer": {
"href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078"
}
},
"id": "F39732BE4BDA9A1EE053AF598E0A4081",
"default": true,
"state": "ACTIVE",
"card": {
"expirationMonth": "12",
"expirationYear": "2031",
"type": "001"
},
"billTo": {
"firstName": "John",
"lastName": "Doe",
"company": "Company Name",
"address1": "1 Market St",
"locality": "San Francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"instrumentIdentifier": {
"id": "7010000000016241111"
},
"metadata": {
"creator": "testrest"
},
"_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {
"href": "/tms/v1/instrumentidentifiers/7010000000016241111"
},
"paymentInstruments": {
"href": "/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstruments"
}
},

Token Management Service | Customer Payment Instrument Tokens | 141

 "id": "7010000000016241111",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXXXX1111"
},
"processingInformation": {
"authorizationOptions": {
"initiator": {
"merchantInitiatedTransaction": {
"previousTransactionId": "123456789012345"
}
}
}
},
"metadata": {
"creator": "testrest"
}
}
}
}
}

REST Interactive Example: Creating a Customer Payment Instrument

Live Console URL: https://developer.cybersource.com/api-reference-assets/index.html#token-
management_customer-payment-instrument_create-a-customer-payment-instrument

Token Management Service | Customer Payment Instrument Tokens | 142

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 id field when you created the
customer token. For more information, see Create a Customer (on page 76).

Required Fields for Adding a Default Payment Instrument Using

Instrument Identifier Using the REST API
customerTokenId
Include the ID of the customer token you want to retrieve in the URL path.
default
Set value to true.
instrumentIdentifier.id
Include the ID of the instrument identifier you want to use.

Related Information

• API Field Reference for the REST API

Optional Fields for Adding a Default Payment Instrument Using

Instrument Identifier Using the REST API
bankAccount.type

billTo.address1

billTo.address2

Token Management Service | Customer Payment Instrument Tokens | 143

billTo.aminstrativeArea

billTo.company

billTo.country

billTo.email

billTo.firstName

billTo.lastName

billTo.locality

billTo.phoneNumber

billTo.postalCode

buyerInformation.companyTaxID

buyerInformation.currency

buyerInformation.dateOfBirth

buyerInformation.personalIdentification.id

buyerInformation.personalIdentification.issuedBy.administrativeArea

buyerInformation.personalIdentification.type

card.expirationMonth

card.expirationYear

card.issueNumber

card.startMonth

card.startYear

card.type

card.useAs

card.tokenizedInformation.requestorID

card.tokenizedInformation.transactionType

instrumentIdentifier.id

processingInformation.billPaymentProgramEnabled

merchantInformation.merchantDescriptor.alternateName

Token Management Service | Customer Payment Instrument Tokens | 144

Related Information

• API Field Reference for the REST API

REST Example: Adding a Default Payment Instrument Using

Instrument Identifier

Request

POST https://
apitest.cybersource.com/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/payment-instrume
nts

{
"default": true,
"card": {
"expirationMonth": "12",
"expirationYear": "2031",
"type": "001"
},
"billTo": {
"firstName": "John",
"lastName": "Doe",
"company": "Visa",
"address1": "1 Market St",
"locality": "san francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"phoneNumber": "4158880000",
"email": "[email protected]"
},
"instrumentIdentifier": {
"id": "7010000000016241111"
}
}

Token Management Service | Customer Payment Instrument Tokens | 145

Response to a Successful Request

{
"_links": {
"self": {

"href": "/tms/v2/customers/F45FB3E443AC3C57E053A2598D0A9CFF/payment-instruments/F45FD8DE
542A9E9CE053A2598D0AFDFA"
},
"customer": {
"href": "/tms/v2/customers/F45FB3E443AC3C57E053A2598D0A9CFF"
}
},
"id": "F45FD8DE542A9E9CE053A2598D0AFDFA",
"default": true,
"state": "ACTIVE",
"card": {
"expirationMonth": "12",
"expirationYear": "2031",
"type": "001"
},
"billTo": {
"firstName": "John",
"lastName": "Doe",
"company": "Visa",
"address1": "1 Market St",
"locality": "san francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"instrumentIdentifier": {
"id": "7030000000014911515"
},
"metadata": {
"creator": "testrest"
},
"_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {
"href": "/tms/v1/instrumentidentifiers/7030000000014911515"
},
"paymentInstruments": {

"href": "/tms/v1/instrumentidentifiers/7030000000014911515/paymentinstruments"
}

Token Management Service | Customer Payment Instrument Tokens | 146

 },
"id": "7030000000014911515",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "489537XXXXXX1515"
},
"issuer": {
"paymentAccountReference": "V0010013019326121174070050420"
},
"processingInformation": {
"authorizationOptions": {
"initiator": {
"merchantInitiatedTransaction": {
"previousTransactionId": "123456789619999"
}
}
}
},
"metadata": {
"creator": "testrest"
}
}
}
}

Token Management Service | Customer Payment Instrument Tokens | 147

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

The {customerTokenId} is the customer token ID returned in the id field when you created the
customer token. For more information, see Create a Customer (on page 76).

Required Fields for Adding a Default Payment Instrument with

Validated Payment Using the REST API
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount

orderInformation.billTo.address1

orderInformation.billTo.administrativeArea

orderInformation.billTo.country

orderInformation.billTo.email

orderInformation.billTo.firstName

orderInformation.billTo.lastName

orderInformation.billTo.locality

orderInformation.billTo.postalCode

paymentInformation.card.expirationMonth

paymentInformation.card.expirationYear

paymentInformation.card.number

paymentInformation.card.type

paymentInformation.customer.id
Set the value to the ID of the customer token.

Token Management Service | Customer Payment Instrument Tokens | 148

 processingInformation.actionList
Set the value to TOKEN_CREATE.
processingInformation.actionTokenTypes
Set the value to paymentInstrument.
tokenInformation.paymentInstrument.default
Set value to true.

Related Information

• API Field Reference for the REST API

REST Example: Adding a Default Payment Instrument with Validated

Payment

Request

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

{
"clientReferenceInformation": {
"code": "TC50171_3"
},
"processingInformation": {
"commerceIndicator": "internet",
"actionList": [
"TOKEN_CREATE"
],
"actionTokenTypes": [
"paymentInstrument"
]
},
"orderInformation": {
"billTo": {
"country": "US",
"lastName": "Deo",
"address2": "Address 2",
"address1": "201 S. Division St.",
"postalCode": "48104-2201",
"locality": "Ann Arbor",
"administrativeArea": "MI",
"firstName": "John",
"phoneNumber": "999999999",

Token Management Service | Customer Payment Instrument Tokens | 149

 "district": "MI",
"buildingNumber": "123",
"company": "Visa",
"email": "[email protected]"
},
"shipTo": {
"country": "US",
"lastName": "Deo",
"address2": "Address 2",
"address1": "201 S. Division St.",
"postalCode": "48104-2201",
"locality": "Ann Arbor",
"administrativeArea": "MI",
"firstName": "John",
"phoneNumber": "999999999",
"district": "MI",
"buildingNumber": "123",
"company": "Visa",
"email": "[email protected]"
},
"amountDetails": {
"totalAmount": "102.00",
"currency": "USD"
}
},
"paymentInformation": {
"customer": {
"id": "{{tms-customer-id}}"
},
"card": {
"expirationYear": "2031",
"number": "4895379987X11523",
"securityCode": "965",
"expirationMonth": "12",
"type": "001"
}
},
"tokenInformation": {
"paymentInstrument": {
"default": "true"
}
}
}

Token Management Service | Customer Payment Instrument Tokens | 150

Response to a Successful Request

{
"_links": {
"authReversal": {
"method": "POST",
"href": "/pts/v2/payments/6760637747316173203955/reversals"
},
"self": {
"method": "GET",
"href": "/pts/v2/payments/6760637747316173203955"
},
"capture": {
"method": "POST",
"href": "/pts/v2/payments/6760637747316173203955/captures"
}
},
"clientReferenceInformation": {
"code": "TC50171_3"
},
"id": "6760637747316173203955",
"orderInformation": {
"amountDetails": {
"authorizedAmount": "102.00",
"currency": "USD"
}
},
"paymentAccountInformation": {
"card": {
"type": "001"
}
},
"paymentInformation": {
"tokenizedCard": {
"type": "001"
},
"shippingAddress": {
"id": "F45FD8DE51B99E9CE053A2598D0AFDFA"
},
"card": {
"type": "001"
},
"customer": {
"id": "F45FB3E443AC3C57E053A2598D0A9CFF"
}
},
"pointOfSaleInformation": {
"terminalId": "111111"
},

Token Management Service | Customer Payment Instrument Tokens | 151

 "processorInformation": {
"paymentAccountReferenceNumber": "V0010013019326121538313096266",
"approvalCode": "888888",
"networkTransactionId": "123456789619999",
"transactionId": "123456789619999",
"responseCode": "100",
"avs": {
"code": "X",
"codeRaw": "I1"
}
},
"reconciliationId": "69815876LDTHD4XU",
"status": "AUTHORIZED",
"submitTimeUtc": "2023-02-10T21:16:15Z",
"tokenInformation": {
"instrumentidentifierNew": false,
"instrumentIdentifier": {
"state": "ACTIVE",
"id": "7030000000014831523"
},
"paymentInstrument": {
"id": "F45FE45E7993C7DBE053A2598D0AED19"
}
}
}

Token Management Service | Customer Payment Instrument Tokens | 152

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 id 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 (on page 76) and Create a Customer Payment
Instrument (on page 137).

Required Fields for Adding a Non-Default Payment Instrument Using

Instrument Identifier Using the REST API
customerTokenId
Include the ID of the customer token you want to retrieve in the URL path.
paymentInstrumentTokenId
Include the ID of the payment instrument token you want to retrieve in the URL path.

Related Information

• API Field Reference for the REST API

Optional Fields for Adding a Non-Default Payment Instrument Using

Instrument Identifier Using the REST API
bankAccount.type

billTo.address1

Token Management Service | Customer Payment Instrument Tokens | 153

billTo.address2

billTo.aminstrativeArea

billTo.company

billTo.country

billTo.email

billTo.firstName

billTo.lastName

billTo.locality

billTo.phoneNumber

billTo.postalCode

buyerInformation.companyTaxID

buyerInformation.currency

buyerInformation.dateOfBirth

buyerInformation.personalIdentification.id

buyerInformation.personalIdentification.issuedBy.administrativeArea

buyerInformation.personalIdentification.type

card.expirationMonth

card.expirationYear

card.issueNumber

card.startMonth

card.startYear

card.type

card.useAs

card.tokenizedInformation.requestorID

card.tokenizedInformation.transactionType

default
Set value to true if default, otherwise set value to false.
instrumentIdentifier.id

Token Management Service | Customer Payment Instrument Tokens | 154

 Set the value to the ID of the instrument identifier token.
processingInformation.billPaymentProgramEnabled

merchantInformation.merchantDescriptor.alternateName

Related Information

• API Field Reference for the REST API

REST Example: Adding a Non-Default Payment Instrument Using

Instrument Identifier

Request

Pass the customer token ID and payment instrument token ID in the URL path.

POST https://
apitest.cybersource.com/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/payment-instrume
nts/F39732BE4BDA9A1EE053AF598E0A4081

{
"default": false,
"card": {
"expirationMonth": "12",
"expirationYear": "2031",
"type": "001"
},
"billTo": {
"firstName": "John",
"lastName": "Doe",
"company": "Visa",
"address1": "1 Market St",
"locality": "san francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"phoneNumber": "4158880000",
"email": "[email protected]"
},
"instrumentIdentifier": {
"id": "{{tms-instrumentIdentifier-id}}"
}
}

Token Management Service | Customer Payment Instrument Tokens | 155

Response to a Successful Request

{
"_links": {
"self": {

"href": "/tms/v2/customers/F45FB3E443AC3C57E053A2598D0A9CFF/payment-instruments/F45FE3A5
DAD6CF8CE053A2598D0AA1EF"
},
"customer": {
"href": "/tms/v2/customers/F45FB3E443AC3C57E053A2598D0A9CFF"
}
},
"id": "F45FE3A5DAD6CF8CE053A2598D0AA1EF",
"default": false,
"state": "ACTIVE",
"card": {
"expirationMonth": "12",
"expirationYear": "2031",
"type": "001"
},
"billTo": {
"firstName": "John",
"lastName": "Doe",
"company": "Visa",
"address1": "1 Market St",
"locality": "san francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"instrumentIdentifier": {
"id": "7030000000012931531"
},
"metadata": {
"creator": "testrest"
},
"_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {
"href": "/tms/v1/instrumentidentifiers/7030000000012931531"
},
"paymentInstruments": {

"href": "/tms/v1/instrumentidentifiers/7030000000012931531/paymentinstruments"
}

Token Management Service | Customer Payment Instrument Tokens | 156

 },
"id": "7030000000012931531",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "489537XXXXXX1531"
},
"issuer": {
"paymentAccountReference": "V0010013019326121921451482293"
},
"processingInformation": {
"authorizationOptions": {
"initiator": {
"merchantInitiatedTransaction": {
"previousTransactionId": "123456789619999"
}
}
}
},
"metadata": {
"creator": "testrest"
}
}
}
}

Token Management Service | Customer Payment Instrument Tokens | 157

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 id field when you created the
customer token. For more information, see Create a Customer (on page 76).

Required Fields for Adding a Non-Default Payment Instrument with

Validated Payment Using the REST API
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount

orderInformation.billTo.address1

orderInformation.billTo.administrativeArea

orderInformation.billTo.country

orderInformation.billTo.email

orderInformation.billTo.firstName

orderInformation.billTo.lastName

orderInformation.billTo.locality

orderInformation.billTo.postalCode

paymentInformation.card.expirationMonth

paymentInformation.card.expirationYear

paymentInformation.card.number

paymentInformation.card.type

Token Management Service | Customer Payment Instrument Tokens | 158

 paymentInformation.customer.id
Set the value to the ID of the customer token.
processingInformation.actionList
Set the value to TOKEN_CREATE.
processingInformation.actionTokenTypes
Set the value to paymentInstrument.
tokenInformation.paymentInstrument.default
Set value to false.

Related Information

• API Field Reference for the REST API

REST Example: Adding a Non-Default Payment Instrument with

Validated Payment

Request

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

{
"clientReferenceInformation": {
"code": "TC50171_3"
},
"processingInformation": {
"commerceIndicator": "internet",
"actionList": [
"TOKEN_CREATE"
],
"actionTokenTypes": [
"paymentInstrument"
]
},
"orderInformation": {
"billTo": {
"country": "US",
"lastName": "Deo",
"address2": "Address 2",
"address1": "201 S. Division St.",
"postalCode": "48104-2201",
"locality": "Ann Arbor",

Token Management Service | Customer Payment Instrument Tokens | 159

 "administrativeArea": "MI",
"firstName": "John",
"phoneNumber": "999999999",
"district": "MI",
"buildingNumber": "123",
"company": "Visa",
"email": "[email protected]"
},
"shipTo": {
"country": "US",
"lastName": "Deo",
"address2": "Address 2",
"address1": "201 S. Division St.",
"postalCode": "48104-2201",
"locality": "Ann Arbor",
"administrativeArea": "MI",
"firstName": "John",
"phoneNumber": "999999999",
"district": "MI",
"buildingNumber": "123",
"company": "Visa",
"email": "[email protected]"
},
"amountDetails": {
"totalAmount": "102.00",
"currency": "USD"
}
},
"paymentInformation": {
"customer": {
"id": "{{tms-customer-id}}"
},
"card": {
"expirationYear": "2031",
"number": "4895379987X11531",
"securityCode": "258",
"expirationMonth": "12",
"type": "001"
}
},
"tokenInformation": {
"paymentInstrument": {
"default": "false"
}
}
}

Token Management Service | Customer Payment Instrument Tokens | 160

Response to a Successful Request

{
"_links": {
"authReversal": {
"method": "POST",
"href": "/pts/v2/payments/6760638084316175703955/reversals"
},
"self": {
"method": "GET",
"href": "/pts/v2/payments/6760638084316175703955"
},
"capture": {
"method": "POST",
"href": "/pts/v2/payments/6760638084316175703955/captures"
}
},
"clientReferenceInformation": {
"code": "TC50171_3"
},
"id": "6760638084316175703955",
"orderInformation": {
"amountDetails": {
"authorizedAmount": "102.00",
"currency": "USD"
}
},
"paymentAccountInformation": {
"card": {
"type": "001"
}
},
"paymentInformation": {
"tokenizedCard": {
"type": "001"
},
"shippingAddress": {
"id": "F45FD8DE51B99E9CE053A2598D0AFDFA"
},
"card": {
"type": "001"
},
"customer": {
"id": "F45FB3E443AC3C57E053A2598D0A9CFF"
}
},
"pointOfSaleInformation": {
"terminalId": "111111"
},

Token Management Service | Customer Payment Instrument Tokens | 161

 "processorInformation": {
"paymentAccountReferenceNumber": "V0010013019326121921451482293",
"approvalCode": "888888",
"networkTransactionId": "123456789619999",
"transactionId": "123456789619999",
"responseCode": "100",
"avs": {
"code": "X",
"codeRaw": "I1"
}
},
"reconciliationId": "698162754DTIATRS",
"status": "AUTHORIZED",
"submitTimeUtc": "2023-02-10T21:16:48Z",
"tokenInformation": {
"instrumentidentifierNew": false,
"instrumentIdentifier": {
"state": "ACTIVE",
"id": "7030000000012931531"
},
"paymentInstrument": {
"id": "F45FE45E79DCC7DBE053A2598D0AED19"
}
}
}

Token Management Service | Customer Payment Instrument Tokens | 162

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 id 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 (on page 76) and Create a Customer Payment
Instrument (on page 137).

Required Fields for Changing a Customer's Default Payment

Instrument Using the REST API
customerTokenId
Include the ID of the customer token you want to retrieve in the URL path.
default
Set value to true.
paymentInstrumentTokenId
Include the ID of the payment instrument token you want to retrieve in the URL path.

Related Information

• API Field Reference for the REST API

Token Management Service | Customer Payment Instrument Tokens | 163

REST Example: Changing a Customer's Default Payment Instrument

Request

PATCH https://
apitest.cybersource.com/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/payment-instrume
nts/F39732BE4BDA9A1EE053AF598E0A4081

{
"default": true
}

Token Management Service | Customer Payment Instrument Tokens | 164

Response to a Successful Request

{
"_links": {
"self": {

"href": "/tms/v2/customers/F4D5E715F75E9910E053A2598D0A7278/payment-instruments/F4D5E715
F7BD9910E053A2598D0A7278"
},
"customer": {
"href": "/tms/v2/customers/F4D5E715F75E9910E053A2598D0A7278"
}
},
"id": "F4D5E715F7BD9910E053A2598D0A7278",
"default": true,
"state": "ACTIVE",
"card": {
"expirationMonth": "12",
"expirationYear": "2031",
"type": "001"
},
"billTo": {
"firstName": "John",
"lastName": "Doe",
"company": "Visa",
"address1": "1 Market St",
"locality": "san francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"instrumentIdentifier": {
"id": "7010000000016241111"
},
"metadata": {
"creator": "testrest"
},
"_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {
"href": "/tms/v1/instrumentidentifiers/7010000000016241111"
},
"paymentInstruments": {

"href": "/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstruments"
}

Token Management Service | Customer Payment Instrument Tokens | 165

 },
"id": "7010000000016241111",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXXXX1111"
},
"processingInformation": {
"authorizationOptions": {
"initiator": {
"merchantInitiatedTransaction": {
"previousTransactionId": "123456789619999"
}
}
}
},
"metadata": {
"creator": "testrest"
}
}
}
}

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 id 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 (on page 76) and Create a Customer Payment
Instrument (on page 137).

Token Management Service | Customer Payment Instrument Tokens | 166

REST Example: Retrieving a Customer Payment Instrument

Request

Pass the customer token ID and payment instrument token ID in the URL path.

GET https://
apitest.cybersource.com/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/payment-instrume
nts/F39732BE4BDA9A1EE053AF598E0A4081

Token Management Service | Customer Payment Instrument Tokens | 167

Response to a Successful Request

{
"_links": {
"self": {

"href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/payment-instruments/F39732BE
4BDA9A1EE053AF598E0A4081"
},
"customer": {
"href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078"
}
},
"id": "F39732BE4BDA9A1EE053AF598E0A4081",
"default": true,
"state": "ACTIVE",
"card": {
"expirationMonth": "12",
"expirationYear": "2031",
"type": "001"
},
"billTo": {
"firstName": "John",
"lastName": "Doe",
"company": "Company Name",
"address1": "1 Market St",
"locality": "San Francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"instrumentIdentifier": {
"id": "7010000000016241111"
},
"metadata": {
"creator": "testrest"
},
"_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {
"href": "/tms/v1/instrumentidentifiers/7010000000016241111"
},
"paymentInstruments": {
"href": "/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstruments"
}
},

Token Management Service | Customer Payment Instrument Tokens | 168

 "id": "7010000000016241111",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXXXX1111"
},
"processingInformation": {
"authorizationOptions": {
"initiator": {
"merchantInitiatedTransaction": {
"previousTransactionId": "123456789012345"
}
}
}
},
"metadata": {
"creator": "testrest"
}
}
}
}

Token Management Service | Customer Payment Instrument Tokens | 169

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 id 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 (on page 76) and Create a Customer Payment
Instrument (on page 137).

Important: You must pass the following request header to get this functionality: Accept:
application/jose.

REST Example: Retrieving a Customer Payment Instrument with

Unmasked Card Number

Request

Pass the customer token ID and payment instrument token ID in the URL path.

GET https://
apitest.cybersource.com/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/payment-instrume
nts/F39732BE4BDA9A1EE053AF598E0A4081

Token Management Service | Customer Payment Instrument Tokens | 170

Response to a Successful Request

eyJraWQiOiJiYTE1ZDRmMTIzMTM0NjlkZjg5MDM1Nzk2YWE4Nzc4ZGM0NTY4ODlkIiwiY3R5IjoianNvbiIsInR5cC
I6IkpXVCIsImVuYyI6IkEyNTZHQ00iLCJhbGciOiJSU0EtT0FFUC0yNTYifQ.FZbQse7mPcf255vpZFXM4Zy8DGalq
ehCYUi6h6ett2WqfP2XA0uzPeRxE-P6O8Ju1trkSOJcZ4PqBcX4xwYmSs8PUmhkakncpjXSvYUaq4RY39kj9BRzvn4
7F18OWCW4CDzaTkOxi7ynGN6vb_Y3_wn5KLXAQVTUCM7Lke45oAFrCnVACBJtQgONKM7GZwLwRiWp_HP6D4IMUZe5Q
w8Qz438scq9DQtOBum_JK_xx_IKA-r1XOkWdvnCasQnK1eEc2jPo3EL9GDe6w3zQFEbhNtC4Rsa33-lc0lxjfuAsI8
YmmtHYKeITvQ-6mB7cOP-guKnRAJk2SUPkMOL6UIfg.zvgReLHE0ybDfWRp.bCMwJgHEV9B9xHrL9Ej1en8xZCiYEu
CN6H4mcKOqxJAxZocO1AtR1xgyrfDIINAi6Jq9UJedIvLJFyMfXx2D2x4njHmxOKzC2KJS_KTpXR1s1-pJNG68jwZ-
g_zPqj1PLa_EGSu73NWhJYalGvhDuo6Ek8bkGVUtNm9OZ89oX2KbxuWc2LQ0JbBBa_dfQWAjkRcM-URlEbhf1nvlzL
wTXhRN2wfB7L1BcAsao51DyYXowOJpWwSK1StC2EKDXSzgpfXP1ZwSKA8SSkpVSmwOkb0n6DZNkwtKlg4eGDok9atJ
pbZ3qCEqqKDYCy1levJQ7w-In2OPLpSpFGyPRUGPBMTnzQo-GtGEM1tiKbpDUzaCL_0iFSGjJCPeottP-B98R2YKdm
Ga3IwyVWgzhAMJBkAfEGAx0TCWwqZE5xFW9uT2MzdX3_Mz9qBgCRa101km9dHYwajClVb1VETlHjS7zpQ1OtXPKmlu
AGTvGSr6PWn9ZiqkOd4R5LC7oA4OdVlpPhY2mJhektLOZj1uUIr5AaHyjHx-BnnFio0CDjM03t8gl9gIeQ44ugUMwY
c19Mvkiikxsvl8h9Ua2hCSFbvvq1cCOcZwb2UtI8EZcJdltw2utoiO5IbsSkE9hU2b16QMXoVIMxiFN0OdTfJqMzJf
PnyVBIkN3nmHmwLwKSek5HqdujU1hFhMJxDRdtmLD__5L0iAxuz1Sm3yx5HmjXWjCpzIfT9vT-pSfIdIwBakF9pBRX
DSCZsAEqlwddS1DbjfNk43E_wKTmwQW96OlnUX7SK70gICydciHsSsrElcp6lGFpbPMGs8QN1czKPrH0lrnkD21xkx
hXjmC7Iqa0-XFXIU8qSV7PsBtUjOnz7oKOzXvIli2SV2gzPEKOQ449HKPXDoBynaT5pWi4WC3JmOwAhyx2f05ABZF9
-Nj_EGLe7H5EoBaCohbKkc3j24nNQ4r_n5cC5weBCxIdkrSKh54pFQdRr72pqEW2XoOTy1Jafi3EJdC_GF0BKI3AFV
w3fGEJq_rpe8PxgkkliAuywVJ43iG_uzD-6Ib5jIA8RcDFah2jh_3tYeWws2EW3qnCuAUXREKebdGlH2BTgcgxzDn9
Y6AJi3Zrdc948qxXpowiYWr5t_5xN8x5kJcOzKVNOCzi5LggcIN-FmZsyB4rRjv9aGPrscoC1pL7xlLEnyHRnIOUy9
6NTG7qOQbhV3dzawvzZN_UZ6LTyTMV9X0679NNGS2RrjxFsrYuMHdQr3SeVcTKe5FL3QBiKFgFjnYMdh73ztYW5tn6
rAx2Daq5G-FkQnD8PnHnzCplGRXopja00xEkL9lugeKxSEorDPaO8ov499M191BrTqc6XaBl7kYuelWfAoVEfCT9Fv
Nf28H0xA5vXJNqKFye2ExkMyk3jjfCn3pkoFwmbyha1gmaLgz788GxMyKtH9K6KMKfgSCfj-w5eJbTl7QJeyYjFuVU
qixZI024YAUoo4OrcCZag1IzLNkpOo_xOqf1iMbREnDcp2MKxMdkJWI72uB5XWztHaQPnzBAxJcBw0_gB5AHy_AIk.
ogA-QQ53MEu1VwH6_H-DQA

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

Token Management Service | Customer Payment Instrument Tokens | 171

The {customerTokenId} is the customer token ID returned in the id field when you created the
customer token. For more information, see Create a Customer (on page 76) and Create a Customer
Payment Instrument (on page 137).

Required Fields for Listing Payment Instruments for a Customer Using

the REST API
customerTokenId
Include the ID of the customer token you want to retrieve in the URL path.

Related Information

• API Field Reference for the REST API

Token Management Service | Customer Payment Instrument Tokens | 172

REST Example: Listing Payment Instruments for a Customer

Request

Pass the customer token ID and instrument identifier token ID in the URL path. 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.

GET https://
apitest.cybersource.com/tms/v2/customers/7A906EC3D0F73581E0539599D30AADC1/payment-instrume
nts?offset=4&limit=2

Token Management Service | Customer Payment Instrument Tokens | 173

Response to a Successful Request

{
"_links": {
"self": {

"href": "/tms/v2/customers/7A906EC3D0F73581E0539599D30AADC1/payment-instruments?offset=4
&limit=2"
},
"first": {

"href": "/tms/v2/customers/7A906EC3D0F73581E0539599D30AADC1/payment-instruments?offset=0
&limit=2"
},
"prev": {

"href": "/tms/v2/customers/7A906EC3D0F73581E0539599D30AADC1/payment-instruments?offset=2
&limit=2"
},
"next": {

"href": "/tms/v2/customers/7A906EC3D0F73581E0539599D30AADC1/payment-instruments?offset=6
&limit=2"
},
"last": {

"href": "/tms/v2/customers/7A906EC3D0F73581E0539599D30AADC1/payment-instruments?offset=8
&limit=2"
}
},
"offset": 4,
"limit": 2,
"count": 2,
"total": 10,
"_embedded": {
"paymentInstruments": [
{
"_links": {
"self": {

"href": "/tms/v2/customers/7A906EC3D0F73581E0539599D30AADC1/payment-instruments/7A906EC3
D0F73581E0539599D30AAPI1"
},
"customer": {
"href": "/tms/v2/customers/7A906EC3D0F73581E0539599D30AADC1"
}
},
"id": "7A906EC3D0F73581E0539599D30AAPI1",
"state": "ACTIVE",

Token Management Service | Customer Payment Instrument Tokens | 174

"card": {
"expirationMonth": "09",
"expirationYear": "2017",
"type": "001",
"issueNumber": "01",
"startMonth": "01",
"startYear": "2016",
"useAs": "pinless debit",
"tokenizedInformation": {
"requestorID": "12345",
"transactionType": "1"
}
},
"buyerInformation": {
"companyTaxID": "12345",
"currency": "USD",
"dateOfBirth": "2000-12-13",
"personalIdentification": [
{
"id": "57684432111321",
"type": "driver license",
"issuedBy": {
"administrativeArea": "CA"
}
}
]
},
"billTo": {
"firstName": "John",
"lastName": "Smith",
"company": "Company Name",
"address1": "8310 Capital of Texas Highwas North",
"address2": "Bluffstone Drive",
"locality": "Austin",
"administrativeArea": "TX",
"postalCode": "78731",
"country": "US",
"email": "[email protected]",
"phoneNumber": "+44 2890447951"
},
"processingInformation": {
"billPaymentProgramEnabled": true,
"bankTransferOptions": {
"SECCode": "WEB"
}
},
"merchantInformation": {
"merchantDescriptor": {
"alternateName": "Branch Name"

Token Management Service | Customer Payment Instrument Tokens | 175

 }
},
"metadata": {
"creator": "mid"
},
"instrumentIdentifier": {
"id": "7040000000057621111"
},
"_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {
"href": "/tms/v1/instrumentidentifiers/7040000000057621111"
},
"paymentInstruments": {

"href": "/tms/v1/instrumentidentifiers/7040000000057621111/paymentinstruments"
}
},
"id": "7040000000057621111",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXXX1111"
},
"issuer": {
"paymentAccountReference": "V000000000000411111111111111"
},
"metadata": {
"creator": "mid"
}
}
}
},
{
"_links": {
"self": {

"href": "/tms/v2/customers/7A906EC3D0F73581E0539599D30AAPI1/payment-instruments/7A906EC3
D0F73581E0539599D30AAPI2"
},
"customer": {
"href": "/tms/v2/customers/7A906EC3D0F73581E0539599D30AAPI2"
}
},
"id": "7A906EC3D0F73581E0539599D30AAPI2",
"state": "ACTIVE",
"card": {
"expirationMonth": "09",

Token Management Service | Customer Payment Instrument Tokens | 176

 "expirationYear": "2017",
"type": "001",
"issueNumber": "01",
"startMonth": "01",
"startYear": "2016",
"useAs": "pinless debit",
"tokenizedInformation": {
"requestorID": "12345",
"transactionType": "1"
}
},
"buyerInformation": {
"companyTaxID": "12345",
"currency": "USD",
"dateOfBirth": "2000-12-13",
"personalIdentification": [
{
"id": "57684432111321",
"type": "driver license",
"issuedBy": {
"administrativeArea": "CA"
}
}
]
},
"billTo": {
"firstName": "John",
"lastName": "Smith",
"company": "Company Name",
"address1": "8310 Capital of Texas Highway North",
"address2": "Bluffstone Drive",
"locality": "Austin",
"administrativeArea": "TX",
"postalCode": "78731",
"country": "US",
"email": "[email protected]",
"phoneNumber": "+44 2890447951"
},
"processingInformation": {
"billPaymentProgramEnabled": true,
"bankTransferOptions": {
"SECCode": "WEB"
}
},
"merchantInformation": {
"merchantDescriptor": {
"alternateName": "Branch Name"
}
},

Token Management Service | Customer Payment Instrument Tokens | 177

 "metadata": {
"creator": "mid"
},
"instrumentIdentifier": {
"id": "7040000000057621111"
},
"_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {
"href": "/tms/v1/instrumentidentifiers/7040000000057621111"
},
"paymentInstruments": {

"href": "/tms/v1/instrumentidentifiers/7040000000057621111/paymentinstruments"
}
},
"id": "7040000000057621111",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXXX1111"
},
"issuer": {
"paymentAccountReference": "V000000000000411111111111111"
},
"metadata": {
"creator": "mid"
}
}
}
}
]
}
}

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}

Token Management Service | Customer Payment Instrument Tokens | 178

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 id 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 (on page 76) and Create a Customer Payment
Instrument (on page 137).

Required Fields for Updating a Customer Payment Instrument Using

the REST API
customerTokenId
Include the ID of the customer token you want to retrieve in the URL path.
paymentInstrumentTokenId
Include the ID of the payment instrument token you want to retrieve in the URL path.

Related Information

• API Field Reference for the REST API

Optional Fields for Updating a Customer Payment Instrument Using

the REST API
bankAccount.type

billTo.address1

billTo.address2

billTo.aminstrativeArea

billTo.company

billTo.country

billTo.email

billTo.firstName

billTo.lastName

Token Management Service | Customer Payment Instrument Tokens | 179

 billTo.locality

billTo.phoneNumber

billTo.postalCode

buyerInformation.companyTaxID

buyerInformation.currency

buyerInformation.dateOfBirth

buyerInformation.personalIdentification.id

buyerInformation.personalIdentification.issuedBy.administrativeArea

buyerInformation.personalIdentification.type

card.expirationMonth

card.expirationYear

card.issueNumber

card.startMonth

card.startYear

card.type

card.useAs

card.tokenizedInformation.requestorID

card.tokenizedInformation.transactionType

default
Set value to true if default, otherwise set value to false.
instrumentIdentifier.id

processingInformation.billPaymentProgramEnabled

merchantInformation.merchantDescriptor.alternateName

Related Information

• API Field Reference for the REST API

Token Management Service | Customer Payment Instrument Tokens | 180

REST Example: Updating a Customer Payment Instrument

Request

Pass the customer token ID and payment instrument token ID in the URL path.

PATCH https://
apitest.cybersource.com/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/payment-instrume
nts/F39732BE4BDA9A1EE053AF598E0A4081

{
"default": "true",
"card": {
"expirationMonth": "12",
"expirationYear": "2031",
"type": "001"
},
"billTo": {
"firstName": "John",
"lastName": "Doe",
"company": "Company Name",
"address1": "1 Market St",
"address2": "Unit B",
"locality": "San Francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"instrumentIdentifier": {
"id": "7010000000016241111"
}
}

Token Management Service | Customer Payment Instrument Tokens | 181

Response to a Successful Request

{
"_links": {
"self": {

"href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/payment-instruments/F39732BE
4BDA9A1EE053AF598E0A4081"
},
"customer": {
"href": "/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078"
}
},
"id": "F39732BE4BDA9A1EE053AF598E0A4081",
"default": true,
"state": "ACTIVE",
"card": {
"expirationMonth": "12",
"expirationYear": "2031",
"type": "001"
},
"billTo": {
"firstName": "John",
"lastName": "Doe",
"company": "Company Name",
"address1": "1 Market St",
"address2": "Unit B",
"locality": "San Francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"instrumentIdentifier": {
"id": "7010000000016241111"
},
"metadata": {
"creator": "testrest"
},
"_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {
"href": "/tms/v1/instrumentidentifiers/7010000000016241111"
},
"paymentInstruments": {
"href": "/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstruments"
}

Token Management Service | Customer Payment Instrument Tokens | 182

 },
"id": "7010000000016241111",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXXXX1111"
},
"processingInformation": {
"authorizationOptions": {
"initiator": {
"merchantInitiatedTransaction": {
"previousTransactionId": "123456789012345"
}
}
}
},
"metadata": {
"creator": "testrest"
}
}
}
}

REST Interactive Example: Updating a Customer Payment Instrument

Live Console URL: https://developer.cybersource.com/api-reference-assets/index.html#token-
management_customer-payment-instrument_update-a-customer-payment-instrument

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}

Token Management Service | Customer Payment Instrument Tokens | 183

The {customerTokenId} is the customer token ID returned in the id 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 (on page 76) and Create a Customer Payment
Instrument (on page 137).

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.

Required Fields for Deleting a Customer Payment Instrument Using

the REST API
customerTokenId
Include the ID of the customer token you want to retrieve in the URL path.
paymentInstrumentTokenId
Include the ID of the payment instrument token you want to retrieve in the URL path.

Related Information

• API Field Reference for the REST API

Token Management Service | Customer Payment Instrument Tokens | 184

REST Example: Deleting a Customer Payment Instrument

Request

Pass the customer token ID and payment instrument token ID in the URL path.

DELETE https://
apitest.cybersource.com/tms/v2/customers/F2F3ADA770102B51E053A2598D0A9078/payment-instrume
nts/F39732BE4BDA9A1EE053AF598E0A4081

Token Management Service | Customer Payment Instrument Tokens | 185

Response to a Successful Request

A successful delete response returns an empty HTTP 204 No Content status. For more information, see
HTTP Status Codes (on page 321).

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 (on page 187)

• Making a Credit with a Non-Default Payment Instrument (on page 192)

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

Token Management Service | Customer Payment Instrument Tokens | 186

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

Required Fields for Authorizing a Payment with a Non-Default

Payment Instrument
clientReferenceInformation.code

orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount

paymentInformation.paymentInstrument.id
Set to the ID of the payment instrument token you want to use.

Related Information

• API field reference guide for the REST API

Optional Fields for Authorizing a Payment with a Non-Default

Payment Instrument
You can use these optional fields to include additional information when authorizing a payment with
a non-default payment instrument.
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount

orderInformation.billTo.address1

orderInformation.billTo.administrativeArea

Token Management Service | Customer Payment Instrument Tokens | 187

 orderInformation.billTo.country

orderInformation.billTo.email

orderInformation.billTo.firstName

orderInformation.billTo.lastName

orderInformation.billTo.locality

orderInformation.billTo.postalCode

paymentInformation.card.expirationMonth

paymentInformation.card.expirationYear

paymentInformation.card.number

paymentInformation.card.type

Related Information

• API field reference guide for the REST API

REST Example: Authorizing 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

Request

{
"clientReferenceInformation": {
"code": "12345678"
},
"paymentInformation": {
"paymentInstrument": {
"id": "0F3BB131F8143A58E063A2598D0AB921"
}
},
"orderInformation": {

Token Management Service | Customer Payment Instrument Tokens | 188

 "amountDetails": {
"currency": "USD",
"totalAmount": "10.00"
}
}
}

Token Management Service | Customer Payment Instrument Tokens | 189

Response to a Successful Request

{
"_links": {
"authReversal": {
"method": "POST",
"href": "/pts/v2/payments/7055952648586653304951/reversals"
},
"self": {
"method": "GET",
"href": "/pts/v2/payments/7055952648586653304951"
},
"capture": {
"method": "POST",
"href": "/pts/v2/payments/7055952648586653304951/captures"
}
},
"clientReferenceInformation": {
"code": "12345678"
},
"id": "7055952648586653304951",
"orderInformation": {
"amountDetails": {
"authorizedAmount": "10.00",
"currency": "USD"
}
},
"paymentAccountInformation": {
"card": {
"type": "001"
}
},
"paymentInformation": {
"tokenizedCard": {
"type": "001"
},
"instrumentIdentifier": {
"id": "7010000000016241111",
"state": "ACTIVE"
},
"paymentInstrument": {
"id": "0F3BB131F8143A58E063A2598D0AB921"
},
"card": {
"type": "001"
}
},
"pointOfSaleInformation": {
"terminalId": "111111"

Token Management Service | Customer Payment Instrument Tokens | 190

 },
"processorInformation": {
"approvalCode": "888888",
"networkTransactionId": "123456789619999",
"transactionId": "123456789619999",
"responseCode": "100",
"avs": {
"code": "X",
"codeRaw": "I1"
}
},
"reconciliationId": "67468244CRIL0U0Y",
"status": "AUTHORIZED",
"submitTimeUtc": "2024-01-18T16:27:45Z"
}

Token Management Service | Customer Payment Instrument Tokens | 191

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

Required Fields for Making a Credit with a Non-Default Payment

Instrument
clientReferenceInformation.code

orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount

paymentInformation.paymentInstrument.id
Set to the ID of the payment instrument token that you want to use.

Related Information

• API field reference guide for the REST API

Optional Fields for Making a Credit with a Non-Default Payment

Instrument
You can use these optional fields to include additional information when making a credit with a non-
default payment instrument.
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount

orderInformation.billTo.address1

orderInformation.billTo.administrativeArea

orderInformation.billTo.country

Token Management Service | Customer Payment Instrument Tokens | 192

 orderInformation.billTo.email

orderInformation.billTo.firstName

orderInformation.billTo.lastName

orderInformation.billTo.locality

orderInformation.billTo.postalCode

paymentInformation.card.expirationMonth

paymentInformation.card.expirationYear

paymentInformation.card.number

paymentInformation.card.type

Related Information

• API field reference guide for the REST API

REST Example: Making a Credit with a Non-Default Payment

Instrument
Endpoint:

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

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

Request

{
"clientReferenceInformation": {
"code": "12345678"
},
"paymentInformation": {
"paymentInstrument": {
"id": "0F3BB131F8143A58E063A2598D0AB921"
}
},
"orderInformation": {
"amountDetails": {
"currency": "USD",

Token Management Service | Customer Payment Instrument Tokens | 193

 "totalAmount": "10.00"
}
}
}

Token Management Service | Customer Payment Instrument Tokens | 194

Response to a Successful Request

{
"_links": {
"void": {
"method": "POST",
"href": "/pts/v2/credits/7055968581386446104953/voids"
},
"self": {
"method": "GET",
"href": "/pts/v2/credits/7055968581386446104953"
}
},
"clientReferenceInformation": {
"code": "12345678"
},
"creditAmountDetails": {
"currency": "USD",
"creditAmount": "10.00"
},
"id": "7055968581386446104953",
"orderInformation": {
"amountDetails": {
"currency": "USD"
}
},
"paymentAccountInformation": {
"card": {
"type": "001"
}
},
"paymentInformation": {
"tokenizedCard": {
"type": "001"
},
"instrumentIdentifier": {
"id": "7010000000016241111",
"state": "ACTIVE"
},
"paymentInstrument": {
"id": "0F3BB131F8143A58E063A2598D0AB921"
},
"card": {
"type": "001"
}
},
"processorInformation": {
"approvalCode": "888888",
"responseCode": "100"

Token Management Service | Customer Payment Instrument Tokens | 195

 },
"reconciliationId": "67445196PRILCQCN",
"status": "PENDING",
"submitTimeUtc": "2024-01-18T16:54:18Z"
}

Token Management Service | Customer Payment Instrument Tokens | 196

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.

Related information
Manage Payment Instrument Tokens (on page 197)
Payments with Payment Instrument Tokens (on page 225)

Manage Payment Instrument Tokens

This section contains information on managing 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.

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 (on page 197)

• Retrieve a payment instrument token (on page 202)

• Update a payment instrument (on page 217)

• Delete a payment instrument (on page 222)

For more information on payment instrument tokens, see Payment Instrument Tokens (on page 21).

Create a Payment Instrument

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

Token Management Service | Payment Instrument Tokens | 197

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

Required Fields for Creating a Payment Instrument Using the REST API
card.type

instrumentIdentifier.id
Include the ID of the instrument identifier token you want to use to create a payment
instrument.

Related Information

• API Field Reference for the REST API

Optional Fields for Creating a Payment Instrument Using the REST API
default
Set value to true if default, otherwise set value to false.
bankAccount.type

billTo.firstName

billTo.lastName

billTo.company

billTo.address1

billTo.locality

billTo.administrativeArea

billTo.postalCode

billTo.country

billTo.email

Token Management Service | Payment Instrument Tokens | 198

 billTo.phoneNumber

card.expirationMonth

card.expirationYear

card.issueNumber

card.startMonth

card.startYear

card.useAs

tokenizedInformation.requestorID

tokenizedInformation.transactionType

buyerInformation.companyTaxID

buyerInformation.currency

buyerInformation.dateOfBirth

buyerInformation.personalIdentification.id

buyerInformation.personalIdentification.type

buyerInformation.personalIdentification.issuedBy.administrativeArea

billTo.address2

processingInformation.billPaymentProgramEnabled

processingInformation.bankTransferOptions.SECCode

merchantInformation.merchantDescriptor.alternateName

Related Information

• API Field Reference for the REST API

Token Management Service | Payment Instrument Tokens | 199

REST Example: Creating a Payment Instrument

Request

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

{
"card": {
"expirationMonth": "12",
"expirationYear": "2031",
"type": "visa"
},
"billTo": {
"firstName": "John",
"lastName": "Doe",
"company": "Company Name",
"address1": "1 Market St",
"locality": "San Francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"instrumentIdentifier": {
"id": "7010000000016241111"
}
}

Token Management Service | Payment Instrument Tokens | 200

Response to a Successful Request

{
"_links": {
"self": {

"href": https://
apitest.cybersource.com/tms/v1/paymentinstruments/F39763E8CFDF2354E053AF598E0AF684"
}
},
"id": "F39763E8CFDF2354E053AF598E0AF684",
"object": "paymentInstrument",
"state": "ACTIVE",
"card": {
"expirationMonth": "12",
"expirationYear": "2031",
"type": "visa"
},
"billTo": {
"firstName": "John",
"lastName": "Doe",
"company": "Company Name",
"address1": "1 Market St",
"locality": "San Francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"metadata": {
"creator": "testrest"
},
"_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111"
},
"paymentInstruments": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts"
}
},
"id": "7010000000016241111",

Token Management Service | Payment Instrument Tokens | 201

 "object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXXXX1111"
},
"processingInformation": {
"authorizationOptions": {
"initiator": {
"merchantInitiatedTransaction": {
"previousTransactionId": "123456789619999"
}
}
}
},
"metadata": {
"creator": "testrest"
}
}
}
}

REST Interactive Example: Creating a Payment Instrument

Live Console URL: https://developer.cybersource.com/api-reference-assets/index.html#token-
management_payment-instrument_create-a-payment-instrument

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 (on page 197).

Token Management Service | Payment Instrument Tokens | 202

REST Example: Retrieving a Payment Instrument

Request

Pass the payment instrument token ID in the URL path.

GET https://
apitest.cybersource.com/tms/v1/paymentinstruments/F39763E8CFDF2354E053AF598E0AF684

Token Management Service | Payment Instrument Tokens | 203

Response to a Successful Request

{
"_links": {
"self": {

"href": "https://
apitest.cybersource.comtms/v1/paymentinstruments/F39763E8CFDF2354E053AF598E0AF684"
}
},
"id": "F39763E8CFDF2354E053AF598E0AF684",
"object": "paymentInstrument",
"state": "ACTIVE",
"card": {
"expirationMonth": "12",
"expirationYear": "2031",
"type": "visa"
},
"billTo": {
"firstName": "John",
"lastName": "Doe",
"company": "Company Name",
"address1": "1 Market St",
"locality": "San Francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"metadata": {
"creator": "testrest"
},
"_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111"
},
"paymentInstruments": {

"href": "https://
apitest.cybersource.comtms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts"
}
},
"id": "7010000000016241111",

Token Management Service | Payment Instrument Tokens | 204

 "object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXXXX1111"
},
"processingInformation": {
"authorizationOptions": {
"initiator": {
"merchantInitiatedTransaction": {
"previousTransactionId": "123456789619999"
}
}
}
},
"metadata": {
"creator": "testrest"
}
}
}
}

Token Management Service | Payment Instrument Tokens | 205

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 id field when you
created the instrument identifier token. For more information, see Create an Instrument Identifier
(on page 235).

Required Fields for Finding Payment Instruments by Card Number

Using the REST API
instrumentIdentifierTokenId
Include the ID of the instrument identifier token you want to retrieve in the URL path.

Related Information

• API Field Reference for the REST API

REST Example: Finding Payment Instruments by Card Number

Request

Pass the instrument identifier token ID in the URL path.

GET https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts?offset=0&limit=5

Token Management Service | Payment Instrument Tokens | 206

Response to a Successful Request

{
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts?offset=0&limit=5"
},
"first": {

"href": "https://
apitest.cybersource.comtms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts?offset=0&limit=5"
},
"next": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts?offset=5&limit=5"
},
"last": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts?offset=121265&limit=5"
}
},
"object": "collection",
"offset": 0,
"limit": 5,
"count": 5,
"total": 121269,
"_embedded": {
"paymentInstruments": [
{
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/paymentinstruments/F4D5E715F7BD9910E053A2598D0A7278"
},
"customer": {

"href": "https://
apitest.cybersource.com/tms/v1/customers/F4D5E715F75E9910E053A2598D0A7278"
}
},

Token Management Service | Payment Instrument Tokens | 207

 "id": "F4D5E715F7BD9910E053A2598D0A7278",
"object": "paymentInstrument",
"state": "ACTIVE",
"card": {
"expirationMonth": "12",
"expirationYear": "2031",
"type": "visa"
},
"billTo": {
"firstName": "John",
"lastName": "Doe",
"company": "Visa",
"address1": "1 Market St",
"locality": "san francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"metadata": {
"creator": "testrest"
},
"_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111"
},
"paymentInstruments": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts"
}
},
"id": "7010000000016241111",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXXXX1111"
},
"processingInformation": {
"authorizationOptions": {
"initiator": {
"merchantInitiatedTransaction": {
"previousTransactionId": "123456789619999"

Token Management Service | Payment Instrument Tokens | 208

 }
}
}
},
"metadata": {
"creator": "testrest"
}
}
}
},
{
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/paymentinstruments/F4D5E70505B30CF9E053AF598E0A005F"
},
"customer": {

"href": "https://
apitest.cybersource.com/tms/v1/customers/F4D5E70505B40CF9E053AF598E0A005F"
}
},
"id": "F4D5E70505B30CF9E053AF598E0A005F",
"object": "paymentInstrument",
"state": "ACTIVE",
"card": {
"expirationMonth": "02",
"expirationYear": "2024",
"type": "visa"
},
"buyerInformation": {
"currency": "USD"
},
"billTo": {
"firstName": "NOREAL",
"lastName": "NAME",
"address1": "1295 Charleston Road",
"locality": "Mountain View",
"administrativeArea": "CA",
"postalCode": "94043",
"country": "US",
"email": "[email protected]"
},
"metadata": {
"creator": "testrest"
},
"_embedded": {
"instrumentIdentifier": {

Token Management Service | Payment Instrument Tokens | 209

 "_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111"
},
"paymentInstruments": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts"
}
},
"id": "7010000000016241111",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXXXX1111"
},
"processingInformation": {
"authorizationOptions": {
"initiator": {
"merchantInitiatedTransaction": {
"previousTransactionId": "123456789619999"
}
}
}
},
"metadata": {
"creator": "testrest"
}
}
}
},
{
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/paymentinstruments/F4D566EED6D369CCE053AF598E0A495B"
},
"customer": {

"href": "https://
apitest.cybersource.com/tms/v1/customers/F4D5523603862EE0E053AF598E0AE5FE"
}
},
"id": "F4D566EED6D369CCE053AF598E0A495B",
"object": "paymentInstrument",

Token Management Service | Payment Instrument Tokens | 210

 "state": "ACTIVE",
"card": {
"expirationMonth": "12",
"expirationYear": "2031",
"type": "visa"
},
"buyerInformation": {
"currency": "USD"
},
"billTo": {
"firstName": "JOHN",
"lastName": "DOE",
"address1": "1 Market St",
"locality": "san francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"processingInformation": {
"billPaymentProgramEnabled": false
},
"metadata": {
"creator": "testrest"
},
"_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111"
},
"paymentInstruments": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts"
}
},
"id": "7010000000016241111",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXXXX1111"
},
"processingInformation": {
"authorizationOptions": {

Token Management Service | Payment Instrument Tokens | 211

 "initiator": {
"merchantInitiatedTransaction": {
"previousTransactionId": "123456789619999"
}
}
}
},
"metadata": {
"creator": "testrest"
}
}
}
},
{
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/paymentinstruments/F4CDBDD6E0A57EC9E053AF598E0AB69F"
},
"customer": {

"href": "https://
apitest.cybersource.com/tms/v1/customers/F4CDBCA630247B2EE053AF598E0ADC91"
}
},
"id": "F4CDBDD6E0A57EC9E053AF598E0AB69F",
"object": "paymentInstrument",
"state": "ACTIVE",
"card": {
"expirationMonth": "12",
"expirationYear": "2034",
"type": "visa"
},
"buyerInformation": {
"currency": "USD"
},
"billTo": {
"firstName": "JOHN",
"lastName": "DOE",
"address1": "1 Market St",
"locality": "san francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"processingInformation": {

Token Management Service | Payment Instrument Tokens | 212

 "billPaymentProgramEnabled": false
},
"metadata": {
"creator": "testrest"
},
"_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111"
},
"paymentInstruments": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts"
}
},
"id": "7010000000016241111",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXXXX1111"
},
"processingInformation": {
"authorizationOptions": {
"initiator": {
"merchantInitiatedTransaction": {
"previousTransactionId": "123456789619999"
}
}
}
},
"metadata": {
"creator": "testrest"
}
}
}
},
{
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/paymentinstruments/F4CDEF212EAA0B13E053AF598E0AB8F4"
},
"customer": {

Token Management Service | Payment Instrument Tokens | 213

 "href": "https://
apitest.cybersource.com/tms/v1/customers/F4CDBCA630247B2EE053AF598E0ADC91"
}
},
"id": "F4CDEF212EAA0B13E053AF598E0AB8F4",
"object": "paymentInstrument",
"state": "ACTIVE",
"card": {
"expirationMonth": "12",
"expirationYear": "2031",
"type": "visa"
},
"buyerInformation": {
"currency": "USD"
},
"billTo": {
"firstName": "JOHN",
"lastName": "DOE",
"address1": "1 Market St",
"locality": "san francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"processingInformation": {
"billPaymentProgramEnabled": false
},
"metadata": {
"creator": "testrest"
},
"_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111"
},
"paymentInstruments": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts"
}
},
"id": "7010000000016241111",

Token Management Service | Payment Instrument Tokens | 214

 "object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXXXX1111"
},
"processingInformation": {
"authorizationOptions": {
"initiator": {
"merchantInitiatedTransaction": {
"previousTransactionId": "123456789619999"
}
}
}
},
"metadata": {
"creator": "testrest"
}
}
}
}
]
}
}

Token Management Service | Payment Instrument Tokens | 215

Retrieve a 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/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 (on page 197).

Important: You must pass the following request header to get this functionality: Accept:
application/jose.

REST Example: Retrieving a Payment Instrument with Unmasked Card

Number

Request

GET https://
apitest.cybersource.com/tms/v1/paymentinstruments/F39763E8CFDF2354E053AF598E0AF684

Token Management Service | Payment Instrument Tokens | 216

Response to a Successful Request

eyJraWQiOiJiYTE1ZDRmMTIzMTM0NjlkZjg5MDM1Nzk2YWE4Nzc4ZGM0NTY4ODlkIiwiY3R5IjoianNvbiIsInR5cC
I6IkpXVCIsImVuYyI6IkEyNTZHQ00iLCJhbGciOiJSU0EtT0FFUC0yNTYifQ.sPdY7WNX0jWady6jdHytYj8WmAyBL
q401OeNNc3-cb2LWyOo11LY3r2mcJo_foZN3W175B0LzEH1IgYT96eQ8qpct7UXvvQLqdB25XCQIsRMU0tqugAox9Q
KDk1q0DMZpeki8O0_HWu1Nk6vGKwQP2XrCPDs9eZ4tHQCoId_8bffjHFOOgVDgFtG7pJ0MpIC7eeadJZCQKsEp5ZEw
zTaGmyJrVLpwMKPMKh63eLYNSTndQihOpMXlWZS1yMvZJzgdf18qQdBB-bINs2jGhgTAGhPaorRsFpHPqvOQm9WRAM
FJU0nq1zzEd2xyf9nG45Wl6VXEOZi87c7riyketm0lA.mxf5cgCFa2NwXuS1._NBdqbu4r0glrtKkIOLkGdiu1Azmb
NLloKFY7-tMIaQ2xA1IpgR1tDHQOfQbumPS752jtjPPvXpHnXHp3pxifM8TJR_F76NcMI0SO3r5_PLePiLtQeyZJna
W6o6ENTrFNnhgG80TNLFS4NqsX6sIQsgm5D2S2Kf1yQL4B3goxHJTMulngvTBVJBGUf6rw5zr-q-w7buAA8NoquyIf
Gx0wORSFO8e_392aX5AWbySFoUobJ1arQJARsfKdoyHsskmfsCJAwRZF6_uvFbw7uoq60TmBjwfGTdsJffqGEYSuU8
ZzXWl6Q9sPAGptwHj-JuWVnEZAq3362Cgqv3DfZtEAS-ewBd8DpzCQXatC4pUz1xj3sE5RzBQtzt8IY_exCL970UsM
xh5pJc8eqT61z5Sf7nxaNj1limcnH7_rnR1LaJ8foQAvZo8rJl8PuLe3inNOqYhAMpu6UURNB126LPHi0W7F7o4MtF
a8fm5rNF7Mbk-z4Xwx4b-FNKr3g_5JyYbJgOSAF9Kwbg7GzOGLyIPwTvXpUbFkyWoGWCgvfRDTVTBrbdlwcuFFDlFA
4B-i9L79DcMRgHb6VqgVuy-A4fA9990ctmwChY0kkfnJYcFcEaT0bgLpJw6hadtmGgyW62yJMCRLF4GtU_PUyZ6k9s
64KH6Ulro7Cbu_wcXiqklqymgCr50Ifx-gDtL3tAv_YoiI-numvNsk0EY8JZtmI4YOUK9V1SbrVy354X3rhPzUt2k5
F8LHnExOnKugsACoFFOjpDaEBe1kI7X6UfKZU876m1H0lS5-ccZ3VVDbdpxHlMKrSrMehno6g4ba9phdqtvuajef6P
73yF3kvHoHhXvxxrEUYcUGIlef9HMvN6NS9sxj2j5Q9LsED1XuyGBoRd5JO-gjeIHx0P__6SPiX2WdfqvVNIaS9f1k
1eOOmCTERz9Esmb7vS13XzKyaN5DAFM9R3Tl2PUmDN-AtlRN5A9moTsvvQKci-CsGTUeEYUWfpbU4UHtzXic06BygA
aFJat1plfeJy1u1qhVLUWkC4Jo6i_KryvAiJ8qb8urb_TFGWHhs2-JLQs8e3e20Ze4AkayQW-hypmshrsMgi86mqcD
4o7IOY_27H4PYD2rVNPw0lSUuxDYCp87ILro_ROiMKu3Gi1jlX-MDqJ-v3PCf21EjgEsB8kV4L1O8ZKFCVOFGpVaXT
vhKXjeEUyYVSB9uM6UTWcYGJznkClJV3vio1xpnRVpeppmTc4x0FABt7xPXCI_B81Q2q2mR9MS_Az7l-XTRIPz6skc
MMjSyS6HI4f-zg__TVWw78gupg4O0xFT1Mpbcs3HxQPtcBHoQ3EWenIcB1Pnso9IOwN3z4bSDj1OI3-cgMRFPwUKLh
JvOh0I5Jql_BKSdEnTJ4WyqY2EswrlG7dZ4fVexoMOi9UX117GqQcmdj0mboOnXDPKfclfv55nkg7ogHhz5OvsonLx
XA9LwCnL0iyISowImm1pUc-Gx1gnEPXvx1Xew7ARamkJIam3MAqhLmxwE0E6CO9xw8AG3wDSznPK3RyE6JeiuVxhRb
r5hJGQLIfH-gu13NTMh3JtPNsnmz0uvF2nZKmcWj8QmuHE76L3qYD7xCwXbGwSDPHp7AhAPueCG8D0sG6Ilf_0S9P3
-mTM1PhL2_AFpF_r9L-R-3-QrgJXVGYTbQaIFJvGG_swpS_o6s2c9iEKI7WK3nZG0pfjiFw0UGTF4cNEj2DWzgLCj2
1pcKgqUDbncf3hYbqnHgNUmxHGjjOxZdiaL31-ccfNodHg6O8kvRr_hhEA9IKG49uCJoPqJtJmOFa4MuSEdIuWBF_l
Sc.fenpFUQKAgR4qz7Ft_6Igg

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}

Token Management Service | Payment Instrument Tokens | 217

The {paymentInstrumentTokenId} is the payment instrument token ID you want to retrieve. For more
information, see Create a Payment Instrument (on page 197).

Required Fields for Updating a Payment Instrument Using the REST

API
paymentInstrumentTokenId
Include the ID of the payment instrument token you want to retrieve in the URL path.

Related Information

• API Field Reference for the REST API

Optional Fields for Updating a Payment Instrument Using the REST

API
default

bankAccount.type

card.issueNumber

card.startMonth

card.startYear

card.useAs

tokenizedInformation.requestorID

tokenizedInformation.transactionType

buyerInformation.companyTaxID

buyerInformation.currency

buyerInformation.dateOfBirth

buyerInformation.personalIdentification.id

buyerInformation.personalIdentification.type

buyerInformation.personalIdentification.issuedBy.administrativeArea

billTo.address2

Token Management Service | Payment Instrument Tokens | 218

 processingInformation.billPaymentProgramEnabled

processingInformation.bankTransferOptions.SECCode

merchantInformation.merchantDescriptor.alternateName

Related Information

• API Field Reference for the REST API

Token Management Service | Payment Instrument Tokens | 219

REST Example: Updating a Payment Instrument

Request

Pass the payment instrument token ID in the URL path.

PATCH https://
apitest.cybersource.com/tms/v1/paymentinstruments/F39763E8CFDF2354E053AF598E0AF684

{
"card": {
"expirationMonth": "12",
"expirationYear": "2031",
"type": "visa"
},
"billTo": {
"firstName": "John",
"lastName": "Doe",
"company": "Company Name",
"address1": "1 Market St",
"address2": "Unit B"
"locality": "San Francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"instrumentIdentifier": {
"id": "7010000000016241111"
}
}

Token Management Service | Payment Instrument Tokens | 220

Response to a Successful Request

{
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/paymentinstruments/F39763E8CFDF2354E053AF598E0AF684"
}
},
"id": "F39763E8CFDF2354E053AF598E0AF684",
"object": "paymentInstrument",
"state": "ACTIVE",
"card": {
"expirationMonth": "12",
"expirationYear": "2031",
"type": "visa"
},
"billTo": {
"firstName": "Jack",
"lastName": "Smith",
"company": "Company Name",
"address1": "1 Market St",
"address2": "Unit B",
"locality": "San Francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158888674"
},
"metadata": {
"creator": "testrest"
},
"_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111"
},
"paymentInstruments": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts"
}
},

Token Management Service | Payment Instrument Tokens | 221

 "id": "7010000000016241111",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXXXX1111"
},
"processingInformation": {
"authorizationOptions": {
"initiator": {
"merchantInitiatedTransaction": {
"previousTransactionId": "123456789619999"
}
}
}
},
"metadata": {
"creator": "testrest"
}
}
}
}

REST Interactive Example: Updating a Payment Instrument

Live Console URL: https://developer.cybersource.com/api-reference-assets/index.html#token-
management_payment-instrument_update-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}

Token Management Service | Payment Instrument Tokens | 222

The {paymentInstrumentTokenId} is the payment instrument token ID you want to retrieve. For more
information, see Create a Payment Instrument (on page 197).

Required Fields for Deleting a Payment Instrument Using the REST API
paymentInstrumentTokenId
Include the ID of the payment instrument token you want to retrieve in the URL path.

Related Information

• API Field Reference for the REST API

Token Management Service | Payment Instrument Tokens | 223

REST Example: Deleting a Payment Instrument

Request

Pass the payment instrument token ID in the URL path.

DELETE https://
apitest.cybersource.com/tms/v1/paymentinstruments/F39763E8CFDF2354E053AF598E0AF684

Token Management Service | Payment Instrument Tokens | 224

Successful Response
A successful delete response returns an empty HTTP 204 No Content status. For more information, see
HTTP Status Codes (on page 321).

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 (on page 226)

• Making a Credit with a Payment Instrument (on page 231)

For more information on payment instrument tokens, see Payment Instrument Tokens (on page 21).

Token Management Service | Payment Instrument Tokens | 225

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

Required Fields for Authorizing a Payment with a Payment Instrument

clientReferenceInformation.code

orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount

paymentInformation.paymentInstrument.id
Set to the ID of the payment instrument token you want to use.

Related Information

• API field reference guide for the REST API

Optional Fields for Authorizing a Payment with a Payment Instrument

You can use these optional fields to include additional information when authorizing a payment with
a payment instrument.
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount

orderInformation.billTo.address1

orderInformation.billTo.administrativeArea

orderInformation.billTo.country

orderInformation.billTo.email

Token Management Service | Payment Instrument Tokens | 226

 orderInformation.billTo.firstName

orderInformation.billTo.lastName

orderInformation.billTo.locality

orderInformation.billTo.postalCode

paymentInformation.card.expirationMonth

paymentInformation.card.expirationYear

paymentInformation.card.number

paymentInformation.card.type

Related Information

• API field reference guide for the REST API

REST Example: Authorizing 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

Request

{
"clientReferenceInformation": {
"code": "12345678"
},
"paymentInformation": {
"paymentInstrument": {
"id": "F4D5E715F7BD9910E053A2598D0A7278"
}
},
"orderInformation": {
"amountDetails": {
"currency": "USD",
"totalAmount": "10.00"

Token Management Service | Payment Instrument Tokens | 227

 }
}
}

Token Management Service | Payment Instrument Tokens | 228

Response to a Successful Request

{
"_links": {
"authReversal": {
"method": "POST",
"href": "/pts/v2/payments/6765713628736138103955/reversals"
},
"self": {
"method": "GET",
"href": "/pts/v2/payments/6765713628736138103955"
},
"capture": {
"method": "POST",
"href": "/pts/v2/payments/6765713628736138103955/captures"
}
},
"clientReferenceInformation": {
"code": "12345678"
},
"id": "6765713628736138103955",
"orderInformation": {
"amountDetails": {
"authorizedAmount": "10.00",
"currency": "USD"
}
},
"paymentAccountInformation": {
"card": {
"type": "001"
}
},
"paymentInformation": {
"tokenizedCard": {
"type": "001"
},
"instrumentIdentifier": {
"id": "7010000000016241111",
"state": "ACTIVE"
},
"paymentInstrument": {
"id": "F4D5E715F7BD9910E053A2598D0A7278"
},
"card": {
"type": "001"
},
"customer": {
"id": "F4D5E715F75E9910E053A2598D0A7278"
}

Token Management Service | Payment Instrument Tokens | 229

 },
"pointOfSaleInformation": {
"terminalId": "111111"
},
"processorInformation": {
"approvalCode": "888888",
"networkTransactionId": "123456789619999",
"transactionId": "123456789619999",
"responseCode": "100",
"avs": {
"code": "X",
"codeRaw": "I1"
}
},
"reconciliationId": "60561224BE37KN5W",
"status": "AUTHORIZED",
"submitTimeUtc": "2023-02-16T18:16:03Z"
}

Token Management Service | Payment Instrument Tokens | 230

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

Required Fields for Making a Credit with a Payment Instrument

clientReferenceInformation.code

orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount

paymentInformation.paymentInstrument.id
Set to the ID of the payment instrument token you want to use.

Related Information

• API field reference guide for the REST API

REST Example: Making a Credit with a Payment Instrument

Endpoint:

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

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

Request

{
"clientReferenceInformation": {
"code": "12345678"
},

Token Management Service | Payment Instrument Tokens | 231

 "paymentInformation": {
"paymentInstrument": {
"id": "F4D5E715F7BD9910E053A2598D0A7278"
}
},
"orderInformation": {
"amountDetails": {
"currency": "USD",
"totalAmount": "10.00"
}
}
}

Token Management Service | Payment Instrument Tokens | 232

Response to a Successful Request

{
"_links": {
"void": {
"method": "POST",
"href": "/pts/v2/credits/7055969586686467104953/voids"
},
"self": {
"method": "GET",
"href": "/pts/v2/credits/7055969586686467104953"
}
},
"clientReferenceInformation": {
"code": "12345678"
},
"creditAmountDetails": {
"currency": "USD",
"creditAmount": "10.00"
},
"id": "7055969586686467104953",
"orderInformation": {
"amountDetails": {
"currency": "USD"
}
},
"paymentAccountInformation": {
"card": {
"type": "001"
}
},
"paymentInformation": {
"tokenizedCard": {
"type": "001"
},
"instrumentIdentifier": {
"id": "7010000000016241111",
"state": "ACTIVE"
},
"paymentInstrument": {
"id": "F4D5E715F7BD9910E053A2598D0A7278"
},
"card": {
"type": "001"
}
},
"processorInformation": {
"approvalCode": "888888",
"responseCode": "100"

Token Management Service | Payment Instrument Tokens | 233

 },
"reconciliationId": "67446174JRIKXXHB",
"status": "PENDING",
"submitTimeUtc": "2024-01-18T16:55:59Z"
}

Token Management Service | Payment Instrument Tokens | 234

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.

Related information
Manage Instrument Identifier Tokens (on page 235)
Payments with Instrument Identifier Tokens (on page 261)

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 (on page 235)

• Retrieve an instrument identifier token (on page 240)

• Update an instrument identifier (on page 243)

• Delete an instrument identifier (on page 258)

• List payment instruments for an instrument identifier (on page 247)

For more information on instrument identifier tokens, see Instrument Identifier Tokens (on page 22).

Create an Instrument Identifier

This section shows you how to create an instrument identifier.

Token Management Service | Instrument Identifier Tokens | 235

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

Required Fields for Creating an Instrument Identifier Using the REST

API
card.number

Related Information

• API Field Reference for the REST API

Token Management Service | Instrument Identifier Tokens | 236

Optional Fields for Creating an Instrument Identifier Using the REST
API
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

Related Information

• API Field Reference for the REST API

Token Management Service | Instrument Identifier Tokens | 237

REST Example: Creating a Card Instrument Identifier

Request

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

{
"card": {
"number": "4111XXXX11111111"
}
}

Response to a Successful Request

{
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111"
},
"paymentInstruments": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts"
}
},
"id": "7010000000016241111",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXXXX1111"
},
"metadata": {
"creator": "testrest"
}
}

REST Interactive Example: Creating an Instrument Identifier

Live Console URL: https://developer.cybersource.com/api-reference-assets/index.html#token-
management_instrument-identifier_create-an-instrument-identifier

Token Management Service | Instrument Identifier Tokens | 238

REST Example: Creating a Bank Account Instrument Identifier

Request

POST https://apitest.cybersource.com/tms/v1/instrumentidentifiers
{
"bankAccount": {
"number": "4100",
"routingNumber": "X71923284"
}
}

Response to a Successful Request

{
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/A7A91A2CA872B272E05340588D0A0699"
},
"paymentInstruments": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/A7A91A2CA872B272E05340588D0A0699/paym
entinstruments"
}
},
"id": "A7A91A2CA872B272E05340588D0A0699",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"bankAccount": {
"number": "XXXX",
"routingNumber": "X71923284"
},
"metadata": {
"creator": "testrest"
}
}

Token Management Service | Instrument Identifier Tokens | 239

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 id field when you
created the instrument identifier token. For more information, see Create an Instrument Identifier
(on page 235).

Token Management Service | Instrument Identifier Tokens | 240

REST Example: Retrieving an Instrument Identifier

Request

Pass the instrument identifier token ID in the URL path.

GET https://apitest.cybersource.com/tms/v1/instrumentidentifiers/7030000000046226486

Token Management Service | Instrument Identifier Tokens | 241

Response to a Successful Request

{
"_links": {
"self": {
"href":
https://apitest.visaacceptance.com/tms/v1/instrumentidentifiers/7030000000046226486
},
"paymentInstruments": {
"href":
https://
apitest.visaacceptance.com/tms/v1/instrumentidentifiers/7030000000046226486/paymentinstrum
ents
}
},
"id": "7030000000046226486",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"tokenizedCard": {
"state": "ACTIVE",
"enrollmentId": "80efd04a838265dcdf9d114eb542be01",
"tokenReferenceId": "003769ea947eb057c13c192f1d26f002",
"number": "489537XXXXXX2655",
"expirationMonth": "12",
"expirationYear": "2030",
"type": "visa",
"card": {
"suffix": "6486",
"expirationMonth": "12",
"expirationYear": "2030"
}
},
"card": {
"number": "489537XXXXXX6486"
},
"issuer": {
"paymentAccountReference": "V0010013020037567013722096631"
},
"metadata": {
"creator": "testacct"
}
}

Token Management Service | Instrument Identifier Tokens | 242

REST Interactive Example: Retrieving an Instrument Identifier
Live Console URL: https://developer.cybersource.com/api-reference-assets/index.html#token-
management_instrument-identifier_retrieve-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 id field when you
created the instrument identifier token. For more information, see Create an Instrument Identifier
(on page 235).

Required Fields for Updating an Instrument Identifier Using the REST

API
instrumentIdentifierTokenId
Include the ID of the instrument identifier token you want to retrieve in the URL path.

Related Information

• API Field Reference for the REST API

Optional Fields for Updating an Instrument Identifier Using the REST

API
bankAccount.number

Token Management Service | Instrument Identifier Tokens | 243

 bankAccount.routingNumber

billTo.address1

billTo.address2

billTo.administrativeArea

billTo.country

billTo.locality

billTo.postalCode

card.expirationMonth

card.expirationYear

card.securityCode

Related Information

• API Field Reference for the REST API

Token Management Service | Instrument Identifier Tokens | 244

REST Example: Updating an Instrument Identifier

Request

Pass the instrument identifier token ID in the URL path.

PATCH https://apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111

Token Management Service | Instrument Identifier Tokens | 245

Response to a Successful Request

{
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111"
},
"paymentInstruments": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts"
}
},
"id": "7010000000016241111",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXXXX1111"
},
"processingInformation": {
"authorizationOptions": {
"initiator": {
"merchantInitiatedTransaction": {
"previousTransactionId": "123456789012345"
}
}
}
},
"metadata": {
"creator": "testrest"
}
}

REST Interactive Example: Updating an Instrument Identifier

Live Console URL: https://developer.cybersource.com/api-reference-assets/index.html#token-
management_instrument-identifier_update-an-instrument-identifier

Token Management Service | Instrument Identifier Tokens | 246

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 id field when you
created the instrument identifier token. For more information, see Create an Instrument Identifier
(on page 235).

Token Management Service | Instrument Identifier Tokens | 247

REST Example: Retrieving an Instrument Identifier's Payment
Instruments

Request

Pass the instrument identifier token ID in the URL path. 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.

GET https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts?offset=0&limit=5

Token Management Service | Instrument Identifier Tokens | 248

Response to a Successful Request

{
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts?offset=0&limit=5"
},
"first": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts?offset=0&limit=5"
},
"next": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts?offset=5&limit=5"
},
"last": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts?offset=120820&limit=5"
}
},
"object": "collection",
"offset": 0,
"limit": 5,
"count": 5,
"total": 120825,
"_embedded": {
"paymentInstruments": [
{
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/paymentinstruments/F396A4DD49CA23ADE053A2598D0AECC4"
},
"customer": {

"href": "https://
apitest.cybersource.com/tms/v1/customers/F396A4DD49CB23ADE053A2598D0AECC4"
}
},

Token Management Service | Instrument Identifier Tokens | 249

 "id": "F396A4DD49CA23ADE053A2598D0AECC4",
"object": "paymentInstrument",
"state": "ACTIVE",
"card": {
"expirationMonth": "12",
"expirationYear": "2031",
"type": "visa"
},
"buyerInformation": {
"currency": "USD"
},
"billTo": {
"firstName": "JOHN",
"lastName": "DOE",
"address1": "1 Market St",
"locality": "san francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"processingInformation": {
"billPaymentProgramEnabled": false
},
"metadata": {
"creator": "testrest"
},
"_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111"
},
"paymentInstruments": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts"
}
},
"id": "7010000000016241111",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXXXX1111"
},

Token Management Service | Instrument Identifier Tokens | 250

 "processingInformation": {
"authorizationOptions": {
"initiator": {
"merchantInitiatedTransaction": {
"previousTransactionId": "123456789012345"
}
}
}
},
"metadata": {
"creator": "testrest"
}
}
}
},
{
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/paymentinstruments/F3969009C44DED0DE053AF598E0AD4E0"
},
"customer": {

"href": "https://
apitest.cybersource.com/tms/v1/customers/F396A109D27377A5E053AF598E0AA34A"
}
},
"id": "F3969009C44DED0DE053AF598E0AD4E0",
"object": "paymentInstrument",
"state": "ACTIVE",
"card": {
"type": "visa"
},
"metadata": {
"creator": "testrest"
},
"_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111"
},
"paymentInstruments": {

Token Management Service | Instrument Identifier Tokens | 251

 "href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts"
}
},
"id": "7010000000016241111",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXXXX1111"
},
"processingInformation": {
"authorizationOptions": {
"initiator": {
"merchantInitiatedTransaction": {
"previousTransactionId": "123456789012345"
}
}
}
},
"metadata": {
"creator": "testrest"
}
}
}
},
{
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/paymentinstruments/F396A109F3637776E053AF598E0A87E4"
},
"customer": {

"href": "https://
apitest.cybersource.com/tms/v1/customers/F396A109D27377A5E053AF598E0AA34A"
}
},
"id": "F396A109F3637776E053AF598E0A87E4",
"object": "paymentInstrument",
"state": "ACTIVE",
"card": {
"expirationMonth": "12",
"expirationYear": "2031",
"type": "visa"
},
"billTo": {

Token Management Service | Instrument Identifier Tokens | 252

 "firstName": "John",
"lastName": "Doe",
"company": "Company Name",
"address1": "1 Market St",
"locality": "San Francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"metadata": {
"creator": "testrest"
},
"_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111"
},
"paymentInstruments": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts"
}
},
"id": "7010000000016241111",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXXXX1111"
},
"processingInformation": {
"authorizationOptions": {
"initiator": {
"merchantInitiatedTransaction": {
"previousTransactionId": "123456789012345"
}
}
}
},
"metadata": {
"creator": "testrest"
}
}
}

Token Management Service | Instrument Identifier Tokens | 253

 },
{
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/paymentinstruments/F3965253C47640F5E053AF598E0AA05A"
}
},
"id": "F3965253C47640F5E053AF598E0AA05A",
"object": "paymentInstrument",
"state": "ACTIVE",
"card": {
"expirationMonth": "02",
"expirationYear": "2028",
"type": "visa"
},
"billTo": {
"firstName": "John",
"lastName": "Snow"
},
"metadata": {
"creator": "testrest"
},
"_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111"
},
"paymentInstruments": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts"
}
},
"id": "7010000000016241111",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXXXX1111"
},
"processingInformation": {
"authorizationOptions": {
"initiator": {
"merchantInitiatedTransaction": {

Token Management Service | Instrument Identifier Tokens | 254

 "previousTransactionId": "123456789012345"
}
}
}
},
"metadata": {
"creator": "testrest"
}
}
}
},
{
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/paymentinstruments/F395F6426D9A30AEE053AF598E0A5BD4"
}
},
"id": "F395F6426D9A30AEE053AF598E0A5BD4",
"object": "paymentInstrument",
"state": "ACTIVE",
"card": {
"expirationMonth": "12",
"expirationYear": "2031",
"type": "visa"
},
"billTo": {
"firstName": "John",
"lastName": "Doe",
"company": "Company Name",
"address1": "1 Market St",
"locality": "San Francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"metadata": {
"creator": "testrest"
},
"_embedded": {
"instrumentIdentifier": {
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111"

Token Management Service | Instrument Identifier Tokens | 255

 },
"paymentInstruments": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts"
}
},
"id": "7010000000016241111",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXXXX1111"
},
"processingInformation": {
"authorizationOptions": {
"initiator": {
"merchantInitiatedTransaction": {
"previousTransactionId": "123456789012345"
}
}
}
},
"metadata": {
"creator": "testrest"
}
}
}
}
]
}
}

REST Interactive Example: Retrieving an Instrument Identifier's

Payment Instruments
Live Console URL: https://developer.cybersource.com/api-reference-assets/index.html#token-
management_instrument-identifier_list-payment-instruments-for-an-instrument-identifier

Token Management Service | Instrument Identifier Tokens | 256

Retrieve an Instrument Identifier with Unmasked Card Number
This section shows you how retrieve an instrument identifier with unmasked card number.

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 id field when you
created the instrument identifier token. For more information, see Create an Instrument Identifier
(on page 235).

Important: You must pass the following request header to get this functionality: Accept:
application/jose.

REST Example: Retrieving an Instrument Identifier with Unmasked

Card Number

Request

GET https://apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111

Token Management Service | Instrument Identifier Tokens | 257

Response to a Successful Request

eyJraWQiOiJiYTE1ZDRmMTIzMTM0NjlkZjg5MDM1Nzk2YWE4Nzc4ZGM0NTY4ODlkIiwiY3R5IjoianNvbiIsInR5cC
I6IkpXVCIsImVuYyI6IkEyNTZHQ00iLCJhbGciOiJSU0EtT0FFUC0yNTYifQ.N_XRPaRJACKNHBAUvXIu11eoB
kgouHb5mrA1LL-WHVfKRpfUoGpHRVp0WRy7b1NLh4-qAlLI3QKnxxplx4tzSaJCn3kQDNt0BnRmKecRvFTGKXk09e
ATF8J7lLfNjYZEgZgA4qe3FdIEWIMN_BwQMJMEy0cMJdpyGtvUt9G6rgmQUDsjwSDU5tQNMopjgqjDUw6rBjbxTprN
tBLpNCqjbSe4-vW_xiZIfFpQs_45YPWV4fRn5YuH7ebfckB1evTdfGRlBMHXfjac_QA8a1gMv_50T2y1VXllam2OSC
2hSabOtd43pGDsFwj5HhOGjobb6GprbNedlIBL5Mlo-2_wCg.OkTe1Z7OredhIrF_.3eEeC9OUfz7uXxl1FLSZZNFG
UiX7vk77SGVCW7cypDuVpy5QpK2wVJzTYrjJFgGlEiE05GwXP04gOsOOp5C6OEhCXKbdGMZO_V0FAyxk1dnx28ur-c
SG-86HdbBRbWsvcuh4ghMqx8WTlA-M13YKubY6L2LcK0yWROn9MrYlUWzgJFjXFZDkpCxsHpMtvXRxcF6nTQkJD4rw
_SHGuHqWbVlQKyIEBcvbuyecjYtz7iZtP_HS349TOOmpbJDxJ-X8exZy3LLTmD7PHjpySYGx-svlkP-Qu4yi_xFtzm
kwf7T7O56SAa9DidDeH9ftGi7V67MBMBGK6Ndl8nK4sn6SieBDMWxnFthNdHZFEhlSONIywGfE-mYI5nuagrNVOo-Z
QqJ2woYXdocdEvyTQ7oDvRy432872l6nUDTZcVdYlVj79KDrW73LjvUYWcAvXZr0bDgI-e1YNziInqgi3DlNNeL6W2
srYrSuqJG5-NnWIISt3Pb8qfa2ve06uRhztpyWisWEZOCVG1SLg_LZTPjaDoe2woJ1kyP2VaEM4VoRynQ0dCZsLlpu
8_s24rj96T-qoi2QkUybUQ3rpYiUUPl1-jhhimMpar4wsJJRIsVfsf6KVz876ReMgvW1Jzm5G0Ypj7acvvqnDAeMEf
RzXvpLvAVpGXP6RbVXuyg3wyUg_8-PqOlllRiavS8eg9-ZdeuAkPQ.4vZxOPrGjw51SFJmn_cF3g

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 id field in the

id field when you created the instrument identifier token. For more information, see Create an
Instrument Identifier (on page 235).

Required Fields for Deleting an Instrument Identifier Using the REST

API
instrumentIdentifierTokenId
Include the ID of the instrument identifier token you want to retrieve in the URL path.

Token Management Service | Instrument Identifier Tokens | 258

Related Information

• API Field Reference for the REST API

Token Management Service | Instrument Identifier Tokens | 259

REST Example: Deleting an Instrument Identifier

Request

Pass the instrument identifier token ID in the URL path.

DELETE https://apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111

Token Management Service | Instrument Identifier Tokens | 260

Response to a Successful Request
A successful delete response returns an empty HTTP 204 No Content status. For more information, see
HTTP Status Codes (on page 321).

REST Interactive Example: Deleting an Instrument Identifier

Live Console URL: https://developer.cybersource.com/api-reference-assets/index.html#token-
management_instrument-identifier_delete-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 (on page 262)

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 (on page 267)

• Making a Credit with an Instrument Identifier (on page 274)

For more information on instrument identifier tokens, see Instrument Identifier Tokens (on page 22).

Token Management Service | Instrument Identifier Tokens | 261

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 id field when you created the customer
token. For more information, see Create a Customer (on page 76).

Required Fields for Creating an Instrument Identifier Token with

Validated Payment Details Using the REST API
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount

orderInformation.billTo.address1

orderInformation.billTo.administrativeArea

orderInformation.billTo.country

orderInformation.billTo.email

orderInformation.billTo.firstName

orderInformation.billTo.lastName

orderInformation.billTo.locality

orderInformation.billTo.postalCode

paymentInformation.card.expirationMonth

paymentInformation.card.expirationYear

paymentInformation.card.number

paymentInformation.card.type

Token Management Service | Instrument Identifier Tokens | 262

 processingInformation.actionList
Set the value to TOKEN_CREATE.
processingInformation.actionTokenTypes
Set the value to instrumentIdentifier.

Related Information

• API Field Reference for the REST API

REST Example: Creating an Instrument Identifier with Validated

Payment Details

Request

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

{
"clientReferenceInformation": {
"code": "TC50171_3"
},
"processingInformation": {
"commerceIndicator": "internet",
"actionList": [
"TOKEN_CREATE"
],
"actionTokenTypes": [
"instrumentIdentifier"
]
},
"orderInformation": {
"billTo": {
"country": "US",
"lastName": "Deo",
"address2": "Address 2",
"address1": "201 S. Division St.",
"postalCode": "48104-2201",
"locality": "Ann Arbor",
"administrativeArea": "MI",
"firstName": "John",
"phoneNumber": "999999999",
"district": "MI",

Token Management Service | Instrument Identifier Tokens | 263

 "buildingNumber": "123",
"company": "Visa",
"email": "[email protected]"
},
"shipTo": {
"country": "US",
"lastName": "Deo",
"address2": "Address 2",
"address1": "201 S. Division St.",
"postalCode": "48104-2201",
"locality": "Ann Arbor",
"administrativeArea": "MI",
"firstName": "John",
"phoneNumber": "999999999",
"district": "MI",
"buildingNumber": "123",
"company": "Visa",
"email": "[email protected]"
},
"amountDetails": {
"totalAmount": "102.00",
"currency": "USD"
}
},
"paymentInformation": {
"card": {
"expirationYear": "2031",
"number": "4895379987X11515",
"securityCode": "890",
"expirationMonth": "12",
"type": "001"
}
}
}

Token Management Service | Instrument Identifier Tokens | 264

Response to a Successful Request

{
"_links": {
"authReversal": {
"method": "POST",
"href": "/pts/v2/payments/6760634870346154903955/reversals"
},
"self": {
"method": "GET",
"href": "/pts/v2/payments/6760634870346154903955"
},
"capture": {
"method": "POST",
"href": "/pts/v2/payments/6760634870346154903955/captures"
}
},
"clientReferenceInformation": {
"code": "TC50171_3"
},
"id": "6760634870346154903955",
"orderInformation": {
"amountDetails": {
"authorizedAmount": "102.00",
"currency": "USD"
}
},
"paymentAccountInformation": {
"card": {
"type": "001"
}
},
"paymentInformation": {
"tokenizedCard": {
"type": "001"
},
"card": {
"type": "001"
}
},
"pointOfSaleInformation": {
"terminalId": "111111"
},
"processorInformation": {
"paymentAccountReferenceNumber": "V0010013019326121174070050420",
"approvalCode": "888888",
"networkTransactionId": "123456789619999",
"transactionId": "123456789619999",
"responseCode": "100",

Token Management Service | Instrument Identifier Tokens | 265

 "avs": {
"code": "X",
"codeRaw": "I1"
}
},
"reconciliationId": "698162504DTIATR3",
"status": "AUTHORIZED",
"submitTimeUtc": "2023-02-10T21:11:27Z",
"tokenInformation": {
"instrumentidentifierNew": false,
"instrumentIdentifier": {
"state": "ACTIVE",
"id": "7030000000014911515"
}
}
}

Token Management Service | Instrument Identifier Tokens | 266

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

Required Fields for Authorizing a Payment with an Instrument

Identifier
clientReferenceInformation.code

orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount

paymentInformation.instrumentIdentifier.id
Set to the ID of the instrument identifier token you want to use.

Related Information

• API field reference guide for the REST API

REST Interactive Example: Authorizing a Payment with an Instrument

Identifier
Live Console URL: https://developer.cybersource.com/api-reference-assets/
index.html#payments_payments_process-a-payment_samplerequests-dropdown_authorization-
using-tokens_authorization-with-instrument-identifier-token-id_liveconsole-tab-request-body

REST Example: Authorizing a Payment with an Instrument Identifier

Endpoint:

Token Management Service | Instrument Identifier Tokens | 267

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

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

Request

{
"clientReferenceInformation": {
"code": "12345678"
},
"paymentInformation": {
"instrumentIdentifier": {
"id": "7010000000016241111"
}
},
"orderInformation": {
"amountDetails": {
"currency": "USD",
"totalAmount": "10.00"
}
}
}

Token Management Service | Instrument Identifier Tokens | 268

Response to a Successful Request

{
"_links": {
"authReversal": {
"method": "POST",
"href": "/pts/v2/payments/7055955288186053404953/reversals"
},
"self": {
"method": "GET",
"href": "/pts/v2/payments/7055955288186053404953"
},
"capture": {
"method": "POST",
"href": "/pts/v2/payments/7055955288186053404953/captures"
}
},
"clientReferenceInformation": {
"code": "12345678"
},
"id": "7055955288186053404953",
"orderInformation": {
"amountDetails": {
"authorizedAmount": "10.00",
"currency": "USD"
}
},
"paymentAccountInformation": {
"card": {
"type": "001"
}
},
"paymentInformation": {
"tokenizedCard": {
"type": "001"
},
"instrumentIdentifier": {
"id": "7010000000016241111",
"state": "ACTIVE"
},
"card": {
"type": "001"
}
},
"pointOfSaleInformation": {
"terminalId": "111111"
},
"processorInformation": {
"approvalCode": "888888",

Token Management Service | Instrument Identifier Tokens | 269

 "networkTransactionId": "123456789619999",
"transactionId": "123456789619999",
"responseCode": "100",
"avs": {
"code": "1"
}
},
"reconciliationId": "67468271CRIL0U24",
"status": "AUTHORIZED",
"submitTimeUtc": "2024-01-18T16:32:09Z"
}

REST Example: Authorizing a Payment with an Instrument Identifier

While Creating TMS Tokens
This example shows you how to authorize a payment using an instrument identifier token while
creating customer, payment instrument, and shipping address tokens.

Endpoint:

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

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

Request

{
"clientReferenceInformation": {
"code": "TC50171_3"
},
"processingInformation": {
"actionList": [
"TOKEN_CREATE"
],
"actionTokenTypes": [
"customer",
"paymentInstrument",
"shippingAddress"
]
},
"paymentInformation": {
"instrumentIdentifier": {
"id": "7010000000016241111"
}
},

Token Management Service | Instrument Identifier Tokens | 270

 "orderInformation": {
"amountDetails": {
"totalAmount": "102.21",
"currency": "USD"
},
"billTo": {
"firstName": "John",
"lastName": "Doe",
"address1": "1 Market St",
"locality": "san francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US",
"email": "[email protected]",
"phoneNumber": "4158880000"
},
"shipTo": {
"firstName": "John",
"lastName": "Doe",
"address1": "1 Market St",
"locality": "san francisco",
"administrativeArea": "CA",
"postalCode": "94105",
"country": "US"
}
}
}

Token Management Service | Instrument Identifier Tokens | 271

Response to a Successful Request

{
"_links": {
"authReversal": {
"method": "POST",
"href": "/pts/v2/payments/7114679840376687203955/reversals"
},
"self": {
"method": "GET",
"href": "/pts/v2/payments/7114679840376687203955"
},
"capture": {
"method": "POST",
"href": "/pts/v2/payments/7114679840376687203955/captures"
}
},
"clientReferenceInformation": {
"code": "TC50171_3"
},
"id": "7114679840376687203955",
"orderInformation": {
"amountDetails": {
"authorizedAmount": "102.21",
"currency": "USD"
}
},
"paymentAccountInformation": {
"card": {
"type": "001"
}
},
"paymentInformation": {
"tokenizedCard": {
"type": "001"
},
"instrumentIdentifier": {
"id": "7010000000016241111",
"state": "ACTIVE"
},
"card": {
"type": "001"
}
},
"pointOfSaleInformation": {
"terminalId": "111111"
},
"processorInformation": {
"approvalCode": "888888",

Token Management Service | Instrument Identifier Tokens | 272

 "networkTransactionId": "123456789619999",
"transactionId": "123456789619999",
"responseCode": "100",
"avs": {
"code": "X",
"codeRaw": "I1"
}
},
"reconciliationId": "623971212U7PN4IU",
"status": "AUTHORIZED",
"submitTimeUtc": "2024-03-26T15:46:24Z",
"tokenInformation": {
"shippingAddress": {
"id": "14930C904FC4D97BE063A2598D0AE0F1"
},
"paymentInstrument": {
"id": "149310A4A924E911E063A2598D0A47AD"
},
"customer": {
"id": "14930C904FC1D97BE063A2598D0AE0F1"
}
}
}

Token Management Service | Instrument Identifier Tokens | 273

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

Required Fields for Making a Credit with an Instrument Identifier

clientReferenceInformation.code

orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount

paymentInformation.paymentInstrument.id
Set to the ID of the payment instrument token you want to use.

Related Information

• API field reference guide for the REST API

REST Interactive Example: Making a Credit with an Instrument

Identifier
Live Console URL: https://developer.cybersource.com/api-reference-assets/
index.html#payments_credit_process-a-credit_samplerequests-dropdown_credit-with-
tokenization_credit-with-instrument-identifier-token-id_liveconsole-tab-request-body

REST Example: Making a Credit with an Instrument Identifier

Endpoint:

Token Management Service | Instrument Identifier Tokens | 274

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

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

Request

{
"clientReferenceInformation": {
"code": "12345678"
},
"paymentInformation": {
"instrumentIdentifier": {
"id": "7010000000016241111"
}
},
"orderInformation": {
"amountDetails": {
"currency": "USD",
"totalAmount": "10.00"
}
}
}

Token Management Service | Instrument Identifier Tokens | 275

Response to a Successful Request

{
"_links": {
"void": {
"method": "POST",
"href": "/pts/v2/credits/7055970261066212404951/voids"
},
"self": {
"method": "GET",
"href": "/pts/v2/credits/7055970261066212404951"
}
},
"clientReferenceInformation": {
"code": "12345678"
},
"creditAmountDetails": {
"currency": "USD",
"creditAmount": "10.00"
},
"id": "7055970261066212404951",
"orderInformation": {
"amountDetails": {
"currency": "USD"
}
},
"paymentAccountInformation": {
"card": {
"type": "001"
}
},
"paymentInformation": {
"tokenizedCard": {
"type": "001"
},
"instrumentIdentifier": {
"id": "7010000000016241111",
"state": "ACTIVE"
},
"card": {
"type": "001"
}
},
"processorInformation": {
"approvalCode": "888888",
"responseCode": "100"
},
"reconciliationId": "67445198PRILCQCQ",

Token Management Service | Instrument Identifier Tokens | 276

 "status": "PENDING",
"submitTimeUtc": "2024-01-18T16:57:06Z"
}

Token Management Service | Instrument Identifier Tokens | 277

Legacy Tokens
A legacy token refers to an existing customer token, instrument identifier token, payment instrument
token, or a shipping address token.

Payments with Legacy Tokens

This section contains information on making payments with legacy tokens.

It is recommended to use the TMS customer, payment instrument, or instrument identifier token
ID fields rather than the legacy token ID. To process a payment using legacy token, instrument
identifier token, or payment instrument token, you must include the legacy token ID in the request.
For example:

• Authorizing a Payment with a Legacy Token (on page 279)

• Making a Credit with a Legacy Token (on page 283)

Token Management Service | Legacy Tokens | 278

Authorizing a Payment with a Legacy Token
This section shows you how to authorize a payment with a legacy token.

Endpoint

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

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

Required Fields for Authorizing a Payment with a Legacy Token

clientReferenceInformation.code

paymentInformation.legacyToken.id
Include the ID of the legacy token you want to use to authorize a payment.
orderInformation.amountDetails.currency

orderInformation.amountDetails.totalAmount

Related Information

• API field reference guide for the REST API

REST Interactive Example: Authorizing a Payment with a Legacy Token

Live Console URL: https://developer.cybersource.com/api-reference-assets/
index.html#payments_payments_process-a-payment_samplerequests-dropdown_authorization-
using-tokens_authorization-with-legacy-token_liveconsole-tab-request-body

REST Example: Authorizing a Payment with a Legacy Token

Endpoint:

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

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

Token Management Service | Legacy Tokens | 279

Request

{
"clientReferenceInformation": {
"code": "12345678"
},
"paymentInformation": {
"legacyToken": {
"id": "B21E6717A6F03479E05341588E0A303F"
}
},
"orderInformation": {
"amountDetails": {
"totalAmount": "22.00",
"currency": "USD"
}
}
}

Token Management Service | Legacy Tokens | 280

Response to a Successful Request

{
"_links": {
"authReversal": {
"method": "POST",
"href": "/pts/v2/payments/7055956342476789004951/reversals"
},
"self": {
"method": "GET",
"href": "/pts/v2/payments/7055956342476789004951"
},
"capture": {
"method": "POST",
"href": "/pts/v2/payments/7055956342476789004951/captures"
}
},
"clientReferenceInformation": {
"code": "12345678"
},
"id": "7055956342476789004951",
"orderInformation": {
"amountDetails": {
"authorizedAmount": "22.00",
"currency": "USD"
}
},
"paymentAccountInformation": {
"card": {
"type": "001"
}
},
"paymentInformation": {
"tokenizedCard": {
"type": "001"
},
"card": {
"type": "001"
}
},
"pointOfSaleInformation": {
"terminalId": "111111"
},
"processorInformation": {
"approvalCode": "888888",
"networkTransactionId": "123456789619999",
"transactionId": "123456789619999",
"responseCode": "100",
"avs": {

Token Management Service | Legacy Tokens | 281

 "code": "X",
"codeRaw": "I1"
}
},
"reconciliationId": "67468431FRIIS246",
"status": "AUTHORIZED",
"submitTimeUtc": "2024-01-18T16:33:54Z"
}

Token Management Service | Legacy Tokens | 282

Making a Credit with a Legacy Token
This section shows you how to make a credit with a legacy 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

Required Fields for Making a Credit with a Legacy Token

clientReferenceInformation.code

orderInformation.amountDetails.currency

orderInformation.amountDetails.totalAmount

paymentInformation.legacyToken.id
Include the ID of the legacy token that you want to use to authorize a payment.

Related Information

• API field reference guide for the REST API

REST Example: Making a Credit with a Legacy Token

Endpoint:

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

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

Request

{
"clientReferenceInformation": {
"code": "12345678"
},

Token Management Service | Legacy Tokens | 283

 "paymentInformation": {
"legacyToken": {
"id": "B21E6717A6F03479E05341588E0A303F"
}
},
"orderInformation": {
"amountDetails": {
"totalAmount": "22.00",
"currency": "USD"
}
}
}

Token Management Service | Legacy Tokens | 284

Response to a Successful Request

{
"_links": {
"void": {
"method": "POST",
"href": "/pts/v2/credits/7055970562096509704953/voids"
},
"self": {
"method": "GET",
"href": "/pts/v2/credits/7055970562096509704953"
}
},
"clientReferenceInformation": {
"code": "12345678"
},
"creditAmountDetails": {
"currency": "USD",
"creditAmount": "22.00"
},
"id": "7055970562096509704953",
"orderInformation": {
"amountDetails": {
"currency": "USD"
}
},
"paymentAccountInformation": {
"card": {
"type": "001"
}
},
"paymentInformation": {
"tokenizedCard": {
"type": "001"
},
"card": {
"type": "001"
}
},
"processorInformation": {
"approvalCode": "888888",
"responseCode": "100"
},
"reconciliationId": "67444779FRILJT84",

Token Management Service | Legacy Tokens | 285

 "status": "PENDING",
"submitTimeUtc": "2024-01-18T16:57:36Z"
}

Token Management Service | Legacy Tokens | 286

Network Tokens for Merchants
Network tokens are network scheme generated tokens that represent customer card information
for secure transactions. Network tokens are mapped to instrument identifier tokens and can be
provisioned directly through Cybersource for merchants.

Payments with Network Tokens for Merchants

This section contains information on making payments with network tokens for merchants.

Network tokens are generated by the network scheme and represent customer card information for
secure transactions. Network schemes include but are not limited to Visa, Mastercard, and American
Express. Network tokens are mapped to instrument identifier tokens. The minimum card data
required to request a network token is the PAN and the expiration date.

Payments are made using network tokens by default for merchants. To authorize a payment ignoring
the network token, you must indicate this in the request. For example:

• Authorize a Payment While Ignoring Network Token (on page 288)

For more information on network tokens, see Network Tokens (on page 22).

Token Management Service | Network Tokens for Merchants | 287

Authorize a Payment While Ignoring Network Token
This section shows you how to authorize a payment ignoring a network token.

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

Required Fields for Authorizing a Payment While Ignoring Network

Token Using the REST API
clientReferenceInformation.code

paymentInformation.customer.id

paymentInformation.paymentInformation.id

paymentInformation.shippingAddress.id

orderInformation.amountDetails.currency

orderInformation.amountDetails.totalAmount

processingInformation.capture

processingInformation.commerceIndicator

tokenInformation.networkTokenOption
Set value to ignore.

Related Information

• API Field Reference for the REST API

Token Management Service | Network Tokens for Merchants | 288

REST Example: Authorizing a Payment While Ignoring Network Token

Request

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

{
"clientReferenceInformation": {
"code": "RTS-Auth"
},
"paymentInformation": {
"card": {
"expirationYear": "2031",
"expirationMonth": "12",
"type": "001"
},
"instrumentIdentifier": {
"id": "7010000000016241111"
}
},
"orderInformation": {
"amountDetails": {
"currency": "USD",
"totalAmount": "1.00"
}
},
"processingInformation": {
"capture": "false",
"commerceIndicator": "internet"
},
"tokenInformation": {
"networkTokenOption": "ignore"
}
}

Token Management Service | Network Tokens for Merchants | 289

Response to a Successful Request

{
"_links": {
"authReversal": {
"method": "POST",
"href": "/pts/v2/payments/6769913443166412604951/reversals"
},
"self": {
"method": "GET",
"href": "/pts/v2/payments/6769913443166412604951"
},
"capture": {
"method": "POST",
"href": "/pts/v2/payments/6769913443166412604951/captures"
}
},
"clientReferenceInformation": {
"code": "RTS-Auth"
},
"id": "6769913443166412604951",
"orderInformation": {
"amountDetails": {
"authorizedAmount": "1.00",
"currency": "USD"
}
},
"paymentAccountInformation": {
"card": {
"type": "001"
}
},
"paymentInformation": {
"tokenizedCard": {
"type": "001"
},
"instrumentIdentifier": {
"id": "7030000000014911515",
"state": "ACTIVE"
},
"shippingAddress": {
"id": "F537CE8DBA2F032CE053AF598E0A64F2"
},
"paymentInstrument": {
"id": "F537E3D12322416EE053AF598E0AD771"
},
"card": {
"type": "001"
},

Token Management Service | Network Tokens for Merchants | 290

 "customer": {
"id": "F537CE8DBA2C032CE053AF598E0A64F2"
}
},
"pointOfSaleInformation": {
"terminalId": "111111"
},
"processorInformation": {
"paymentAccountReferenceNumber": "V0010013019326121174070050420",
"approvalCode": "888888",
"networkTransactionId": "123456789619999",
"transactionId": "123456789619999",
"responseCode": "100",
"avs": {
"code": "X",
"codeRaw": "I1"
}
},
"reconciliationId": "744295942E2LY3F8",
"status": "AUTHORIZED",
"submitTimeUtc": "2023-02-21T14:55:44Z"
}

Manage Merchant-Initiated Transactions and Network Tokens

This section contains information for using network tokens in merchant-initiated transactions (MIT).

Network tokens are generated by the network scheme and represent customer card information for
secure transactions. Network schemes include but are not limited to Visa, Mastercard, and American
Express. Network tokens are mapped to instrument identifier tokens. The minimum card data
required to request a network token is the PAN and the expiration date.

You can manage merchant-initiated transactions using network tokens by including the relevant MIT
information in requests sent to tms/v2/customers. For example:

• Update Merchant-Initiated Transaction Authorization Options (on page 292)

For more information on network tokens and credentialed transactions, see Network Tokens (on
page 22) and Credentialed Transactions, respectively.

Token Management Service | Network Tokens for Merchants | 291

Update Merchant-Initiated Transaction Authorization Options
This section shows you how to update merchant-initiated transaction (MIT) authorization options.

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 id field when you
created the instrument identifier token. For more information, see Create an Instrument Identifier
(on page 235).

Required Fields for Updating MIT Authorization Options Using the

REST API
instrumentIdentifierTokenId
Include the ID of the instrument identifier token you want to retrieve in the URL path.
processingInformation.authorizationOptions.
initiator.merchantInitiatedTransaction.previousTransactionId

processingInformation.authorizationOptions.
initiator.merchantInitiatedTransaction.originalAuthorizedAmount

processingInformation.authorizationOptions.
initiator.merchantInitiatedTransaction.processorTransactionId

Related Information

• API Field Reference for the REST API

Token Management Service | Network Tokens for Merchants | 292

REST Example: Updating MIT Authorization Options

Request

PATCH https://apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111

{
"processingInformation": {
"authorizationOptions": {
"initiator": {
"merchantInitiatedTransaction": {
"previousTransactionId": "123456789012345",
"originalAuthorizedAmount": "1",
"processorTransactionId": "123456789012345123"
}
}
}
}
}

Token Management Service | Network Tokens for Merchants | 293

Response to a Successful Request

{
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111"
},
"paymentInstruments": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts"
}
},
"id": "7010000000016241111",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"card": {
"number": "411111XXXXXX1111"
},
"processingInformation": {
"authorizationOptions": {
"initiator": {
"merchantInitiatedTransaction": {
"previousTransactionId": "123456789012345",
"originalAuthorizedAmount": "1",
"processorTransactionId": "123456789012345123"
}
}
}
},
"metadata": {
"creator": "testrest"
}
}

Token Management Service | Network Tokens for Merchants | 294

Network Tokens for Partners
Network tokens are network scheme generated tokens that represent customer card information
for secure transactions. Network tokens are mapped to instrument identifier tokens and can be
provisioned through Cybersource for partners.

Manage Network Tokens for Partners

This section contains information on managing network tokens for partners.

Network tokens are generated by the network scheme and represent customer card information for
secure transactions. Network schemes include but are not limited to Visa, Mastercard, and American
Express. Network tokens are mapped to instrument identifier tokens. The minimum card data
required to request a network token is the PAN and the expiration date.

You can provision network tokens for a card number or an existing instrument identifier. For
example:

• Provision a Network Token for a Card Number (on page 296)

• Provision a Network Token for an Existing Instrument Identifier (on page 299)

You can also retrieve a network tokens for existing payment credentials. For example:

• Retrieve a Network Token for Payment Credentials (on page 302)

For more information on network tokens, see Network Tokens (on page 22).

Token Management Service | Network Tokens for Partners | 295

Provision a Network Token for a Card Number
This section shows you how to provision a network token for a card number.

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

Required Fields for Provisioning a Network Token for a Card Number

Using the REST API
card.number

card.expirationMonth

card.expirationYear

type

Related Information

• API Field Reference for the REST API

Optional Fields for Provisioning a Network Token for a Card Number

Using the REST API
card.securityCode

Related Information

• API Field Reference for the REST API

Token Management Service | Network Tokens for Partners | 296

REST Example: Provisioning a Network Token for a Card Number

Request

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

{
"type": "enrollable card",
"card": {
"number": "4895379987X11515",
"expirationMonth": "12",
"expirationYear": "2031",
"securityCode": "089"
}
}

Token Management Service | Network Tokens for Partners | 297

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/paymentinstrumen
ts"
}
},
"id": "7030000000014911515",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"tokenizedCard": {
"state": "ACTIVE",
"number": "489537XXXXXX5914",
"expirationMonth": "12",
"expirationYear": "2022",
"type": "visa",
"card": {
"suffix": "1515",
"expirationMonth": "12",
"expirationYear": "2031"
}
},
"card": {
"number": "489537XXXXXX1515"
},
"issuer": {
"paymentAccountReference": "V0010013019326121174070050420"
},
"metadata": {
"creator": "testrest"
}
}

Token Management Service | Network Tokens for Partners | 298

Provision a Network Token for an Existing Instrument Identifier
This section shows you how to provision a network token for an existing instrument identifier.

Endpoint

Test: GET https://apitest.cybersource.com/tms/v1/instrumentidentifiers/

{instrumentIdentifierTokenId}/enrollment

Production: GET https://api.cybersource.com/tms/v1/instrumentidentifiers/

{instrumentIdentifierTokenId}/enrollment

Production in India: GET https://api.in.cybersource.com/tms/v1/instrumentidentifiers/

{instrumentIdentifierTokenId}/enrollment

instrumentIdentifierTokenId is the instrument identifier token ID returned in the id field when you
created the instrument identifier token. For more information, see Create an Instrument Identifier
(on page 235).

Required Fields for Provisioning a Network Token for an Existing

Instrument Identifier Using the REST API
card.expirationMonth

card.expirationYear

card.securityCode

instrumentIdentifierTokenId
Include the ID of the instrument identifier token you want to retrieve in the URL path.
type

Related Information

• API Field Reference for the REST API

Optional Fields for Provisioning a Network Token for an Existing

Instrument Identifier Using the REST API
card.securityCode

Token Management Service | Network Tokens for Partners | 299

Related information
API Field Reference for the REST API

REST Example: Provisioning a Network Token for an Existing

Instrument Identifier

Request

POST https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/enrollment

{
"type": "enrollable card",
"card": {
"expirationMonth": "12",
"expirationYear": "2031",
"securityCode": "089"
}
}

Token Management Service | Network Tokens for Partners | 300

Response to a Successful Request

{
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111"
},
"paymentInstruments": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111/paymentinstrumen
ts"
}
},
"id": "7010000000016241111",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"tokenizedCard": {
"state": "ACTIVE",
"type": "visa"
},
"card": {
"number": "411111XXXXXX1111"
},
"metadata": {
"creator": "testrest"
}
}

REST Interactive Example: Provisioning a Network Token for an

Existing Instrument Identifier
Live Console URL: https://developer.cybersource.com/api-reference-assets/index.html#token-
management_instrument-identifier_enroll-an-instrument-identifier-for-payment-network-token

Token Management Service | Network Tokens for Partners | 301

Retrieve a Network Token for Payment Credentials
This section shows you how to retrieve a network token for payment credentials.

Endpoint

Test: POST https://apitest.cybersource.com/tms/v2/tokens/{tokenId}/payment-credentials

Production: POST https://api.cybersource.com/tms/v2/tokens/{tokenId}/payment-credentials

Production in India: POST https://api.in.cybersource.com/tms/v2/tokens/{tokenId}/payment-

credentials

The {tokenId} is the token ID returned in the id field when you created the customer, payment
instrument or instrument identifier token. For more information, see Create an Instrument Identifier
(on page 235) for more information.

REST Example: Retrieving a Network Token for Payment Credentials

Request

POST https://apitest.cybersource.com/tms/v2/tokens/7040000000001853257/payment-credentials

Token Management Service | Network Tokens for Partners | 302

Successful Response: BASE 64

JraWQiOiI5OWY5YmVjOTlmMzQ1MDJmMDE2NWIyYmJhYWYyODAxNDNhOTI0OWNjIiwiY3R5IjoianNvbiIs
InR5cCI6IkpXVCIsImVuYyI6IkEyNTZHQ00iLCJhbGciOiJSU0EtT0FFUC0yNTYifQ.uYCE2zysWJB8E56
2FGJl4YyotZEHw4Az-2fvhjaUWubuAZ2tmZm44oKUdsfsBLYWInxpMDUsiENTTHG_UJJ25Snhcft6eZGj7
9gW_S55ZAGAi1eYIJA08gr01U7P-1QIzQ5t6dlkTRZElYDiNjypSaVfQPQPODaGNfB04Li7Pt88i-PIspG
afq9P7TgacPyKoIkvM5CwLWbwSZYN_jdFq8hEu4Dy7gqDpf0z-rCdtWggWpFbGwdurDrKCbLBoQ4dY7Ock
Joe2OOWH-O1h_7uZymDDUjnqWFRcHgjxY7bmWJz94i_r4QUaoTQiaaqgyP6A2H3Gmt6Dy4VpIzO2XgLQA.
_cLex9BPstYqqnfe.RMbdjAqWR6HaVZ7USbp6j-KWPC1jGc3Wzk4M_CwJ58X2NNZ5ekUpAvU28_MbqQ2W6
MLhJ7ulgfU5mk9_Y5nvAW6Yh68Ctye2yOhgu_V_33aLmz3iZP5AEGi7HeJVng0hy4EaQHNb92XYXUV1mvF
HJokA4cRaj3eKwh6v-1lRhB4uIgXU62ZanVGGu5c7UkVkf6JiigZarGJiY2DKCRjYnbQYkj4JNFY94JlS5
0wTnGrk3MiAJN9DYIU-6US98zWGJ8VhBwhMuXk1juqVBfifjJMFa_-vnJjGpq1ri2buZ7hMJG-x0PIYoHU
GSFeqNrcLUjJxI0o8lnXfhj7DtfYvNc0e4g5U39xtk-T2TDnQfdekRVxgdxcVR4mZdEqUHBxYUWTSW4Abg
V-fjuCGDCkUoPIgkZ95y4RJhSPZzjZHdulf2Fk3L7e-nto2PB25zUTt_aXeNBSH8zjmaI2ve6D3VN0Scdu
RMl_9PXv1876opHEGqgkKLSTXcTUasXKlzMEiUzLl3p5pN30KnVbryAzuU3hhmIMyyPpEQkp9h3WlD4sc5
oH1E8YtihLlSTtTUNwX5dJuR6iVwpKqFxECqYPtDWlzXQDTedFqdTA4isE3MCs.th9qWPzsevuDYp--06o
POw

Successful Response: Decrypted

{
"_links": {
"self": {
"href": "/tms/v2/tokens/7040000000001853257/payment-credentials"
}
},
"tokenizedCard": {
"state": "ACTIVE",
"number": "504240750347XX2",
"expirationMonth": "11",
"expirationYear": "2024",
"type": "mastercard",
"cryptogram": "AGMkrO22Drk4AAdiUWJoAAADFA==",
"requestorId": "50162233570",
"card": {
"suffix": "3257",
"expirationMonth": "09",
"expirationYear": "2023"
}
},
"card": {
"number": "520424XXXXXX3257"
},
"issuer": {

Token Management Service | Network Tokens for Partners | 303

 "paymentAccountReference": "500194XI39I8V2596QWVQSG0JQFSE"
}
}

For more information on decrypting data, see Encrypt and Decrypt Data (on page 320).

Token Management Service | Network Tokens for Partners | 304

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 id field when you
created the instrument identifier token. For more information, see Create an Instrument Identifier
(on page 235).

Token Management Service | Network Tokens for Partners | 305

REST Example: Retrieving an Instrument Identifier

Request

Pass the instrument identifier token ID in the URL path.

GET https://apitest.cybersource.com/tms/v1/instrumentidentifiers/7030000000046226486

Token Management Service | Network Tokens for Partners | 306

Response to a Successful Request

{
"_links": {
"self": {
"href":
https://apitest.visaacceptance.com/tms/v1/instrumentidentifiers/7030000000046226486
},
"paymentInstruments": {
"href":
https://
apitest.visaacceptance.com/tms/v1/instrumentidentifiers/7030000000046226486/paymentinstrum
ents
}
},
"id": "7030000000046226486",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"tokenizedCard": {
"state": "ACTIVE",
"enrollmentId": "80efd04a838265dcdf9d114eb542be01",
"tokenReferenceId": "003769ea947eb057c13c192f1d26f002",
"number": "489537XXXXXX2655",
"expirationMonth": "12",
"expirationYear": "2030",
"type": "visa",
"card": {
"suffix": "6486",
"expirationMonth": "12",
"expirationYear": "2030"
}
},
"card": {
"number": "489537XXXXXX6486"
},
"issuer": {
"paymentAccountReference": "V0010013020037567013722096631"
},
"metadata": {
"creator": "testacct"
}
}

Token Management Service | Network Tokens for Partners | 307

REST Interactive Example: Retrieving an Instrument Identifier
Live Console URL: https://developer.cybersource.com/api-reference-assets/index.html#token-
management_instrument-identifier_retrieve-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 id field in the

id field when you created the instrument identifier token. For more information, see Create an
Instrument Identifier (on page 235).

Required Fields for Deleting an Instrument Identifier Using the REST

API
instrumentIdentifierTokenId
Include the ID of the instrument identifier token you want to retrieve in the URL path.

Related Information

• API Field Reference for the REST API

Token Management Service | Network Tokens for Partners | 308

REST Example: Deleting an Instrument Identifier

Request

Pass the instrument identifier token ID in the URL path.

DELETE https://apitest.cybersource.com/tms/v1/instrumentidentifiers/7010000000016241111

Token Management Service | Network Tokens for Partners | 309

Response to a Successful Request
A successful delete response returns an empty HTTP 204 No Content status. For more information, see
HTTP Status Codes (on page 321).

REST Interactive Example: Deleting an Instrument Identifier

Live Console URL: https://developer.cybersource.com/api-reference-assets/index.html#token-
management_instrument-identifier_delete-an-instrument-identifier

Network Token Provision Failures

Token Management Service | Network Tokens for Partners | 310

Lost and Stolen Card Response

Network Token Provision Failure Reason Codes and Descriptions

Reason Code Description
INVALID_REQUEST The network token provision request contained invalid data.
CARD_VERIFICATION_FAI The network token provision request contained data that could not be
LED verified.
CARD_NOT_ELIGIBLE Card cannot be used currently with issuer for tokenization.
CARD_NOT_ALLOWED Card cannot be used currently with card association for tokenization.
DECLINED Card cannot be used currently with issuer for tokenization.
SERVICE_UNAVAILABLE The network token service was unavailable or timed out.
SYSTEM_ERROR An unexpected error occurred with network token service, check
configuration.

{
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7030000000041554452"
},
"paymentInstruments": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7030000000041554452/paymentinstrumen
ts"
}
},
"id": "7030000000041554452",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"tokenizedCard": {
"state": "UNPROVISIONED",
"reason": "CARD_NOT_ELIGIBLE",
"type": "visa"
},
"card": {
"number": "400555XXXXXX4452"
},
"metadata": {
"creator": "testrest"
}
}

Token Management Service | Network Tokens for Partners | 311

Issuer Decline Response

{
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7030000000051790079"
},
"paymentInstruments": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7030000000051790079/paymentinstrumen
ts"
}
},
"id": "7030000000051790079",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"tokenizedCard": {
"state": "UNPROVISIONED",
"reason": "CARD_NOT_ALLOWED",
"type": "visa"
},
"card": {
"number": "462294XXXXXX0079"
},
"metadata": {
"creator": "testrest"
}
}

Token Management Service | Network Tokens for Partners | 312

Past Expiration Date Response

{
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7030000000224170019"
},
"paymentInstruments": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7030000000224170019/paymentinstrumen
ts"
}
},
"id": "7030000000224170019",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"tokenizedCard": {
"state": "UNPROVISIONED",
"reason": "CARD_NOT_ALLOWED",
"type": "visa"
},
"card": {
"number": "476134XXXXXX0019"
},
"metadata": {
"creator": "testrest"
}
}

Token Management Service | Network Tokens for Partners | 313

Issuer Not Participating Response

{
"_links": {
"self": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7030000000224170019"
},
"paymentInstruments": {

"href": "https://
apitest.cybersource.com/tms/v1/instrumentidentifiers/7030000000224170019/paymentinstrumen
ts"
}
},
"id": "7030000000224170019",
"object": "instrumentIdentifier",
"state": "ACTIVE",
"tokenizedCard": {
"state": "UNPROVISIONED",
"reason": "CARD_NOT_ALLOWED",
"type": "visa"
},
"card": {
"number": "476134XXXXXX0019"
},
"metadata": {
"creator": "testrest"
}
}

Token Management Service | Network Tokens for Partners | 314

Using Token Management Service with Wallet Apps
Use the TMS API features to create an e-wallet app for your customers.

Manage Tokens with Wallet Apps

This section contains information for on managing tokens using wallet apps.

Use the Token Management Service (TMS) API features to create an e-wallet app for your customers.
You can use your e-wallet to create, update, patch, and delete payment methods. Use the TMS API to:

• Create a New Customer Account (on page 315)

• Add a New Shipping Address (on page 316)

• Create a New Payment Instrument with the Payments API (on page 316)

• Add a New Payment Method Address (on page 318)

• Edit or Delete a Shipping Address (on page 316)

• Edit or Delete a Payment Method (on page 317)

• Change the Default Payment Method (on page 317)

• View Wallet (on page 318)

Create a New Customer Account

Use the TMS API in your e-wallet app when creating a new customer account to store customer
information securely.

1. Call the POST /tms/v2/customers endpoint to create a new customer in the e-wallet app
customer sign-up flow.

2. The request returns the customer token. Store the customer token with the customer profile
information in your database.

Token Management Service | Using Token Management Service with Wallet Apps | 315
Add a New Shipping Address
Use the TMS API in your e-wallet app to store a customer's new shipping address.

1. When you collect the new customer's shipping address, use the customer token from the
Create a New Customer Account (on page 315) step to create a shipping address for that
customer.

2. Call POST /tms/v2/customers/{customerTokenId}/shipping-addresses.

Edit or Delete a Shipping Address

Use the TMS API in your e-wallet app to edit or delete a customer's shipping address.

1. To get all addresses, call: GET /tms/v2/customers/{customerTokenId}/shipping-address.

The first record is the default.

2. To add an address, call: POST /tms/v2/customers/{customerTokenId}/shipping-addresses.

This adds a non-default shipping address. If it is the customer's first address, it becomes the
default address.

3. To edit an address, call: PATCH /tms/v2/customers/{customerTokenId}/shipping-addresses/

{shippingAddressTokenId}.

4. To delete an address, call: DELETE /tms/v2/customers/{customerTokenId}/shipping-addresses/

{shippingAddressTokenId}.

5. To set an address as the default address, call: PATCH /tms/

v2/customers/{customerTokenId}/shipping-addresses/{shippingAddressTokenId} and set the
value of the request field default to true.

Create a New Payment Instrument with the Payments API

Use the payments API in your e-wallet app to store the customer's payment method information in a
payment instrument.

Token Management Service | Using Token Management Service with Wallet Apps | 316
 1. Use the payment instrument you created in the call from the Add a Default Payment Instrument
with Validated Payment (on page 148) step to create a new payment method.

2. Call: POST /pts/v2/payments and pass the instrument identifier token, card type, and expiration
date in the request.
If this is the first payment method, it becomes the customer's default.

3. Store the card expiration date and last 4 digits with the customer profile information in your
database.

Edit or Delete a Payment Method

Use the TMS API in your e-wallet app to retrieve a customer's payment method and allow the
customer to delete or edit the payment method.

1. To retrieve the customer's default payment method, call: GET /tms/

v2/customers/{customerTokenId}/payment-instruments.
The first record is the default payment method. The remaining payment methods are the non-
default payment methods.

2. To delete a payment method, call: DELETE /tms/v2/customers/{customerTokenId}/payment-

instruments/{paymentInstrumentTokenId}

3. To edit a payment method, call: PATCH /tms/v2/customers/{customerTokenId}/payment-

instruments/{paymentInstrumentTokenId}

4. Include the updated payment method details in the call.

Change the Default Payment Method

Use the TMS API in your e-wallet app to change the customer's default payment method.

1. To get all payment methods, call: GET /tms/v2/customers/{customerTokenId}/payment-

instruments.
The first result is the default payment instrument. The remaining payment methods are the
non-default payment methods.

2. To make a non-default payment method the default, call: PATCH /tms/

v2/customers/{customerTokenId}/payment-instruments/{paymentInstrumentTokenId} and set the
value of the request field default to true.

Token Management Service | Using Token Management Service with Wallet Apps | 317
Add a New Payment Method Address
Use the TMS API in your e-wallet app to list the customer's addresses or add a new address for a
payment method.

1. To list the customer's existing billing addresses, call: GET /tms/

v2/customers/{customerTokenId}/payment-instruments.
The call returns all of the payment methods for a customer, including their billing address
details.

2. To list the customer's existing shipping addresses, call: GET /tms/

v2/customers/{customerTokenId}/payment-instruments.
This call returns all the shipping address details for a customer.

3. To add a new address, call: POST /tms/v2/customers/{customerTokenId}/shipping-addresses.

4. To add an address to the payment method created in Create a New Payment Instrument with
the Payments API (on page 316), call: PATCH /tms/v2/customers/{customerTokenId}/payment-
instruments/{paymentInstrumentTokenId}.

5. Pass the ID of the instrument identifier created in Create a New Payment Instrument with the
Payments API (on page 316) and the card expiration date.

View Wallet
Use the TMS API in your e-wallet app to view wallet.

1. Call GET /tms/v2/customers/{customerTokenId}/payment-instruments.

The first record is the default payment instrument.

2. Retrieve the last four digits of the card number from your database or call the payment
identifier endpoint.

Payments with Tokens and Wallet Apps

This section contains information for on making payments with tokens using wallet apps.

Use the TMS API features to create an e-wallet app for your customers. You can use your e-wallet to
authorize a payment. For example:

• Authorize a Payment (on page 319)

Token Management Service | Using Token Management Service with Wallet Apps | 318
Authorize a Payment
Use the TMS API in your e-wallet app to authorize a payment.

1. To get the customer’s default shipping address, call: GET /tms/

v2/customers/{customerTokenId}/shipping-address.
The first record is the default.

2. To retrieve the customer's default payment method, call: GET /tms/

v2/customers/{customerTokenId}/payment-instruments.
The first record is the default.

3. Finally, when the customer clicks the Place Order button, call: POST /pts/v2/payments pass the
customer token, payment instrument token, and shipping address token.

Token Management Service | Using Token Management Service with Wallet Apps | 319
Reference Information

Encrypt and Decrypt Data

1. Send a POST request to token cryptogram resource at /tms/v2/tokens/
instrumentIdentifierTokenId/payment-credentials. The response is BASE 64 encoded text. For
example:

JraWQiOiI5OWY5YmVjOTlmMzQ1MDJmMDE2NWIyYmJhYWYyODAxNDNhOTI0OWNjIiwiY3R5IjoianN
vbiIsInR5cCI6IkpXVCIsImVuYyI6IkEyNTZHQ00iLCJhbGciOiJSU0EtT0FFUC0yNTYifQ.uYCE2
zysWJB8E562FGJl4YyotZEHw4Az-2fvhjaUWubuAZ2tmZm44oKUdsfsBLYWInxpMDUsiENTTHG_UJ
J25Snhcft6eZGj79gW_S55ZAGAi1eYIJA08gr01U7P-1QIzQ5t6dlkTRZElYDiNjypSaVfQPQPODa
GNfB04Li7Pt88i-PIspGafq9P7TgacPyKoIkvM5CwLWbwSZYN_jdFq8hEu4Dy7gqDpf0z-rCdtWgg
WpFbGwdurDrKCbLBoQ4dY7OckJoe2OOWH-O1h_7uZymDDUjnqWFRcHgjxY7bmWJz94i_r4QUaoTQi
aaqgyP6A2H3Gmt6Dy4VpIzO2XgLQA._cLex9BPstYqqnfe.RMbdjAqWR6HaVZ7USbp6j-KWPC1jGc
3Wzk4M_CwJ58X2NNZ5ekUpAvU28_MbqQ2W6MLhJ7ulgfU5mk9_Y5nvAW6Yh68Ctye2yOhgu_V_33a
Lmz3iZP5AEGi7HeJVng0hy4EaQHNb92XYXUV1mvFHJokA4cRaj3eKwh6v-1lRhB4uIgXU62ZanVGG
u5c7UkVkf6JiigZarGJiY2DKCRjYnbQYkj4JNFY94JlS50wTnGrk3MiAJN9DYIU-6US98zWGJ8VhB
whMuXk1juqVBfifjJMFa_-vnJjGpq1ri2buZ7hMJG-x0PIYoHUGSFeqNrcLUjJxI0o8lnXfhj7Dtf
YvNc0e4g5U39xtk-T2TDnQfdekRVxgdxcVR4mZdEqUHBxYUWTSW4AbgV-fjuCGDCkUoPIgkZ95y4R
JhSPZzjZHdulf2Fk3L7e-nto2PB25zUTt_aXeNBSH8zjmaI2ve6D3VN0ScduRMl_9PXv1876opHEG
qgkKLSTXcTUasXKlzMEiUzLl3p5pN30KnVbryAzuU3hhmIMyyPpEQkp9h3WlD4sc5oH1E8YtihLlS
TtTUNwX5dJuR6iVwpKqFxECqYPtDWlzXQDTedFqdTA4isE3MCs.th9qWPzsevuDYp--06oPOw

2. Decode the BASE 64 encoded response. The response is a decoded JWE response with an
encrypted payload. For example:

{
"kid": "99f9bec99f34502f0165b2bbaaf280143a9249",
"cty": "json",
"typ": "JWT",
"enc": "A256GCM",
"alg": "RSA-OAEP-256"
}
<Encrypted payload>

3. Decrypt the JWE encrypted payload. The response is the decrypted payload. For example:

{
"_links": {
"self": {

Token Management Service | Reference Information | 320

 "href": "/tms/v2/tokens/A560EECDED74936DE0533F36CF0ACEBC/payment-credentials"
}
},
"tokenizedCard": {
"state": "ACTIVE",
"number": "4X24XX7118382281",
"expirationMonth": "11",
"expirationYear": "2022",
"type": "visa",
"cryptogram": "AF1ajnoLKKj8AAKhssPUGgADFA\u003d\u003d",
"requestorId": "ABCD",
"card": {
"suffix": "2382",
"expirationMonth": "12",
"expirationYear": "2018"
}
},
"card": {
"number": "402400XXXXXX2382"
},
"issuer": {
"paymentAccountReference": "V0000000000005109162731718000"
}
}

HTTP Status Codes

A request response returns one of the following HTTP status codes:

• 200: The standard response for a successful HTTP request. In a GET request, the response
will contain an empty entity corresponding to the requested resource. In a POST request, the
response will contain an entity describing or containing the result of the action.

• 201: The request was fulfilled and resulted in a new resource being created. If you get this HTTP
status code for an unsuccessful transaction, Cybersource or the merchant's processor probably
marked this transaction as under review, declined, or failed.

• 204: The server fulfilled the request but does not need to return a body.

• 403: Forbidden Response: The profile might not have permission to perform the operation.

• 404: Token Not Found. The token ID may not exist or was entered incorrectly.

• 409: Conflict. The token is linked to a Payment Instrument.

Token Management Service | Reference Information | 321

• 410: Token not available The token has been deleted.

• 424: Failed Dependency: The profile represented by the profile ID may not exist or the profile ID
was entered incorrectly.

• 500: Unexpected error.

Token Management Service | Reference Information | 322

Supported Processors
The processors listed below support customer and instrument identifier tokens, unless noted
otherwise.

Processor Payment Method

Visa Platform
Connect • Credit card—supports 0.00 pre-authorizations for Visa and Mastercard
cards.

• Credit card—supports 1.00 pre-authorizations for American Express,

Discover, Diners Club, and JCB card types.

• Debit card and prepaid card.

• Payouts.

Token Management Service | Supported Processors | 323