Hosted tokenisation button

Use the hosted tokenisation button integration to seamlessly embed Google or Apple Pay buttons into your checkout page through our Secure Fields. With this integration we manage the onboarding process with the wallet provider and offer you a straightforward and hassle-free method to gather card details stored within cardholders' wallets.

Process overview

Find below a high-level overview of the process flow:

Activation

Apple Pay

To complete the onboarding at Apple please login to the Dashboard and navigate to the Developers menu within the project section. Open the Apple Pay Settings tab and enable Apple Pay if not already done.

In the next screen configure the name you want to display on the Apple Pay payment sheet showed to the cardholder and press the Enable button. Finally add your domains and subdomains where the Apple Pay button will be hosted by adding the URLs in the Associated Domains section as shown below:

Google Pay

No setup required for Google Pay as PCI Proxy is taking care of it behind the scenes.

Setup Tokenisation button

Follow the recipe below to get started:

Initialise tokenisation

To capture card data with the Tokenisation button, you need to initialize a transactionId via a server-to-server call first. Call our secureFields/tokenize endpoint with your desired parameters and we will return a transaction identifier ready to be used with our Secure Fields.

For the full API specification please see the API reference

curl -L -X POST 'https://api.sandbox.datatrans.com/v1/transactions/secureFields/tokenize' \
-H 'Authorization: Basic {{basicAuth}}' \
-H 'Content-Type: application/json' \
--data-raw '{
    "applePay": {
        "merchantName": "Merchant Name",
        "currency": "CHF",
        "amount": 100,
        "country": "CH"
    },
    "googlePay": {
        "currency": "CHF",
        "amount": 100,
        "country": "CH"
    }
}'

{
    "transactionId": "230919162326558204"
}

📘

Strong Customer Authentication (SCA) data

Merchants which are subject to Strong Customer Authentication must make sure to submit country and amount. Not providing the correct amount or country might impact the liability shift.

Make sure that amount matches with the amount which will be authorized and charged to the cardholder in any downstream payment. It is also the value which will be displayed in the payment sheet presented to the cardholder.

Request PCI Proxy token

Once you have transmitted the transactionId from the client to your server, you then need to execute a server-to-server POST request to retrieve the PCI Proxy token and 3D data provided by the wallets if available.

Check the walletIndicator parameter to see the original wallet provider of the returned token. For Google Pay, it returns PAY and for Apple Pay APL.

Strong Customer Authentication and liability shift

❗️

Google Pay

The Google Pay API might return cards on file on Google.com (PAN_ONLY) or a device token on an Android-powered device authenticated with a 3D-Secure cryptogram (CRYPTOGRAM_3DS).

In case of a CRYPTOGRAM_3DS enabled card, 3D-Secure related data such as the eci and caav values will be present in the 3D object of the get TOKEN API response. For cards with PAN_ONLY authentication, no 3D object is returned and a separate 3D-Secure authentication step might be required. Refer to 3D Secure Authentication if you want to process 3D-Secure authentications with PCI Proxy.

Apple Pay

Visa Apple Pay tokens come with 3D-Secure data elements (eci and caav) in the 3D object of the get TOKEN API response as Apple Pay is only returning device PANs (DPAN). For Mastercard tokens the eci value is not available.

Example Request & Response

curl -L -X POST 'https://api.sandbox.datatrans.com/v1/tokenizations/{{transactionId}}' \
-H 'Authorization: Basic {{basicAuth}}' \
-H 'Content-Type: application/json'

{
    "alias": "7LHXscqwAAEAAAGLbFhOeHrXIiMLAEcX",
    "fingerprint": "F-dN4ZBIp_rGghxyGVlDmVOv",
    "maskedCard": "412374xxxxxx0013",
    "expiryYear": "25",
    "expiryMonth": "06",
    "cardInfo": {
        "brand": "VISA",
        "type": "credit",
        "usage": "consumer",
        "country": "US",
        "issuer": ""
    },
    "walletIndicator": "APL",
    "3D": {
        "cavv": "Yzu7ORQAA1LQNMiNlUP6MAACAAA=",
        "eci": "5"
    },
    "last4": "1914"
}

{
    "alias": "7LHXscqwAAEAAAGLbRHwv1vpwvThAOyd",
    "fingerprint": "F-dN4ZBIp_rGghxyGVlDmVOv",
    "maskedCard": "412374xxxxxx0013",
    "expiryYear": "25",
    "expiryMonth": "06",
    "cardInfo": {
        "brand": "VISA",
        "type": "credit",
        "usage": "consumer",
        "country": "US",
        "issuer": ""
    },
    "walletIndicator": "PAY",
    "3D": {
        "cavv": "AgAAAAAABk4DWZ4C28yUQAAAAAA=",
        "eci": "07"
    },
    "last4": "1914"
}

{
    "alias": "7LHXscqwAAEAAAGK4UF0bShLshqhAGri",
    "fingerprint": "F-fkO8WHlN03g-bhs44wFI9J",
    "maskedCard": "412374xxxxxx0013",
    "expiryYear": "25",
    "expiryMonth": "06",
    "cardInfo": {
        "brand": "VISA",
        "type": "credit",
        "usage": "consumer",
        "country": "US",
        "issuer": ""
    },
    "walletIndicator": "PAY",
    "last4": "0013"
}

📘

Check last4 to see the original last four digits of the full pan (FPAN). Values returned in the maskedCard element represent the masked device pan (DPAN) - except for the Google Pay PAN_ONLYflow where the FPAN is returned as masked value.

Showcase & Examples

The source code for the integrations is hosted on our GitHub Repository. To see an an interactive demo please visit here: Online demo