Network Tokens - Step By Step

In this guide, you’ll learn how to use a network token as part of our Card Storage Service. This includes sending requests for a new payer and a new card, creating Auth and Receipt-In transactions, and detokenizing a card. The steps in this guide are the same whether you use direct API integration or our Hosted Payment Page.

For more information on network tokens, see our Overview.

Step 1: Payer-new request

Before you can proceed to make a new card token or network token, you must create a payer. The payer-new request will include the information as shown in the sample below. Once you’ve created a payer, you can proceed to Step 2.

//coming soon

$config = new GpEcomConfig();
$config->merchantId = "MerchantId";
$config->accountId = "accountId";
$config->sharedSecret = "secret";
ServicesContainer::configureService($config);

$newCustomer = new Customer();
$newCustomer->key = '0f357b45-9aa4-4453-a685-c69232e9024f';
$newCustomer->title = "Mr.";
$newCustomer->firstName = "James";
$newCustomer->lastName = "Mason";
$newCustomer->company = "Global Payments";
$newCustomer->address = new Address();
$newCustomer->address->streetAddress1 = "Flat 123";
$newCustomer->address->streetAddress2 = "House 456";
$newCustomer->address->streetAddress3 = "The Cul-De-Sac";
$newCustomer->address->city = "Halifax";
$newCustomer->address->province = "West Yorkshire";
$newCustomer->address->postalCode = "W6 9HR";
$newCustomer->address->country = "United Kingdom";
$newCustomer->homePhone = "+35312345678";
$newCustomer->workPhone = "+3531987654321";
$newCustomer->fax = "+124546871258";
$newCustomer->mobilePhone = "+25544778544";
$newCustomer->email = "text@example.com";
$newCustomer->dateOfBirth = date('Ymd',strtotime('1985-12-22'));

try {
    $payer = $newCustomer->Create();
} catch (GatewayException $e) {
    // check for already created
    if ($e->responseCode != "501") {
        echo $e->responseMessage;
    } else {
        echo 'Payer already exists!';
    }
}
$payerId = $payer->id;

$config = new GpEcomConfig();
$config->merchantId = "MerchantId";
$config->accountId = "accountId";
$config->sharedSecret = "secret";
ServicesContainer::configureService($config);

$newCustomer = new Customer();
$newCustomer->key = '0f357b45-9aa4-4453-a685-c69232e9024f';
$newCustomer->title = "Mr.";
$newCustomer->firstName = "James";
$newCustomer->lastName = "Mason";
$newCustomer->company = "Global Payments";
$newCustomer->address = new Address();
$newCustomer->address->streetAddress1 = "Flat 123";
$newCustomer->address->streetAddress2 = "House 456";
$newCustomer->address->streetAddress3 = "The Cul-De-Sac";
$newCustomer->address->city = "Halifax";
$newCustomer->address->province = "West Yorkshire";
$newCustomer->address->postalCode = "W6 9HR";
$newCustomer->address->country = "United Kingdom";
$newCustomer->homePhone = "+35312345678";
$newCustomer->workPhone = "+3531987654321";
$newCustomer->fax = "+124546871258";
$newCustomer->mobilePhone = "+25544778544";
$newCustomer->email = "text@example.com";
$newCustomer->dateOfBirth = date('Ymd',strtotime('1985-12-22'));

try {
    $payer = $newCustomer->Create();
} catch (GatewayException $e) {
    // check for already created
    if ($e->responseCode != "501") {
        echo $e->responseMessage;
    } else {
        echo 'Payer already exists!';
    }
}
$payerId = $payer->id;

try
            {
                GpEcomConfig config = new GpEcomConfig();
                config.MerchantId = "MerchantId";
                config.AccountId = "internet";
                config.SharedSecret = "secret";

                ServicesContainer.ConfigureService(config);

                Customer newCustomer = new Customer();
                newCustomer.Key = "New Id";
                newCustomer.Id = "E8953893489";
                newCustomer.Title = "Mr.";
                newCustomer.FirstName = "James";
                newCustomer.LastName = "Mason";
                newCustomer.Company = "Realex Payments";
                newCustomer.Address = new Address
                {
                    StreetAddress1 = "Flat 123",
                    StreetAddress2 = "House 456",
                    StreetAddress3 = "The Cul-De-Sac",
                    City = "Halifax",
                    Province = "West Yorkshire",
                    PostalCode = "W6 9HR",
                    Country = "United Kingdom"
                };
                newCustomer.HomePhone = "+35312345678";
                newCustomer.WorkPhone = "+3531987654321";
                newCustomer.Fax = "+124546871258";
                newCustomer.MobilePhone = "+25544778544";
                newCustomer.Email = "text@example.com";
                newCustomer.Comments = "Campaign Ref E7373G";
                newCustomer.DateOfBirth = "19901222";

                var customer = newCustomer.Create();               
            }
            catch (GatewayException exc)
            {
                // check for already created
                if (exc.ResponseCode != "501")
                    throw;
            }

