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.
    Cybersource
    stores 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.
  1. The cardholder taps their card.
  2. Regular local transit processing occurs. See Mass Transit Transaction Workflows.
  3. The validator encrypts the card data and creates the card hash value.
  4. Your system uses the card hash value to create the tokens.
  5. 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"
     }