Network Tokenisation

Introduction

Network tokens are surrogate values that replace Primary Account Number (PAN) stored electronically throughout the payments system. Network Tokens can be used to conduct payment transactions securely and can provide improved protection against fraud, because network tokens can require cryptogram validation or be limited to use in a specific domain or circumstance, such as token requestor, device or channel.
The purpose of this article is to describe the process how to generate and use the network tokens in the Gateway.

Initial Setup and Conditions

In order to utilise network tokens, it is necessary to change your account setup respectively. Please contact your boarding team or customer support team to manage the setup for you.

In case you are located in India, due to compliance requirements you need to obtain and capture customer’s consent and perform Strong Customer Authentication (SCA) before customer’s credit card is tokenized. You can authenticate your customer by using a 3-D Secure request followed by successful authorization which thereby provides you with the permission to request a network token. Please note, that you should not store card number at your end and generate the token instead.

Payments API

Network Token Generation

If you want to store the credit card information under network token, you need to send a request with referencedOrderIdof the transaction which captured consumer's consent to store their sensitive credit card information under a token.

The following JSON document represents an example of a request including your own token value:

{
    "requestType": "ReferencedOrderPaymentTokenizationRequest",
    "referencedOrderId": "C-8a820c97-03e5-4045-83ff-a9b5976ab0c9",
    "storeId": "330995118",
    "createToken": {
        "value": "TEST125"
     }   
}

A network token is provisioned by the Gateway for the card data used in submitted referencedOrderIdand linked to the Token value you have provided in the previous request. The call to retrieve a token from the schemes is made by our system automatically.

{
    "clientRequestId": "2838649",
    "apiTraceId": "YbsATprutgkfwMXM9131BQAAA4E",
    "requestStatus": "SUCCESS",
    "requestTime": 1639645262162,
    "paymentToken": {
        "value": "TEST125",
        "reusable": true,
        "declineDuplicates": false,
        "last4": "3006",
        "brand": "MASTERCARD",
        "accountVerification": false,
        "type": "PAYMENT_CARD"
    }
}

If you do not wish to define your own ‘paymentToken’ value in your token provisioning request, the Gateway will generate this value for you and you will obtain it in the API response.

The following json document represents an example of a request without submitted ‘paymentToken’:

{
    "requestType": "ReferencedOrderPaymentTokenizationRequest",
    "referencedOrderId": "C-8a820c97-03e5-4045-83ff-a9b5976ab0c9",
    "storeId": "330995118",
    "createToken": {
          }
   
}

The following json document represents an example of the response including generated ‘paymentToken’:

{
    "clientRequestId": "2838649",
    "apiTraceId": "YbsAhUr75THtfN2sdqvVhQAAA8E",
    "requestStatus": "SUCCESS",
    "requestTime": 1639645317009,
    "paymentToken": {
        "value": "FF2E6982-BA39-477D-A486-D6970846DE80",
        "reusable": true,
        "declineDuplicates": false,
        "last4": "3006",
        "brand": "MASTERCARD",
        "accountVerification": false,
        "type": "PAYMENT_CARD"
    }
}

Initiate payment transactions using Network Token and Cryptogram

Network token and a cryptogram will be provided in the response after you submitted the following request to the Gateway:

POST /v2/services/payment-tokens/{paymentTokenValue}/cryptogram

{
    "storeId": "330995118"
}

Below is the example of the response including associated credit card details, network token value and token cryptogram.

{
    "clientRequestId": "2838649",
    "apiTraceId": "YbsBzwSL38Qqaq8aJ53@hwAAAhM",
    "requestStatus": "SUCCESS",
    "requestTime": 1639645647039,
    "networkToken": {
        "value": "5204736200204958",
        "expiryMonth": "01",
        "expiryYear": "25",
        "cardLast4": "3006",
        "brand": "MASTERCARD",
        "cryptogram": "AGX1lvbYlypcAAFHV22IGgADFA=="
    }
}

Received data can be used to trigger a sale or preauth request.

⚠️

Please note, that in case you are located in European Union or India, you are mandated to perform 3-D Secure authentication for every eCommerce transaction. In case you are using network tokens with such transaction, you need to include "tokenCryptogram" element in all sale/preauth requests for all 3DS protocols (2.1 and 2.2).

The following json document represents an example of a Sale transaction using network token and token cryptogram with included 3DS v1 call:

{
    "requestType": "PaymentCardSaleTransaction",
    "storeId": "330995118",
    "transactionAmount": {
        "total": "178.00",
        "currency": "INR"
    },
    "transactionOrigin": "ECOM",
    "paymentMethod": {
        "paymentCard": {
            "number": "5204736200113910",
            "securityCode": "006",
            "cardFunction": "DEBIT",
            "expiryDate": {
                "month": "12",
                "year": "24"
            }
        }
    },
    "authenticationRequest": {
        "authenticationType": "Secure3DAuthenticationRequest",
        "termURL": "https://test.ipg-online.com/webshop/simulator/secure3d/return",
        "methodNotificationURL": "https://test.test/notify",
        "messageCategory": "01"
    },
    "order": {
        "tokenCryptogram": "AGX1lvbYlypcAAFHV22IGgADFA=="
    }
}

