Network Tokenisation

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.

In order to utilize network tokenization, a special configuration is needed for your store.
Please contact your client support team for further details and to manage the setup for you.

In case you are located in India or European Economic Area, 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.

Network Token Generation

In order to request a network token to store the credit card information you used in the previous step in which the customer consent was captured, you need to send an action request to the Gateway and provide OrderId and HostedDataID of this transaction.

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

The following XML document represents an example of an action request including HostedDataID and the response, when the request has been completed successfully:

<ns4:IPGApiActionRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
    <ns2:Action>
        <ns2:StoreHostedData>
            <ns2:StoreId>330115006</ns2:StoreId>
            <ns2:DataStorageItem>
                <ns2:OrderId>C-bd4e8baa-b2310cc20eb0</ns2:OrderId>
                <ns2:HostedDataID>test123</ns2:HostedDataID>
            </ns2:DataStorageItem>
        </ns2:StoreHostedData>
    </ns2:Action>
</ns4:IPGApiActionRequest>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ipgapi:IPGApiActionResponse
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
            <ipgapi:successfully>true</ipgapi:successfully>
        </ipgapi:IPGApiActionResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

In case you do not wish to define your own HostedDataID in your token provisioning request, the Gateway will generate its value for you and you will obtain it in the API response.

The following XML document represents an example of a request without submitted HostedDataID and an example of the response including generated HostedDataID:

<ns4:IPGApiActionRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
    <ns2:Action>
        <ns2:StoreHostedData>
            <ns2:StoreId>330115006</ns2:StoreId>
            <ns2:DataStorageItem>
                <ns2:OrderId>C-bd4e8baa-b2310cc20eb0</ns2:OrderId>
                <ns2:AssignToken>true</ns2:AssignToken>
            </ns2:DataStorageItem>
        </ns2:StoreHostedData>
    </ns2:Action>
</ns4:IPGApiActionRequest>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ipgapi:IPGApiActionResponse
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
            <ipgapi:successfully>true</ipgapi:successfully>
            <ipgapi:DataStorageItem>
                <a1:CreditCardData>
                    <v1:CardNumber>3006*****1234</v1:CardNumber>
                    <v1:ExpMonth>12</v1:ExpMonth>
                    <v1:ExpYear>27</v1:ExpYear>
                    <v1:Brand>MASTERCARD</v1:Brand>
                </a1:CreditCardData>
                <a1:HostedDataID>CD0A6414-B78C-40B0-9D1F90F16C32952F</a1:HostedDataID>
           </ipgapi:DataStorageItem>
        </ipgapi:IPGApiActionResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

You can use the HostedDataID linked to a network token for further transaction processing.

Payment Transaction Initiation using "HostedDataId"

With generated HostedDataIDyou can perform transactions without the need to pass the credit card or bank account data again. Please note, that it is not allowed to store the card code (in most cases on the back of the card) so that for credit card transactions, the cardholder still needs to enter this value.

The following XML document represents an example of a Sale transaction including minimum set of elements:

<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ns4:IPGApiOrderRequest
            xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
            xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
            xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
            <ns2:Transaction>
                <ns2:CreditCardTxType>
                 <ns2:StoreId>330115006</ns2:StoreId>
                 <ns2:Type>sale</ns2:Type>
                </ns2:CreditCardTxType>
                <ns2:CreditCardData>
                 <ns2:CardCodeValue>XXX</ns2:CardCodeValue>
                </ns2:CreditCardData>
                <ns2:Payment>
                 <ns2:HostedDataID>CD0A6414-B78C-40B0-9D1F-90F16C32952F</ns2:HostedDataID>
                 <ns2:ChargeTotal>500.00</ns2:ChargeTotal>
                 <ns2:Currency>356</ns2:Currency> 
                </ns2:Payment>
            </ns2:Transaction>
        </ns4:IPGApiOrderRequest>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Payment Transaction Initiation using Network Token and Cryptogram

