Cybersource Instrument Identifier vs Payment Instrument tokens

Question

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

Reference: https://developer.cybersource.com/api-reference-assets/index.html#token-management

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

Answer 1

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.

Answer 2

Cybersource is never good at API design or documentation. but their document on this topic could help you understand the concept https://developer.cybersource.com/api/developer-guides/dita-tms/paymentInstrumentREST.html

Look at the first chart.

A "customer" has a "payment instrument" which associates with a "card", which could have multiple instrument identifiers that each has one-on-one mapping with a specific card number.

This model exists because consumer can have the SAME card updated with different card numbers OR expire date. ("Payment Instrument" tries to represent the "SAMEness" part of it.)

So Cybersource's "Payment Instrument" model can be seen as an "abstract" card object/container representing the working "instrument" (that is why it doesn't store the number) which knows the actual card number that should be used (but the merchant doesn't necessary need to know), in the mean time, it knows the "history" of the card.

The naming is terrible, the "Payment Instrument" itself has an ID, then Instrument Identifier ID is an "ID" too (guess the guy who came up with the name forgot ID is the acronym for "Identifier"? LOL). Very confusing indeed. Just keep in mind that Instrument Identifier ID maps to a card number, "Payment Instrument" ID is a container that maps to a series of (SAME) card numbers (potentially)

So that answers your question why you can get a different "Payment Instrument" ID every time, because you can think of it as different merchant has a different "Payment Instrument" ID for the same customer with that physical card. As long as Cybersource has the record and knows how to find the associated instrument identifier ID via this "Payment Instrument ID", it is mission accomplished.

Again you know Cybersource is a dinosaur living in the past, so you have to deal with it