In the response you will obtain authentication parameters, what should be used in the next call to the Gateway:

{
    "clientRequestId": "2838649",
    "apiTraceId": "YbsF-DfjEh@p8a4GDb3JSQAAA2Y",
    "ipgTransactionId": "84385055093",
    "orderId": "R-f98d11be-9bea-419b-9645-1c4404971c10",
    "transactionType": "SALE",
    "paymentToken": {
        "reusable": true,
        "declineDuplicates": false,
        "brand": "MASTERCARD",
        "type": "PAYMENT_CARD"
    },
    "transactionOrigin": "ECOM",
    "paymentMethodDetails": {
        "paymentCard": {
            "expiryDate": {
                "month": "12",
                "year": "2024"
            },
            "cardFunction": "DEBIT",
            "bin": "520473",
            "last4": "3910",
            "brand": "MASTERCARD"
        },
        "paymentMethodType": "PAYMENT_CARD"
    },
    "transactionTime": 1639646716,
    "transactionStatus": "WAITING",
    "approvalCode": "?:waiting 3dsecure",
    "authenticationResponse": {
        "type": "3D_SECURE",
        "version": "1.0",
        "params": {
            "payerAuthenticationRequest": "eJxVUslywjAM……….07LxXdr4L6/27lx8yoLp8",
            "termURL": "https://test.ipg-online.com/webshop/simulator/secure3d/return",
            "merchantData": "MD_________17800202112160925162356Y7OjntZ3r1/WkioPvj95VgnXdfI=_____111111_________470000032001125______R-f98d11be-9bea-419b-96450ww_________________________________________________________________________________________return-url?_______________________________________________________________________________________VRQR-f98d11be-9bea-419b-9645-1c4404971c1079c536",
            "acsURL": "https://test3.3ds.firstdata.com/fs3ds-dsacs/acs/pareq"
        }
    }
}

The complete process how to perform 3-D Secure is described here: 3-D Secure

It is important to include the element tokenCryptogram in your PATCH request to the original transaction, once you received the response from the ACS about the successful authentication:

PATCH /v2/services/payments/{transaction-id}

{
    "authenticationType": "Secure3D10AuthenticationUpdateRequest",
    "storeId": "330995118",
    "payerAuthenticationResponse": "SAf33f+Ovbx9fn……………….2a8P05/fDL//YP1fgD3NaQ==",
    "merchantData": "MD_________17800202112160925162356Y7OjntZ3r1/WkioPvj95VgnXdfI=_____111111_________470000032001125______R-f98d11be-9bea-419b-96450ww_________________________________________________________________________________________return-url?_______________________________________________________________________________________VRQR-f98d11be-9bea-419b-9645-1c4404971c1079c536",
    "tokenCryptogram": "AGX1lvbYlypcAAFHV22IGgADFA=="
}

The following JSON document represents an example of the response you will receive after successfully authenticated and authorized transaction using token cryptogram:

{
    "clientRequestId": "2838649",
    "apiTraceId": "YbsG@MItojOb3pFHVNWOygAAA7w",
    "ipgTransactionId": "84385055093",
    "orderId": "R-f98d11be-9bea-419b-9645-1c4404971c10",
    "transactionType": "SALE",
    "paymentToken": {
        "reusable": true,
        "declineDuplicates": false,
        "brand": "MASTERCARD",
        "type": "PAYMENT_CARD"
    },
    "transactionOrigin": "ECOM",
    "paymentMethodDetails": {
        "paymentCard": {
            "expiryDate": {
                "month": "12",
                "year": "2024"
            },
            "cardFunction": "DEBIT",
            "bin": "520473",
            "last4": "3910",
            "brand": "MASTERCARD"
        },
        "paymentMethodType": "PAYMENT_CARD"
    },
    "terminalId": "00001115",
    "merchantId": "470000032001125",
    "transactionTime": 1639646716,
    "approvedAmount": {
        "total": 178,
        "currency": "INR",
        "components": {
            "subtotal": 178
        }
    },
    "transactionStatus": "APPROVED",
    "approvalCode": "Y:006973:4385055093:PPX :121609639289",
    "secure3dResponse": {
        "responseCode3dSecure": "1"
    },
    "processor": {
        "referenceNumber": "121609639289",
        "authorizationCode": "006973",
        "responseCode": "00",
        "responseMessage": "Function performed error-free",
        "avsResponse": {
            "streetMatch": "NO_INPUT_DATA",
            "postalCodeMatch": "NO_INPUT_DATA"
        }
    }
}

Display Stored Network Token Details

For cases when you would like to get information about the network token associated with your store and token value, you can submit a GET request with referenced paymentTokenValue:

