How Token Processing Works

This page describes what happens when a cardholder pays with a token that has already been provisioned.

📘

Read this one first if you are scoping the work. Token payments do not require a new integration. They arrive on the authorization interface you already handle. If you are estimating effort, this page is the one that tells you where the effort is not.

The path

%%{init: {"sequence": {"actorMargin": 8, "boxMargin": 6, "noteMargin": 6, "messageMargin": 26, "width": 110, "diagramMarginX": 8, "diagramMarginY": 8}}}%%
sequenceDiagram
    autonumber
    participant CH as Cardholder
    participant M as Merchant
    participant ACQ as Acquirer
    participant MC as Mastercard
    participant UDT as UnDosTres
    participant P as You

    CH->>M: Taps the device, or pays online
    M->>ACQ: Auth request with the token
    ACQ->>MC: Forwards the token
    MC->>MC: Maps token to PAN
    MC->>UDT: Auth request, PAN and token
    UDT->>P: Deduct, existing interface
    P-->>UDT: Approve or decline
    UDT-->>MC: Authorization response
    MC-->>ACQ: PAN swapped back to token
    ACQ-->>M: Approved or declined

Step by step:

1. The cardholder initiates the transaction, at an NFC terminal, in an app, or on an e-commerce site.
2. The merchant submits an authorization request to its acquirer carrying the token in place of the PAN.
3. The acquirer passes the token to the card network.
4. The network maps the token to the original PAN and verifies the token is being used by the party entitled to use it. It then sends both the PAN and the token to UnDosTres for authorization.
5. UnDosTres authorizes or declines, following the same rules as any other transaction on the card.
6. UnDosTres sends the authorization response back to the network.
7. The network substitutes the PAN back with the token and responds to the acquirer.
8. The merchant and acquirer settle the transaction.

What reaches you

A tokenized transaction reaches you as an ordinary Deduct. The card is identified the way it always is. The token-specific data travels in the KLV payload, so if you want to distinguish a wallet transaction from a physical card tap you can, but you are not required to.

Practically, this means:

• No new endpoint for token payments.
• No change to your authorization logic, balance checks or limits.
• Your existing decline reasons apply unchanged.
• If you report on transactions, you may want to surface which wallet was used. See KLV Lookup for the fields.

One thing worth checking

If your authorization logic branches on anything derived from the physical card, for example a rule that treats a card-present transaction differently from card-not-present, review it before launch. A token transaction from a phone at a terminal is card-present, and a token transaction from a card-on-file token is not. The behaviour is correct by default, but a custom rule written before tokenization existed may not have anticipated it.

Related

• Token Payments on Devices — what the device is doing
• Provisioning Overview — how the token got there
• Response Codes