try
            {
                GpEcomConfig config = new GpEcomConfig();
                config.MerchantId = "MerchantId";
                config.AccountId = "internet";
                config.SharedSecret = "secret";

ServicesContainer.ConfigureService(config);

Customer newCustomer = new Customer();
                newCustomer.Key = "New Id";
                newCustomer.Id = "E8953893489";
                newCustomer.Title = "Mr.";
                newCustomer.FirstName = "James";
                newCustomer.LastName = "Mason";
                newCustomer.Company = "Realex Payments";
                newCustomer.Address = new Address
                {
                    StreetAddress1 = "Flat 123",
                    StreetAddress2 = "House 456",
                    StreetAddress3 = "The Cul-De-Sac",
                    City = "Halifax",
                    Province = "West Yorkshire",
                    PostalCode = "W6 9HR",
                    Country = "United Kingdom"
                };
                newCustomer.HomePhone = "+35312345678";
                newCustomer.WorkPhone = "+3531987654321";
                newCustomer.Fax = "+124546871258";
                newCustomer.MobilePhone = "+25544778544";
                newCustomer.Email = "text@example.com";
                newCustomer.Comments = "Campaign Ref E7373G";
                newCustomer.DateOfBirth = "19901222";

var customer = newCustomer.Create();               
            }
            catch (GatewayException exc)
            {
                // check for already created
                if (exc.ResponseCode != "501")
                    throw;
            }

<?xml version="1.0" encoding="UTF-8"?>
<request type="payer-new" timestamp="20180614095601">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>OL0f0VYFQTyNG5IulhsMrg</orderid>
  <payer ref="0f357b45-9aa4-4453-a685-c69232e9024f" type="Retail">
    <title>Mr.</title>
    <firstname>James</firstname>
    <surname>Mason</surname>
    <company>Global Payments</company>
    <address>
      <line1>Flat 123</line1>
      <line2>House 456</line2>
      <line3>The Cul-De-Sac</line3>
      <city>Halifax</city>
      <county>West Yorkshire</county>
      <postcode>W6 9HR</postcode>
      <country code="GB">United Kingdom</country>
    </address>
    <phonenumbers>
      <home>+35312345678</home>
      <work>+3531987654321</work>
      <fax>+124546871258</fax>
      <mobile>+25544778544</mobile>
    </phonenumbers>
    <email>text@example.com</email>
    <dateofbirth>19851222</dateofbirth>
    <state>Yorkshire and the Humber</state>
    <passphrase>montgomery</passphrase>
    <vatnumber>GB 123456789</vatnumber>
    <varref>Car Part HV</varref>
    <custnum>E8953893489</custnum>
  </payer>
  <sha1hash>8d7e42bba0d9f6ca81f6106bfd74d2911fad888b</sha1hash>
</request>

<?xml version="1.0" encoding="UTF-8"?>
<request type="payer-new" timestamp="20180614095601">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>OL0f0VYFQTyNG5IulhsMrg</orderid>
  <payer ref="0f357b45-9aa4-4453-a685-c69232e9024f" type="Retail">
    <title>Mr.</title>
    <firstname>James</firstname>
    <surname>Mason</surname>
    <company>Global Payments</company>
    <address>
      <line1>Flat 123</line1>
      <line2>House 456</line2>
      <line3>The Cul-De-Sac</line3>
      <city>Halifax</city>
      <county>West Yorkshire</county>
      <postcode>W6 9HR</postcode>
      <country code="GB">United Kingdom</country>
    </address>
    <phonenumbers>
      <home>+35312345678</home>
      <work>+3531987654321</work>
      <fax>+124546871258</fax>
      <mobile>+25544778544</mobile>
    </phonenumbers>
    <email>text@example.com</email>
    <dateofbirth>19851222</dateofbirth>
    <state>Yorkshire and the Humber</state>
    <passphrase>montgomery</passphrase>
    <vatnumber>GB 123456789</vatnumber>
    <varref>Car Part HV</varref>
    <custnum>E8953893489</custnum>
  </payer>
  <sha1hash>8d7e42bba0d9f6ca81f6106bfd74d2911fad888b</sha1hash>
</request>

Sample response

<response timestamp="20180731090859">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>OL0f0VYFQTyNG5IulhsMrg</orderid>
  <result>00</result>
  <message>Successful</message>
  <pasref>415d5e0f6ad247d3825284d1484bd7e9</pasref>
  <authcode/>
  <batchid/>
  <timetaken>1</timetaken>
  <processingtimetaken/>
  <sha1hash>5b5fec3c05fe723332bfc0a27c47d067526a3961</sha1hash>
</response>