You can also perform a transaction using network token and a cryptogram instead of using HostedDataID.

Network token and a cryptogram will be provided in the API response after you submitted the following action request to the Gateway. In the response you will find associated credit card details, token number and token cryptogram.

<SOAP-ENV:Envelope
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns4:IPGApiActionRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
    <ns2:Action>
        <ns2:GetNetworkTokenCryptogram>
            <ns2:StoreId>330115006</ns2:StoreId>
            <ns2:HostedDataID>A03D6777-D729-4C35-A556-8D6B285E440D</ns2:HostedDataID>
        </ns2:GetNetworkTokenCryptogram>
    </ns2:Action>
</ns4:IPGApiActionRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ipgapi:IPGApiActionResponse
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
            <ipgapi:successfully>true</ipgapi:successfully>
            <ipgapi:NetworkTokenData>
            <v1:NetworkTokenNumber>5204XXXX80216</v1:NetworkTokenNumber>
                <v1:ExpMonth>12</v1:ExpMonth>
                <v1:ExpYear>27</v1:ExpYear>
                <v1:CardLast4>3006</v1:CardLast4>
                <v1:Brand>MASTERCARD</v1:Brand>
                <v1:TokenCryptogram>AJ0BWvQntOkiAAHFcGgADFA==</v1:TokenCryptogram>
            </ipgapi:NetworkTokenData>
        </ipgapi:IPGApiActionResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

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

A payment transaction using network token can be initiated by submitting the network token number you received in previous API response as a value of the element ‘CardNumber’ and the expiry date of the credit card replaced by the network token expiry. It is important to include the ‘TokenCryptogram’ in the request as well.

The following XML document represents an example of a Sale transaction using network token and token cryptogram elements followed by a response:

<soapenv:Envelope 
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ipg="http://ipg-online.com/ipgapi/schemas/ipgapi" 
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1" 
   <soapenv:Header/>
   <soapenv:Body>
      <ipg:IPGApiOrderRequest>
         <v1:Transaction>
            <v1:CreditCardTxType>
               <v1:StoreId>330115006</v1:StoreId>
               <v1:Type>sale</v1:Type>
            </v1:CreditCardTxType>
            <v1:CreditCardData>
               <v1:CardNumber>520473******0216</v1:CardNumber>
               <v1:ExpMonth>12</v1:ExpMonth>
               <v1:ExpYear>27</v1:ExpYear>
               <v1:CardCodeValue>XXX</v1:CardCodeValue>
               <v1:Brand>MASTERCARD</v1:Brand>
            </v1:CreditCardData>
            <v1:TokenCryptogram>AJ0BWvQntOkiAAHFcQ42GgADFA==</v1:TokenCryptogram>
            <v1:Payment>
               <v1:ChargeTotal>150</v1:ChargeTotal>
               <v1:Currency>INR</v1:Currency>
            </v1:Payment>
          </v1:Transaction>
      </ipg:IPGApiOrderRequest>
   </soapenv:Body>
</soapenv:Envelope>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
    <ipgapi:IPGApiOrderResponse 
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1" 
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi" 
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
<ipgapi:ApprovalCode>Y:006953:4381648535:PPX:113009626785</ipgapi:ApprovalCode>
<ipgapi:AVSResponse>PPX</ipgapi:AVSResponse>
<ipgapi:Brand>MASTERCARD</ipgapi:Brand>
<ipgapi:CommercialServiceProvider>IMS</ipgapi:CommercialServiceProvider>
<ipgapi:OrderId>A-d47b2da7-f64d-475f-8d1f-75be94d1419b</ipgapi:OrderId>
<ipgapi:IpgTransactionId>84381648535</ipgapi:IpgTransactionId>
<ipgapi:PaymentType>CREDITCARD</ipgapi:PaymentType>
<ipgapi:ProcessorApprovalCode>006953</ipgapi:ProcessorApprovalCode>
<ipgapi:ProcessorReferenceNumber>113009626785</ipgapi:ProcessorReferenceNumber>
<ipgapi:ProcessorResponseCode>00</ipgapi:ProcessorResponseCode>
<ipgapi:ProcessorResponseMessage>Function performed error-free</ipgapi:ProcessorResponseMessage>
<ipgapi:TDate>1638266046</ipgapi:TDate>
<ipgapi:TDateFormatted>2021.11.30 10:54:06 (CET)</ipgapi:TDateFormatted>
<ipgapi:TerminalID>12345678</ipgapi:TerminalID>
<ipgapi:TransactionResult>APPROVED</ipgapi:TransactionResult>
<ipgapi:TransactionTime>1638266046</ipgapi:TransactionTime>
</ipgapi:IPGApiOrderResponse>

