Skip to main content

Tokenization guide

What is tokenization?​

Tokenization is the process of replacing sensitive information in a transaction (such as a credit card PAN) with a string of random characters, also known as a token.

How does it work?​

The UP Gateway generates a token for a transaction when requested. The sensitive data is stored in the UP Gateway, and the token is returned to the merchant for future use. These tokens can then be used exclusively for e-commerce transactions or tokenized payments.

Tokenization protects the customer's account by using the token instead of sensitive data during the transaction, which the merchant never sees or stores.

Tokenized payments involve substituting sensitive data with a token. Since the sensitive data isn’t transmitted during the transaction, even if a data breach occurs and payment tokens are accessed, the likelihood of the token being used for fraudulent activity is very low.

When to Use Tokenization​

Tokenization is ideal for businesses that rely on a subscription-based model or repeat customers. It allows customer transactions to be as smooth as possible. Tokens can be securely stored and used for one-click/zero-click payments, making online payments effortless and secure.

Advantages of Tokenization​

  • PCI DSS Compliance

    By minimizing the storage and processing of sensitive payment data, tokenization helps businesses adhere to industry standards like the Payment Card Industry Data Security Standard (PCI DSS). PCI compliance is essential for maintaining customer trust and avoiding penalties.

  • Data Protection and Security

    Tokenization significantly improves payment security by replacing sensitive data with randomly generated tokens, protecting both merchants and customers from data breaches.

  • Reduction in Fraud and Chargebacks

    Even if a token is stolen, it cannot be used to make a payment, as the sensitive information is securely stored by the UP Gateway. This leads to more predictable transaction flows.

  • Effortless Payments

    Tokenization enables merchants to save payment data through tokens, allowing customers to make future purchases without re-entering their details. This facilitates one-click and zero-click payments, increasing conversion at checkout.

Supported payment methods​

Currently, the UP Gateway only supports card tokenization.

Payment methodCard tokenization
Visa✅
Mastercard✅
Maestro✅
Troy✅

Creating a token during a payment​

To request the tokenization of the account in a transaction, the tokenization block must be included as part of the request for the supported payment method.

As a result, the UP Gateway will include a token block in the response with the token identifier assigned to the tokenized account.

Please note that it is also necessary to include the credentialOnFile field, indicating whether the token is being stored for the first time or has been stored previously. Check the credential on file reference for more information.

Example of tokenization request for a visa transaction​

  • Request
{
    "processingAccountId": "2HdN2jq6XWmlkhqRC2gDTNYCvNH",
    "merchantReference": "B2A8734D-9450-4915-A63D-FE5C21F09550",
    "amount": {
        "value": 200,
        "currency": "hkd"
    },
    "paymentMethod": {
        "type": "visa",
        "visa": {
            "account": {
                "number": "4000000000000002",
                "expiryMonth": "1",
                "expiryYear": "2030",
                "cvv": "333"
            },
            "credentialOnFile":"initial_storage",
            "tokenization":{
                "type":"card"
            }
        }
    }
}
  • Response
{
    "id": "2DCstfsS93GWIPhkv5che8rvAQe",
    "merchantReference": "B2A8734D-9450-4915-A63D-FE5C21F09550",
    "status": "succeeded",
    "paymentMethod": {
        "type": "visa",
        "scheme": {
            "approvalCode": "707595",
            "cvvResult": "M"
        },
        "token":{
            "id":"2kv0Qq1kGFJ4EjFXSBFyrwYRvbp"
        }
    }
}

Example of tokenization request for a visa recurring transaction​

  • Request
{
    "processingAccountId": "2HdN2jq6XWmlkhqRC2gDTNYCvNH",
    "merchantReference": "B2A8734D-9450-4915-A63D-FE5C21F09550",
    "amount": {
        "value": 200,
        "currency": "hkd"
    },
   "paymentMethod": {
        "type": "visa",
        "visa": {
            "account": {
                "number": "4000000000000002",
                "expiryMonth": 1,
                "expiryYear": 2030,
                "cvv": "333"
            },
             "tokenization":{
                "type":"card"
            },
            "credentialOnFile": "initial_storage",
            "standingInstruction": {
                "type": "recurring",
                "mode": "initial"
            }
        }
    }
}
  • Response
{
    "id": "2kv0Qv0SCQNznU8K2la1CY5xDxM",
    "merchantReference": "B2A8734D-9450-4915-A63D-FE5C21F09550",
    "status": "succeeded",
    "paymentMethod": {
        "type": "visa",
        "scheme": {
            "approvalCode": "707595",
            "cvvResult": "M",
            "transactionId": "358501774473752"
        },
        "token":{
            "id":"2kv0Qq1kGFJ4EjFXSBFyrwYRvbp"
        }
    }
}

Use a token​

Once the token is created, it can be used in later transactions. To use a token, the request must include the accountToken block, which replaces the account block used in non-tokenized transactions.

Please note that in most scenarios, it is also necessary to include the credentialOnFile field with the value stored. Check the credential on file reference for more information.

