For AI agents: the complete documentation index is at /llms.txt, and the full text of every page is at /llms-full.txt. Most pages are also available as Markdown by adding .md to the URL.

Network Tokens - Guide

Learn how to use a network token for card storage

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, third-party get requests, and detokenizing a card. We also provide information on using network tokens in Auth transactions and a standalone option for merchants who don’t store cards with us.

The steps in this guide are the same whether you integrate via direct API or our Hosted Payment Page.

For more information on network tokens, see our Overview.

Sample payer variables

$f_name = "Jason";
$s_name = "Mason";
$city = "Leicester";
$county = "Leicestershire";
$country = "United Kingdom";
$email = "john@mason.com";

Transaction variables

$card_num = "*************"; //card number
$ch_name = "**** *****"; // cardholder name
$amount = "***";
$currency = "***";
$expdate = "****"; // exp date
$type = "****"; //card type

Account variables

$merchantid = "***"; //  merchant id
$account = "***"; // account name
$orderid = "***"; // can be randomly generated
$payerref = "***"; // customer id
$cardref = "***"; // card id
$token = "***"; // pmt-token
$ref = "***"; // can be randomly generated
$srd = "***"; // can be randomly generated

Step 1: Create a payer

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

Sample request

Sample response

<response timestamp="20240416162802">
  <merchantid>MerchantId</merchantid>
  <account>AccountName</account>
  <orderid>20240416172802-183</orderid>
  <result>00</result>
  <message>Successful</message>
  <pasref>84ec146a1fad41b383d1037248f70fcb</pasref>
  <authcode/>
  <batchid/>
  <timetaken>0</timetaken>
  <processingtimetaken/>
  <sha1hash>e25da6f323b492ebb51e8fd29c543d2c736f7588</sha1hash>
</response>

Step 2: Create a new card

Now that a new payer is created, you can send a card-new request. This creates a new token, which the API then returns as a network token in addition to the acquirer token.

If you want to receive both the network token and the acquirer token in the response, add the following returnfields in the request. However, adding returnfields is not necessary for network-token creation as the token is created regardless.

Sample request

Sample response

<response timestamp="20240416162802">
<merchantid>merchantid</merchantid>
 <account>AccountName</account>
  <orderid>20240416173729-931</orderid>
  <networktoken>2222690419268210</networktoken>
  <networktokenexpiry>0527</networktokenexpiry>
  <result>00</result>
  <message>Successful</message>
  <pasref>852011055bd64f84be5ae3c63800c364</pasref>
  <authcode/>
  <batchid/>
  <timetaken>0</timetaken>
  <processingtimetaken/>
  <sha1hash>5222067c6ffd59866c018fefbc64c4d0296b79f5</sha1hash>
  <token>PMT_445ba23e-a46d-4fad-9937-41891823bd3e</token>
</response>

Third-party card request

Using the thirdparty-card-get request exposes a number of data points, including the network token and expiration date, among others.
The entire list of available returnfields is included in the sample request below. You can customize the request based on your needs.

Sample response

<response timestamp="20240416164256">
  <merchantid>MerchantId</merchantid>
  <result>00</result>
  <message>Successful</message>
  <list>
    <item 
    token="PMT_db4c9acc-4614-4dc3-afbd-a6cf8e90e8bf"
    status="A" 
    setupdate="1702032172"
    ref="103352"
    payerref="20231206343217-968"
    cardtype="MC"
    cardnumber="xxxxxxxxxxxx0055"
    cardname="James Mason"
    cardexpiry="1225"
    networktoken="2222690419310194"
    networktokenexpiry="0527"
     />
  </list>
  <timetaken>0</timetaken>
  <md5hash>ba41c9f6cf2f5f7b25b2f09954556b5d</md5hash>
  <sha1hash>fc72c210fe83351bb8c7d174c7b1e265e8a5cafe</sha1hash>
</response>

Detokenize

Detokenizing the card will return the token requestor id (TRID) and scheme token requestor id (STRID). This makes it possible for you to use multiple payment service providers (PSPs) if desired.

Sample response