Please note, that in case you are located in European Union or India, you are mandated to perform a 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.

The following XML document represents an example of a Sale transaction using network token and token cryptogram elements together with 3DS v2 authentication call:

<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ns4:IPGApiOrderRequest
            xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
            xmlns:ns2="http://ipg-online.com/ipgapi/schemas/v1"
            xmlns:ns3="http://ipg-online.com/ipgapi/schemas/a1">
            <ns2:Transaction>
                <ns2:CreditCardTxType>
                    <ns2:StoreId>330995118</ns2:StoreId>
                    <ns2:Type>sale</ns2:Type>
                </ns2:CreditCardTxType>
                <ns2:CreditCardData>
                    <ns2:CardNumber>520473******0216</ns2:CardNumber> 
                    <ns2:ExpMonth>12</ns2:ExpMonth>
                    <ns2:ExpYear>24</ns2:ExpYear>
                    <ns2:CardCodeValue>XXX</ns2:CardCodeValue>
		    <ns2:Brand>MASTERCARD</ns2:Brand>
                </ns2:CreditCardData>
<ns2:TokenCryptogram>AJ0BWvQntOkiAAHFcQ42GgADFA==</ns2:TokenCryptogram>
                <ns2:CreditCard3DSecure>
<ns2:AuthenticateTransaction>true</ns2:AuthenticateTransaction>       
<ns2:TermUrl>https://test.ipg.com/webshop/simulator/secure3d/return</ns2:TermUrl>                    
<ns2:ThreeDSMethodNotificationURL>https://test.com/secure3ds</ns2:ThreeDSMethodNotificationURL>
<ns2:ThreeDSRequestorChallengeIndicator>01</ns2:ThreeDSRequestorChallengeIndicator>
<ns2:ThreeDSRequestorChallengeWindowSize>01</ns2:ThreeDSRequestorChallengeWindowSize>
<ns2:ThreeDSEmvCoMessageCategory>01</ns2:ThreeDSEmvCoMessageCategory>
                </ns2:CreditCard3DSecure>
                <ns2:Payment>
                    <ns2:ChargeTotal>100.00</ns2:ChargeTotal>
                    <ns2:Currency>INR</ns2:Currency>
                </ns2:Payment>
            </ns2:Transaction>
        </ns4:IPGApiOrderRequest>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

3-D Secure authentication and subsequent 'Sale' transaction are performed as per standard process described in 3-D Secure section: 3-D Secure

Displaying Network Token Details

For cases when you would like to get information about the network token associated with your store and HostedDataId, you can use a display function with submitting the StoreID and HostedDataID in your request:

<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:ipg="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
    <soapenv:Header/>
    <soapenv:Body>
<ns4:IPGApiActionRequest
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1">
        <ns2:Action>
          <ns2:StoreHostedData>
              <ns2:StoreId>330115006</ns2:StoreId>
              <ns2:DataStorageItem>
                  <ns2:Function>display</ns2:Function>
                  <ns2:HostedDataID>A03D6777-D729-4C35-A556-8D6B285E440D</ns2:HostedDataID>
              </ns2:DataStorageItem>
          </ns2:StoreHostedData>
        </ns2:Action>
        </ns4:IPGApiActionRequest>
    </soapenv:Body>
