Skip to main content

Card Tokenization

Card tokenization is a white-label integration: you accept card payments on your website without redirecting buyers to PayU. It keeps payments secure, reduces your PCI DSS scope and gives you more control over the payment process, which helps increase conversion.

Overview​

A payment flow consists of two steps: a front-end process and a back-end process.

In the front-end process, card data is securely captured and you receive a token and a masked card number, so you never handle the full card details. In the back-end process, the token is used to create the payment transaction.

PayU tokens can be single-use or multi-use. Single-use tokens are valid for one payment only and cannot be stored. Multi-use tokens can be stored and reused for future payments. This is especially useful for shops with many returning buyers: once a buyer's account is linked to a multi-use token, the buyer does not need to re-enter card data for each payment.

Security Requirements and Recommendations​

Before integrating card tokenization, read the requirements and recommendations from our security experts. They help you protect your business against fraud.

Additional Configuration​

Single-use tokens do not require additional configuration. To enable multi-use tokens, contact your PayU account manager.

Note that...

Tokenization may be disabled on some older POSs.

Integration Overview​

Card tokenization works with or without saving the card. When paying, the buyer can choose whether to save the card in your system. If the buyer does not want to save the card, the process is as follows:

  • Integrate Secure Form into your frontend to securely collect card data.
  • On your frontend, tokenize the card using the SINGLE type and pass the token to your backend.
  • From your backend, send an order request with the token to PayU.

The flow for a white-label payment without storing the card token (first payment) is shown below:

first payment with token

If the buyer decides to save the card for future one-click payments during the first payment, the process is as follows:

  • Integrate Secure Form into your frontend.
  • On your frontend, tokenize the card using the MULTI type and pass the token to your backend.
  • From your backend, send an order request with the token and the required buyer details.
  • Retrieve the stored tokens during the buyer's next checkout.

The flow for white-label payments with a multi-use token (second and subsequent payments) is shown below:

subsequent payments with token

Device Fingerprint​

A device fingerprint is a collection of information gathered from a device, such as a computer or smartphone, that can be used to identify it. Device fingerprints can partially or fully identify devices or individual users, and they are often used in online security and fraud prevention systems.

The fingerprint value is generated by the static Fingerprint2.get function, which replaced new Fingerprint2().get. Because of this, the result is no longer hashed.

The examples below use FingerprintJS v2. You can find this version of the library on GitHub.

Fingerprint2.get Usage Example
var options = {}
Fingerprint2.get(options, function (components) {
    // components is array of {key: 'foo', value: 'component value'}
    ...
})

// or

Fingerprint2.getPromise(options).then(function (components) {
    // components is array of {key: 'foo', value: 'component value'}
    ...
})

To hash the fingerprint, use the murmur hash function.

murmur Hash Function Usage Example
Fingerprint2.get(options, function (components) {
  var values = components.map(function (component) {
    return component.value
  })
  var murmur = Fingerprint2.x64hash128(values.join(''), 31)
})

Pass the hash to PayU in the deviceFingerprint field of the order.

Order Example with deviceFingerprint
curl -v -X POST https://secure.payu.com/api/v2_1/orders \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd" \
-d '{
        "notifyUrl":"https://your.eshop.com/notify",
        "customerIp":"127.0.0.1",
        "merchantPosId":"145227",
        "description":"Laptop",
        "currencyCode":"PLN",
        "totalAmount":"15000",
        "cardOnFile": "FIRST",
        "extOrderId":"60kiyw2dckg7wtjn1zl0ip",
        "products":[
            {
                "name":     "Laptop",
                "unitPrice":"15000",
                "quantity": "1"
            }
        ],
        "buyer": {
            "email": "john.doe@example.com",
            "firstName": "John",
            "lastName": "Doe",
            "language": "en"
        },
        "payMethods": {
            "payMethod": {
                "value": "TOK_1IHRPT6HKSSS3H62K0GS8pElP862",
                "type":  "CARD_TOKEN"
            }
        },
        // highlight-next-line
        "deviceFingerprint": "20601bbecba69f841b3d61986bf9c1f6"
    }'

Flow Examples​

The following scenarios show the card tokenization flows.

First Charge​

Step 1 – Method: POST – Obtain an OAuth access token.

Step 2 – Method: GET – Retrieve available payment methods.

Step 3 – Collect card data with Secure Form and tokenize the card.

Step 4 – Method: POST – Prepare an OrderCreateRequest (with the cardOnFile or recurring parameter if required), insert the card token obtained from Secure Form and submit the request.

Step 5 – Handle the WARNING_CONTINUE_3DS status returned in the response by redirecting the buyer to the URL in the redirectUri parameter or by handling it in an iframe.

(optional) Step 5.5 – Only when 3DS authentication took too long and CVV2/CVC2 is no longer cached by PayU: handle the WARNING_CONTINUE_CVV status added to continueUrl.

Step 6 – Receive the notification with the order status sent to the address specified in notifyUrl.

(optional) Step 7 – Method: PUT – Only when auto-receive is disabled for the given payment method: capture the order.

Subsequent Charge without Card Authentication​

Step 1 – Method: POST – Obtain an OAuth access token.

Step 2 – Method: GET – Retrieve available payment methods, including the multi-use card token.

Step 3 – Method: POST – Prepare an OrderCreateRequest, insert the multi-use card token and submit the request.

Step 4 – Receive the notification with the order status sent to the address specified in notifyUrl.

(optional) Step 5 – Method: PUT – Only when auto-receive is disabled for the given payment method: capture the order.

Subsequent Charge with Full Card Authentication​

Step 1 – Method: POST – Obtain an OAuth access token.

Step 2 – Method: GET – Retrieve available payment methods, including the multi-use card token.

Step 3 – Method: POST – Prepare an OrderCreateRequest, insert the multi-use card token and submit the request.

Step 4 – Handle the WARNING_CONTINUE_3DS status returned in the response by redirecting the buyer to the URL in the redirectUri parameter.

Step 5 – Handle the WARNING_CONTINUE_CVV status added to continueUrl.

Step 6 – Receive the notification with the order status sent to the address specified in notifyUrl.

(optional) Step 7 – Method: PUT – Only when auto-receive is disabled for the given payment method: capture the order.

Subsequent Charge with Partial Card Authentication​

Step 1 – Method: POST – Obtain an OAuth access token.

Step 2 – Method: GET – Retrieve available payment methods, including the multi-use card token.

Step 3 – Method: POST – Prepare an OrderCreateRequest, insert the multi-use card token and submit the request.

Step 4 – Handle the WARNING_CONTINUE_3DS or WARNING_CONTINUE_CVV status returned in the response.

Step 5 – Receive the notification with the order status sent to the address specified in notifyUrl.

(optional) Step 6 – Method: PUT – Only when auto-receive is disabled for the given payment method: capture the order.

Topics in this Section

On this page