<response timestamp="20240416164105">
  <merchantid>MerchantId</merchantid>
  <result>00</result>
  <message>Successful</message>
  <timetaken>0</timetaken>
  <card>
    <number>370295069663597</number>
    <expdate>1225</expdate>
    <type>AMEX</type>
    <chname>James Mason</chname>
    <createdate>20240107162832</createdate>
    <status>A</status>
    <ref>ref-8636</ref>
    <networktoken>374245002751005</networktoken>
    <networktokenexpiry>0540</networktokenexpiry>
    <tokenrequestorid>6c2b9b4d-5ff6-49dc-b449-2846f3e96f13</tokenrequestorid>
    <schemetokenrequestorid>37936260501</schemetokenrequestorid>
  </card>
  <sha1hash>4d6ebf768c94c1a7810235943cae595d930efb6b</sha1hash>
</response>

Auth MIT and CIT

It’s possible to use network tokens in place of card information in Auth transactions by substituting the token for the card value in merchant-initiated transactions (MITs) or customer-initiated transactions (CITs). This is not necessary, however, as the card value will be swapped out for network tokens if one exists.

Card Auth MIT

Sample response

<response timestamp="20240923123808">
  <merchantid>merchantid</merchantid>
  <account>account</account>
  <orderid>20240923133808-433</orderid>
  <authcode>123456</authcode>
  <result>00</result>
  <cvnresult>U</cvnresult>
  <avspostcoderesponse>U</avspostcoderesponse>
  <avsaddressresponse>U</avsaddressresponse>
  <batchid>1441120</batchid>
  <message>[ test system ] Authorised</message>
  <pasref>17270914888354845</pasref>
  <timetaken>0</timetaken>
  <authtimetaken>0</authtimetaken>
  <acquirerresponse><![CDATA[ ]]></acquirerresponse>
  <srd>hNIGGCbubyxF9Zoi</srd>
  <cardissuer>
    <commercial/>
    <cardtype/>
    <country/>
    <countrycode/>
    <bank/>
  </cardissuer>
  <sha1hash>e69421311a393b334c004de1bb678aa591ca0c19</sha1hash>
</response>

Card Auth - CIT

Sample request

Sample response

<response timestamp="20240417114051">
  <merchantid>MerchantId</merchantid>
 <account>AccountName</account>
  <orderid>20240417124050-953</orderid>
  <authcode>123456</authcode>
  <result>00</result>
  <cvnresult>U</cvnresult>
  <avspostcoderesponse>U</avspostcoderesponse>
  <avsaddressresponse>U</avsaddressresponse>
  <batchid>1381517</batchid>
  <message>[ test system ] Authorised</message>
  <pasref>17133504510469551</pasref>
  <timetaken>0</timetaken>
  <authtimetaken>0</authtimetaken>
  <srd>9Mcd3n3yy2gzvgPi</srd>
  <sha1hash>57c99b6c31d6f26107f6ead01cd4b575fd65854e</sha1hash>
</response>

Standalone network tokens

Our Network Tokens solution can be used even if you're not storing cards with us. This makes it possible for you to use multiple PSPs if desired.

Sample Sandbox request URL

curl --location 'https://api.sandbox.globalpay-ecommerce.com/card-storage/merchants/merchantId/network-tokens/accountName' \
--header 'Authorization: securehash 91e9063aed61da6f09d8f21d7f537585a0e72e4f' \
--header 'x-realex-application-id: apigee' \
--header 'x-api-key: 030a8944-f976-44d8-a774-f8152c5f13f7' \
--header 'Content-Type: application/json' \
--data '{
    "pan": "{{cardNumber}}",
    "expiration_date": "{{cardExpDate}}",
    "card_scheme":"{{cardType}}"
}

Hash value

clientId + "." + accountName + "." + panNumber

Sample response

{
    "merchant_id": "merchantId",
    "account": "accountname",
    "network_token": "4895370016970953",
    "expiration_date": "1136",
    "status": "ACTIVE"
}

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 our test cards for Network Tokens.

Enhance your integration

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

Card Storage - API Reference

See the full API specification for card storage.

Card Storage

Securely store card data with no added PCI DSS requirements.

Digital Wallets

Help customers pay securely with just a scan, tap, or click.

Card Blocking

Limit what card types to accept for payment or storage.

Policies

Connect

Additional Resources

Network Tokens - Guide

Sample payer variables

Transaction variables

Account variables

Step 1: Create a payer

Sample request

Sample response

Step 2: Create a new card

Sample request

Sample response

Third-party card request

Sample response

Detokenize

Sample response

Auth MIT and CIT

Card Auth MIT

Sample response

Card Auth - CIT

Sample request

Sample response

Standalone network tokens

Sample Sandbox request URL

Hash value

Sample response

Testing network tokens

Enhance your integration

Card Storage - API Reference

Card Storage

Digital Wallets

Card Blocking