</soapenv:Envelope>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ipgapi:IPGApiActionResponse
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
            <ipgapi:successfully>true</ipgapi:successfully>
            <ipgapi:DataStorageItem>
                <a1:NetworkTokenData>
                 <v1:NetworkTokenNumber>520473**0216</v1:NetworkTokenNumber>
                 <v1:ExpMonth>12</v1:ExpMonth>
                 <v1:ExpYear>24</v1:ExpYear>
                 <v1:Brand>MASTERCARD</v1:Brand>
                </a1:NetworkTokenData>
                 <a1:HostedDataID>A03D6777-D729-4C35-A556-8D6B285E440D</a1:HostedDataID>
            </ipgapi:DataStorageItem>
        </ipgapi:IPGApiActionResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Storing Payment Information without Performing a Transaction

For cases where you would prefer to store credit card details without performing a transaction at the same time, you can submit an action request including credit card details as on example below:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ns4:IPGApiActionRequest
xmlns:ns2="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ns3="http://ipg-online.com/ipgapi/schemas/v1"
xmlns:ns4="http://ipg-online.com/ipgapi/schemas/ipgapi">
            <ns2:Action>
                <ns2:StoreHostedData>
                    <ns2:StoreId>330115006</ns2:StoreId>
                    <ns2:DataStorageItem>
                        <ns2:CreditCardData>
                          <ns3:CardNumber>5204********006</ns3:CardNumber>
                          <ns3:ExpMonth>12</ns3:ExpMonth>
                          <ns3:ExpYear>27</ns3:ExpYear>
                          <ns3:CardCodeValue>XXX</ns3:CardCodeValue>
                        </ns2:CreditCardData>
                        <ns2:AssignToken>true</ns2:AssignToken>
                    </ns2:DataStorageItem>
                </ns2:StoreHostedData>
            </ns2:Action>
        </ns4:IPGApiActionRequest>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ipgapi:IPGApiActionResponse
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1"
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi"
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
          <ipgapi:successfully>true</ipgapi:successfully>
          <ipgapi:DataStorageItem>
            <a1:CreditCardData>
                <v1:CardNumber>5555*****3006</v1:CardNumber>
                <v1:ExpMonth>12</v1:ExpMonth>
                <v1:ExpYear>27</v1:ExpYear>
                <v1:Brand>MASTERCARD</v1:Brand>
            </a1:CreditCardData>
            <a1:HostedDataID>A03D6777-D729-4C35-A556-8D6B285E440D</a1:HostedDataID>
          </ipgapi:DataStorageItem>
          </ipgapi:IPGApiActionResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

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

You will get assigned ‘HostedDataID’ in the API response:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <ipgapi:IPGApiActionResponse 
xmlns:a1="http://ipg-online.com/ipgapi/schemas/a1" 
xmlns:ipgapi="http://ipg-online.com/ipgapi/schemas/ipgapi" 
xmlns:v1="http://ipg-online.com/ipgapi/schemas/v1">
            <ipgapi:successfully>true</ipgapi:successfully>
            <ipgapi:DataStorageItem>
                <a1:CreditCardData>
                    <v1:CardNumber>5555*****3006</v1:CardNumber>
                    <v1:ExpMonth>12</v1:ExpMonth>
                    <v1:ExpYear>27</v1:ExpYear>
                    <v1:Brand>MASTERCARD</v1:Brand>
                </a1:CreditCardData>
                <a1:HostedDataID>A03D6777-D729-4C35-A556-8D6B285E440D</a1:HostedDataID>
            </ipgapi:DataStorageItem>
        </ipgapi:IPGApiActionResponse>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

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

API Products

Point of Sale

Developer

Resources

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