Step 2: Card-new request

card-new-request

API requests for editing or deleting a card are the same as what is normally used for Card Storage Service calls. For more information, see the API Reference for Edit a Card and Delete a Card.

info

Now that a new payer is created, you can send a card-new request. This creates a new token, which the Ecommerce API then returns as a network token instead of an acquirer token.

If you want to receive both the network token and the acquirer token in the response, include the following field in the request and use “1” instead of the default (“0”), as shown in the sample.

//coming soon

//coming soon

//coming soon

<?xml version="1.0" encoding="UTF-8"?>
<request type="card-new" timestamp="20180614095601">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>F-2knQ0iShKK6ezfaSLh2Q</orderid>
  <card>
    <ref>10c6a2c7-be7b-a13f-12638937a012</ref>
    <payerref>0f357b45-9aa4-4453-a685-c69232e9024f</payerref>
    <number>4263970000005262</number>
    <expdate>0519</expdate>
    <chname>James Mason</chname>
    <type>VISA</type>
  </card>
  <returnfields networktoken=’1’/>
  <sha1hash>85fbaf68bb0e4fccd634facf6592b0677489709e</sha1hash>
</request>

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Element/Field	Category	Format	Type	Length	Description
order
returnfields networktoken	integer	boolean	O	1	If set to 1, returns all network token details available from our Card Storage Service, including the token and expiry. The default is 0 and does not return any network token details.

Sample response

<response timestamp="20180731090859">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>OL0f0VYFQTyNG5IulhsMrg</orderid>  
  <networkToken>374245002751005</networkToken>     
  <networkTokenExpiry>0540</networkTokenExpiry>
  <result>00</result>
  <message>Successful</message>
  <pasref>415d5e0f6ad247d3825284d1484bd7e9</pasref>
  <authcode/>
  <batchid/>
  <timetaken>1</timetaken>
  <processingtimetaken/>
  <sha1hash>5b5fec3c05fe723332bfc0a27c47d067526a3961</sha1hash>
</response>

Step 3: Create transaction - Auth

Next, we create an Auth transaction. For this step, the following request types are applicable:

Auth
Receipt-In
Credit
OTB (Open to Buy)

//coming soon

//coming soon

//coming soon

<?xml version="1.0" encoding="UTF-8"?>
<request type="auth" timestamp="20180613141207">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <channel>ECOM</channel>
  <orderid>N6qsk4kYRZihmPrTXWYS6g</orderid>
  <amount currency="EUR">1001</amount>
  <networktoken>
     <number>4242424242422841</number>
     <expdate>0100</expdate>
     <type>VISA</type>
     <cryptogram>
       <tokenvalue>oenlske2kdlfkk3jlffs333432fde3</tokenvalue> -> Max length same as authentication_value 
       <eci>1</eci>
     </cryptogram>
  </networktoken>
   <mpi>  //3Ds2 fields
    <eci>5</eci>
    <ds_trans_id>c272b04f-6e7b-43a2-bb78-90f4fb94aa25</ds_trans_id>
    <authentication_value>ODQzNjgwNjU0ZjM3N2JmYTg0NTM=</authentication_value>
    <message_version>2.2.0</message_version>
    <exempt_status>LOW_VALUE</exempt_status>
  </mpi>
  <autosettle flag="1"/>
  <sha1hash>784645637a34bayy6uhj87576lyt56766yt345ty</sha1hash>
</request>

Sample response

<response timestamp="20180731090859">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>OL0f0VYFQTyNG5IulhsMrg</orderid>  
  <networkToken>374245002751005</networkToken>     
  <networkTokenExpiry>0540</networkTokenExpiry>
  <result>00</result>
  <message>Successful</message>
  <pasref>415d5e0f6ad247d3825284d1484bd7e9</pasref>
  <authcode/>
  <batchid/>
  <timetaken>1</timetaken>
  <processingtimetaken/>
  <sha1hash>5b5fec3c05fe723332bfc0a27c47d067526a3961</sha1hash>
</response>

Step 4: Create transaction - Receipt-In

In this step, we create a Receipt-In transaction. The following request types are applicable:

Receipt-In

Step 5: Generate hash

For security reasons, you must generate a hash for the request and check it in the response. You can use the same steps as you would for our Card Storage Service. We provide a set of steps for multiple request types:

Authorization
Validate (OTB)
Credit
Create a Customer
Edit a Customer
Store a Card
Edit a Card
Delete a Card
3DS2 - Check Version, Authentication, Authorization or Dynamic Currency Conversion

For more information, see the API Reference for Card Storage (Generate Hash, Check Hash).

//coming soon

//coming soon

//coming soon

