Tokenization

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 method	Card tokenization
Visa	✅
Mastercard	✅
Maestro	✅
Troy	✅

Creating a token

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 account is being stored for the first time or has been stored previously. Check the credential on file section 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"
        }
    }
}

Creating a token using tokenization

To request the tokenization of an account, the tokenization endpoint can be used. This endpoint enables the creation of a token without requiring a transaction to be processed.

As a result, the uP Gateway will return a token identifier that can be used in future operations.

Example of tokenization request for a card

• Request to tokens

{
    "type": "card",
    "card": {
        "account": {
            "number": "5555555555554444",
            "expiryMonth": 1,
            "expiryYear": 2030
        }
    }
}

• Response

{
    "id": "2kv0Qq1kGFJ4EjFXSBFyrwYRvbp",
    "status": "active",
    "createTime": "2024-10-17T09:52:23.123Z",
    "updateTime": "2024-10-17T09:52:23.123Z",
    "type": "card",
    "card": {
        "account": {
            "firstDigits": 555555,
            "lastDigits": 4444,
            "length": 16,
            "expiryMonth": 1,
            "expiryYear": 2030
        }
    }
}

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 these scenarios it is also necessary to include the credentialOnFile field with the value stored. Check the credential on file section 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

Webhooks during a payment

When a token is created during a payment, a token block with the token identifier will be present in the corresponding payment webhook notification. Also, a token webhook notification is generated in relation to the created token besides the payment webhook notification.

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"
            }
        }
    }
}

Example of webhook for the token created with the previous transaction

{
    "id": "27yiudbcBY6FfBFpRIO6zVwLG5D",
    "live": true,
    "type": "token",
    "version": "v1",
    "createTime": "2022-02-14T09:52:23.123Z",
    "payload": {
        "id": "2kv0Qq1kGFJ4EjFXSBFyrwYRvbp",
        "merchant": {
            "partnerId": "PID-1234567"
        },
        "status": "active",
        "createTime": "2022-02-14T09:52:22.123Z",
        "updateTime": "2022-02-14T09:52:22.123Z",
        "type": "card",
        "card": {
            "account": {
                "firstDigits": 411111,
                "lastDigits": 1111,
                "length": 16,
                "expiryMonth": 1,
                "expiryYear": 2030
            }
        }
    }
}

Webhooks using tokenization

When a token is created or modified during a tokenization request, a webhook notification is generated for the change to the token. If the token creation request returns an existing token without any changes, no webhook notification will be generated.

Check the webhooks reference for more information.

Example of webhook for a tokenization of a card

{
    "id": "2nsCzyNFJGR5hJC50idq89jB1To",
    "live": true,
    "type": "token",
    "version": "v1",
    "createTime": "2024-10-21T08:50:34.654Z",
    "payload": {
        "id": "2kv0Qq1kGFJ4EjFXSBFyrwYRvbp",
        "merchant": {
            "partnerId": "PID-1234567"
        },
        "status": "active",
        "createTime": "2024-10-21T08:50:36.109Z",
        "updateTime": "2024-10-21T08:50:36.109Z",
        "type": "card",
        "card": {
            "account": {
                "firstDigits": 555555,
                "lastDigits": 4444,
                "length": 16,
                "expiryMonth": 1,
                "expiryYear": 2030
            }
        }
    }
}

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.