Showing results for 
Search instead for 
Did you mean: 

Cybersource Instrument Identifier vs Payment Instrument tokens

I'm currently looking into Cybersource's REST API for the tokenization of cards.


However, I'm having some trouble wrapping my head around the following and could use some advice from those who have already worked with Cybersource and are more familiar with the terminology.

Under Token Management, there's an Instrument Identifier and Payment Instrument. Instrument Identifier seems to return the same unique ID for the same card and is part of the overall Payment Instrument token.

If I POST (create) a Payment Instrument token, inside the response, I see that as well, where an Instrument Identifier is returned and giving me back the same id as long as the card is the same. However, the Payment Instrument always returns a new token.

Question: I'm trying to think of Payment Instrument as a payment method, tokenizing a card, and not per payment, but since it returns a different token each time even if I put in the same credit card, am I understanding this wrong? Should I treat the Payment Instrument as something else completely different? If I were to store a token on our side, which one would I be?
As for payments API, we can pass in a token, does this work for both types mentioned above?

Any help, guidance or thoughts are appreciated


In the response, where an Instrument Identifier is returned and gives me the same ID as long as the card is the same, I can also see that if I POST (create) a Payment Instrument token. The Payment Instrument, however, always returns a fresh token.


Cybersource is never good at API design or documentation. but their document on this topic could help you understand the concept /omeglz echat

So my understanding of how this works, is that a payment instrument is a TYPE of payment (ACH, CreditCard, bitcoin, ApplePay™, GooglePay™, etc.) then the instrument identifier is the token (or id) that represents the specific account number within that payment type.

So a payment instrument of Credit Card might have an instrument identifier of Visa account 4242424242424242 but the Token Management Service (TMS) returns an instrument identifier of AA7D990C34583376EB05345443E0234242434B. The TMS allows for relevant information to then be stored within a CUSTOMER identifier (which is the "wallet" owner). As the TMS becomes more feature rich, the addition of things like 'shipping info' and other possible 'preferences' may become available. The other concept is that this digital wallet (TMS token API) can have its permissions granted to other merchant entities so that all payment processing and transactions can be managed through one (OMNICHANEL) API and this payment information can remain SECURE, AUDITABLE, GRANTED, REVOKED, etc.

Now the reason you can get different "tokens" for the same instrument is based on preference. This means that if a cardholder doesn't want to 'keep payment info on file' or 'store the token for later use'. Then the TMS system will provide a token for one-time use, thereby satisfying the requirement of the merchant (reducing PCI scope/risks) and keeping the preference of the cardholder.

This is in no way an official explanation, so I am definitely open to any additional insights on how TMS (from Cybersource™) is designed to work.