<?xml version="1.0" encoding="UTF-8"?>
<request timestamp="20231004144810" type="receipt-in">
<merchantid>test</merchantid>
<account>testaccount</account>
<orderid>95dc06eb-9633-46f3-b369-3fc9424098e6</orderid>
<channel>ECOM</channel>
<amount currency="EUR">280</amount>
<autosettle flag="0"/>
<payerref>e3d4b606-83b3-43b1-8b1f-e3bc07536e10</payerref>
<paymentmethod>92441652-93e5-4df0-85b7-db0f55c266a4</paymentmethod>
<storedcredential>
<srd>792023250179096</srd>
<type>oneoff</type>
<initiator>merchant</initiator>
<sequence>subsequent</sequence>
</storedcredential>
<sha1hash>03931a4fb797dc533a27d6d992c9d74a08b9a29d</sha1hash>
</request>

Sample response

<response timestamp="20180731090859">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>OL0f0VYFQTyNG5IulhsMrg</orderid>  
  <result>00</result>
  <message>Successful</message>
  <pasref>415d5e0f6ad247d3825284d1484bd7e9</pasref>
  <authcode/>
  <batchid/>
  <timetaken>1</timetaken>
  <processingtimetaken/>
  <sha1hash>5b5fec3c05fe723332bfc0a27c47d067526a3961</sha1hash>
</response>

[Optional] Detokenize the card

To expose the full network token, you can use the card-detokenize option, as shown in the sample. This shows the full network token number (16-19 digits) and the appropriate expiration date.

Additional fields that need to be returned include:

<networkToken> – network token (unmasked)
<networkTokenExpiry> – network token expiry date

//coming soon

//coming soon

//coming soon

<?xml version='1.0' encoding='UTF-8'?> 
<request timestamp='20230816151400' type='card-detokenise'>     
<returnfields token="1"/>     
<merchantid>NetworkTokenTest</merchantid>     
<account>ntrscc</account>     
<orderid>2300e61b-729a-4565-b4c0-2095a1251d97</orderid>         <payerref>payerNtrsTest04615</payerref>     
<ref>cardNtrsTest2571</ref>     <sha1hash>4fcfc513d102b2042f1e1a4877b9d1dcbe1b0131</sha1hash> 
</request>

Sample response

<response timestamp="20230816151400">   
<merchantid>NetworkTokenTest</merchantid>   
<result>00</result>   
<message>Successful</message>   
<timetaken>0</timetaken>   
<card> 
 <networkToken>374245002751005</networkToken>   
 <networkTokenExpiry>1225</networkTokenExpiry>     
 <type>MC</type>    
 <chname>James Mason</chname>    
 <createdate>20230713135402</createdate>    
 <status>A</status>    
 <ref>cardNtrsTest2571</ref>       
</card>   
<sha1hash>4061e6818e4bd0ff451c3445a07d6fbc3db2c785</sha1hash> 
</response>

[Optional] GET stored card

To present card metadata for the network token, include the data as shown in the sample GET request.

To receive card data on an existing token, a thirdparty-card-get is used.

//coming soon

//coming soon

//coming soon

<?xml version='1.0' ?>
<request timestamp='yyyyMMddhhmmss' type='thirdparty-card-get'>
  <merchantid>clientid</merchantid>
  <ddi>
    <payerref>payer-ref</payerref>
    <ref>payment-ref</ref>
  </ddi>
  <returnfields payerref='1' ref='1' setupdate='1' status='1' cardnumber='1' cardexpiry='1' cardtype='1' cardname='1' networktoken=’1’/>
  <sha1hash></sha1hash>
</request>

Sample response

<?xml version='1.0' encoding='ISO-8859-1'?>
<response timestamp="yyyyMMddhhmmss">
  <merchantid>clientid</merchantid>
  <result>00</result>
  <message>Successful</message>
  <list>
    <item cardexpiry="MMYY" status="A" ref="visa_test2" setupdate="1138616400" cardtype="visa" cardname="Owen O Byrne" payerref="owenobyrne" cardnumber="xxxxxxxxxxxx1307" networkTokenExpiry=’1225’ networkToken=’1213131232131’ />
  </list>
  <timetaken>0</timetaken>
  <md5hash></md5hash>
  <sha1hash></sha1hash>
</response>

Testing network tokens

Our Network Tokens - Card Storage Service is available for testing in our Sandbox environment for registered users of this developer portal. Use our test cards to try different scenarios for your application to handle. For more information, see the Network Tokens section of our Test Cards article.

Enhance your integration

Explore more functionality to enrich your application or website. For the detailed Ecommerce API specification and a full list of features, see the API Reference.

Buttons

Card Storage - API Reference

Disabled

Card Storage

Card Storage Article

Disabled

Icon Name

coin

Digital Wallets

Digital Wallets Overview

Disabled

Icon Name

wallet

Card Blocking

Disabled

Icon Name

filter-circle-xmark

Internal Title

XML API

Show Content Nav