Mass Transit Token Management Services
Use the
Token Management Service
to create, retrieve, and delete tokens for mass
transit.
Creating a Token
You can create tokens directly from the validator or through your back office system.
When the customer taps their card, the validator generates a unique transaction identifier that is used to create these tokens:
-
Transient token: tokenized EMV tag data and track2 data. Used as the transaction ID to create the instrument identifier and payment instrument tokens, and as the payment token for the final authorization and sale transactions. You can delete this token after a success transit payment for the travel period.Cybersourcestores this token for 7 days.
-
Instrument identifier: tokenized card number, used for follow-on payment transactions and BIN lookup.
-
Payment instrument: stores the card hash that is used to identify the payment card in the deny list.
Refer to
Cybersource
documentation regarding card-present data encryption and BDK provisioning.
This diagram shows the process for creating a token.
Figure:
Creating a Token
The token creation process begins when the when the cardholder taps a payment card at the fare collection terminal.
-
The cardholder taps their card.
-
Regular local transit processing occurs. See Mass Transit Transaction Workflows.
-
The validator encrypts the card data and creates the card hash value.
-
Your system uses the card hash value to create the tokens.
-
You receive the tokens in the response message.
Endpoint
Test:
POST
https://apitest.cybersource.com
/tms/v2/taps
Production:
POST
https://api.cybersource.com
/tms/v2/taps
Retrieving Transient Token Details
Use the token retrieval service to get the transient token details such as the instrument identifier token and payment instrument token. Use the payment instrument token for token management. Use the instrument identifier for these transactions:
-
Merchant-initiated debt recovery
-
Stand-alone credit
Endpoint
Test:
POST
https://apitest.cybersource.com
/tms/v2/taps/{id}
Production:
POST
https://api.cybersource.com
/tms/v2/taps/{id}
Retrieving an Instrument Identifier Details
You can retrieve instrument identifier details.
Endpoint
Test:
GET
https://apitest.cybersource.com
/tms/v1/instrumentidentifiers/{id}
Production:
GET
https://api.cybersource.com
/tms/v1/instrumentidentifiers/{id}
The
id
is the instrument identifier ID that was returned in a token management service response.
}, "tokenInformation": { "instrumentIdentifier": { "id": "CD616772D8355EA6E053AF598E0AE794" },
Retrieving Card Hash Details
You can use the card hash to retrieve the details, which include the instrument identifier token and payment instrument token.
Endpoint
Test:
GET
https://apitest.cybersource.com
/tms/v1/paymentinstruments/{id}
Production:
GET
https://api.cybersource.com
/tms/v1/paymentinstruments/{id}
The
id
is the transient token identifier assigned by the contactless terminal.
Retrieving Payment Instrument Details
Send a
GET
request to retrieve payment instrument details, which include the card details, card hash, and instrument identifier.
Endpoint
Test:
GET
https://apitest.cybersource.com
/tms/v1/paymentinstruments/{id}
Production:
GET
https://api.cybersource.com
/tms/v1/paymentinstruments/{id}
The
id
is the transient token identifier assigned by the contactless terminal.
Deleting an Instrument Identifier
Send a
DELETE
request to delete an instrument identifier.
Endpoint
Test:
DELETE
https://apitest.cybersource.com
/tms/v1/instrumentidentifiers/{id}
Production:
DELETE
https://api.cybersource.com
/tms/v1/instrumentidentifiers/{id}
The
id
is the instrument identifier ID that was returned in a token management service response.
}, "tokenInformation": { "instrumentIdentifier": { "id": "CD616772D8355EA6E053AF598E0AE794" },
Deleting a Card Hash
Send a
DELETE
request to delete a card hash.
Endpoint
Test:
DELETE
https://apitest.cybersource.com
/tms/v1/paymentinstruments/{id}
Production:
DELETE
https://api.cybersource.com
/tms/v1/paymentinstruments/{id}
The
id
is the
card.hash
value that was returned in the retrieve a payment instrument response.
"card": { "expirationMonth": "12", "expirationYear": "2030", "type": "visa", "hash": "7400A4154369E584BA36CA19B50AAA3F9AE97FE93CF8FBC97777" }