GET /v2/services/payment-tokens/{paymentTokenValue}

The following json document represents an example of API response:

{
    "clientRequestId": "2838649",
    "apiTraceId": "YbsJPn4TVn0bWRZH6wmlegAAAuc",
    "requestStatus": "SUCCESS",
    "requestTime": 1639647550653,
    "paymentToken": {
        "value": "FF2E6982-BA39-477D-A486-D6970846DE80",
        "reusable": false,
        "brand": "MASTERCARD",
        "type": "PAYMENT_CARD"
    },
    "networkToken": {
        "value": "520473******4958",
        "expiryMonth": "01",
        "expiryYear": "25"
    }
}

Store payment information without performing a transaction at the same time

For cases where you would prefer to store credit card details without performing a transaction at the same time, you can submit a request type: PaymentCardPaymentTokenizationRequestincluding credit card details as on example below, and accountVerification element set to false:

Please note, that you have to obtain customer’s consent and perform additional strong customer authentication via 3-D Secure before submitting the request to store card credentials.

POST /v2/services/payment-tokens


{
    "requestType": "PaymentCardPaymentTokenizationRequest",
    "storeId": "330995118",
    "paymentCard": {
        "number": "520473******3006",
        "expiryDate": {
            "month": "12",
            "year": "24"
        },
        "securityCode": "XXX"
    },
   
    "createToken": {
      
    },
    "accountVerification": false
}

Hosted Payment Page Integration

You can use Network Tokens also with our Hosted Payment Pages solution. You can send a transaction request using Network Token value submitted in cardnumber field together with tokenCryptogram.

The following represents an example of a ‘Sale’ transaction request including tokenCryptogram and Network Token value filled out in the cardnumber field:

<!-- #include file="ipg-util.asp"-->
<html>
<head><title>IPG Connect Sample for ASP</title></head>
<body>
<p><h1>Order Form</h1></p>
<form method="post" action=" https://test.ipg-online.com/connect/gateway/processing ">
  <input type="hidden" name="txntype" value="sale">
    <input type="hidden" name="checkoutoption" value="combinedpage">
    <input type="hidden" name="timezone" value="Europe/Berlin"/>
    <input type="hidden" name="txndatetime" value="<% getDateTime() %>"/>
    <input type="hidden" name="hash_algorithm" value="HMACSHA256"/>
    <input type="hidden" name="hashExtended" value="<% call createExtendedHash( "13.00","978" ) %>"/>
    <input type="hidden" name="storename" value="1109950006" />
    <input type="hidden" name="mode" value="payonly"/>
    <input type="hidden" name="paymentMethod" value="M"/>
    <input type="text" name="chargetotal" value="130.00" />
    <input type="hidden" name="currency" value="978"/>
    <input type="hidden" name="authenticateTransaction" value="true"/>
    <input type="hidden" name="threeDSRequestorChallengeIndicator" value=”1”/>
    <input type="hidden" name="tokenCryptogram" value=”AGX1lvbYlypcAAV22IGgADFA==”/>
    <input type="text" name="cardnumber" value="540215******2355">
    <input type="text" name="expmonth" value="12">
    <input type="text" name="expyear" value="24">
    <input type="submit" value="Submit">
</form>
</body>
</html>

Once you retrieved Network Token from your provider, you can use our HPP combinedmode to submit its value in cardnumber field together with tokenCryptogram.

The following represents an example of a ‘Sale’ transaction request including tokenCryptogram and Network Token value filled out in the cardnumber field:

<html>
<head><title>IPG Connect Sample for ASP</title></head>
<body>
<p><h1>Order Form</h1></p>
<form method="post" action=" https://test.ipg-online.com/connect/gateway/processing ">
  <input type="hidden" name="txntype" value="sale">
    <input type="hidden" name="checkoutoption" value="combinedpage">
    <input type="hidden" name="timezone" value="Europe/Berlin"/>
    <input type="hidden" name="txndatetime" value="<% getDateTime() %>"/>
    <input type="hidden" name="hash_algorithm" value="HMACSHA256"/>
    <input type="hidden" name="hashExtended" value="<% call createExtendedHash( "13.00","978" ) %>"/>
    <input type="hidden" name="storename" value="1109950006" />
    <input type="hidden" name="mode" value="payonly"/>
    <input type="hidden" name="paymentMethod" value="M"/>
    <input type="text" name="chargetotal" value="130.00" />
    <input type="hidden" name="currency" value="978"/>
    <input type="hidden" name="authenticateTransaction" value="true"/>
    <input type="hidden" name="threeDSRequestorChallengeIndicator" value=”1”/>
    <input type="hidden" name="tokenCryptogram" value=”AGX1lvbYlypcAAV22IGgADFA==”/>
    <input type="text" name="cardnumber" value="540215******2355">
    <input type="text" name="expmonth" value="12">
    <input type="text" name="expyear" value="24">
    <input type="submit" value="Submit">
</form>
</body>
</html>

Want a quick overview?