Example of tokenized visa one-click payment request​

  • Request
{
    "processingAccountId": "2HdN2jq6XWmlkhqRC2gDTNYCvNH",
    "merchantReference": "B2A8734D-9450-4915-A63D-FE5C21F09550",
    "amount": {
        "value": 200,
        "currency": "hkd"
    },
    "paymentMethod": {
        "type": "visa",
        "visa": {
            "accountToken": {
                "id": "2kv0Qq1kGFJ4EjFXSBFyrwYRvbp"
            },
            "credentialOnFile":"stored"
        }
    }
}
  • Response
{
    "id": "2kv1Qv0SCQNznU8K2la4CY5xDcD",
    "merchantReference": "B2A8734D-9450-4915-A63D-FE5C21F09550",
    "status": "succeeded",
    "paymentMethod": {
        "type": "visa",
        "scheme": {
            "approvalCode": "707595",
            "cvvResult": "M",
            "transactionId": "358501774473752"
        }
    }
}

Example of tokenized visa subsequent recurring payment request​

  • Request
{
    "processingAccountId": "2HdN2jq6XWmlkhqRC2gDTNYCvNH",
    "merchantReference": "B2A8734D-9450-4915-A63D-FE5C21F09550",
    "amount": {
        "value": 200,
        "currency": "hkd"
    },
    "paymentMethod": {
        "type": "visa",
        "visa": {
            "accountToken": {
                "id": "2kv0Qq1kGFJ4EjFXSBFyrwYRvbp"
            },
            "credentialOnFile":"stored",
            "schemeTransactionId": "358501774473752",
            "standingInstruction": {
                "type": "recurring",
                "mode": "subsequent"
            }
        }
    }
}
  • Response
{
    "id": "2kD1Qv0SCJPknU8K2la4CY5xAbC",
    "merchantReference": "B2A8734D-9450-4915-A63D-FE5C21F09550",
    "status": "succeeded",
    "paymentMethod": {
        "type": "visa",
        "scheme": {
            "approvalCode": "707595",
            "cvvResult": "M",
            "transactionId": "358501774473752"
        }
    }
}

Webhooks​

When a token is created, it will also be present in the corresponding transaction webhook. Check the webhooks reference for more information.

Example of webhook for a transaction that requested tokenization for visa​

{
  "id": "27yiudbcBY6FfBFpRIO6zVwLG4C",
  "live": true,
  "type": "payment",
  "version": "v1",
  "createTime": "2022-02-14T09:52:23.123Z",
  "payload": {
    "id": "27yiuHx86Rpmm7reQvfKmqGljAF",
    "merchantReference": "B2A8734D-9450-4915-A63D-FE5C21F09550",
    "merchant": {
      "processingAccountId": "2IDbro4HqWGkjjBceyaPDbkS2dn"
    },
    "status": "succeeded",
    "amount": {
      "value": 2.32,
      "currency": "eur"
    },
    "paymentMethod": {
        "type": "visa",
        "scheme": {
            "approvalCode": "707595",
            "cvvResult": "M",
        },
        "token":{
            "id":"2kv0Qq1kGFJ4EjFXSBFyrwYRvbp"
        }
    }
  }
}

Retrieve payments​

The token information will also be available in the Retrieve Payments API. If a token was created or used during a transaction, it will be present in the returned response, indicating the token identifier and the token type.

Example of visa tokenized payment retrieved​

{
    "id": "2kxitQX1rzYQkywxtVnkm0BjUz4",
    "merchantReference": "d7d0fa34-fc75-4ada-b9a9-d05bff6e044d",
    "type": "payment",
    "status": "captured",
    "createTime": "2024-08-21T09:17:22.948Z",
    "updateTime": "2024-08-21T09:17:29.265Z",
    "version": 1,
    "merchant": {
        "storeId": "LID-0000000001",
        "storeName": "merchant",
        "processingAccountId": "2IDbro4HqWGkjjBceyaPDbkS2dn",
        "entityId": "EID-10000000001"
    },
    "amount": {
        "authorized": 200.0,
        "captured": 200.0,
        "currency": "eur"
    },
    "paymentMethod": {
        "type": "visa",
        "account": {
            "number": "400000******0002"
        },
        "capture": "auto",
        "authorizationType": "final",
        "initiatedBy": "consumer",
        "credentialOnFile": "stored",
        "source": "ecommerce",
        "retrievalReferenceNumber": "423409793083",
        "scheme": {
            "approvalCode": "EFC6D6",
            "transactionId": "361855211188097"
        },
        "token": {
            "id": "2ijkHvZvn8GTvHi9s8pRTyr3jXp",
            "type": "card"
        }
    },
    "events": [
        {
            "type": "payment",
            "createTime": "2024-08-21T09:17:22.9482421Z",
            "id": "2kxitQX1rzYQkywxtVnkm0BjUz4",
            "merchantReference": "d7d0fa34-fc75-4ada-b9a9-d05bff6e044d",
            "status": "succeeded",
            "amount": {
                "value": 200.0,
                "currency": "eur"
            }
        }
    ]
}

Retention policy​

Each token created will have a retention period of 15 months. After this period, if the token has not been used, it will be deleted. However, each time the token is used, its retention period is reset to 15 months again.