Our Card Storage API offers a range of easy-to-use requests to store, charge, update and delete cards. All the functionality available where card data is captured can also be called upon in Card Storage including 3D Secure, Dynamic Currency Conversion, Credits and Open-To-Buy (OTB).
Global Payments employ a dual token system whereby each customer is assigned a unique reference (known as a Payer), each card the customer stores is then saved against that reference. Merchants can easily see all their saved customers and their respective saved cards in Ecommerce Portal.
Authorization
Once you have the card stored you can easily raise an authorization against it. In the place of collected card data you simply send the customer token (Payer) and card (Payment Method) reference, Global Payments obtains the securely stored card data from our vault and builds an authorization which we then send on to the Issuer.
Under PCI Compliance rules the security code (CVN, CVV) cannot be stored. However if in your application or website you are providing the customer the option of using a stored card, you can prompt them for their security code again and include this in the request.
To understand how to utilize Credential on File functionality in relation to this request type, see the API Reference for Credential on File.
Sample request
<?xml version="1.0" encoding="UTF-8"?>
<request type="receipt-in" timestamp="20180614095601">
<merchantid>MerchantId</merchantid>
<account>internet</account>
<channel>ECOM</channel>
<orderid>AiCibJ5UR7utURy_slxhJw</orderid>
<foreignretailer flag="false"/>
<amount currency="EUR">1001</amount>
<autosettle flag="1"/>
<payerref>03e28f0e-492e-80bd-20ec318e9334</payerref>
<paymentmethod>3c4af936-483e-a393-f558bec2fb2a</paymentmethod>
<paymentdata>
<cvn>
<number>123</number>
</cvn>
</paymentdata>
<sha1hash>f0b45f1d7aed21e7476c11c22c124f5a44a9c59a</sha1hash>
</request>Validate (OTB)
Open to Buy (OTB) allows you to check that a stored card is still valid and active without actually processing a payment against it. This is an alternative to charging the card a small amount (for example 10c) to obtain the same result.
To understand how to utilize Credential on File functionality in relation to this request type, see the API Reference for Credential on File.
This request type is supported by Global Payments. However, it is not supported by all Acquirers. For more information, contact your account manager.
<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<request type='receipt-in-otb' timestamp='20190723133011'>
<merchantid>MerchantId</merchantid>
<account>internet</account>
<orderid>N6qsk4kYRZihmPrTXWYS6g</orderid>
<foreignretailer flag="false"/>
<payerref>03e28f0e-4cf0-492e-80bd-20ec318e9334</payerref>
<paymentmethod>3c4af936-3732-483e-a393-f558bec2fb2a</paymentmethod>
<paymentdata>
<cvn>
<number>123</number>
</cvn>
</paymentdata>
<comments>
<comment id='1'>Verification Only</comment>
<comment id='2'>Mobile Channel</comment>
</comments>
<sha1hash>20ebb67e527a9ae01c4b17d55becdefe19300978</sha1hash>
</request>Credit
This request type allows you to credit an amount to a stored card. To process this request you must supply the Refund Password which you can set with a member of our support team (note: this is a different password than the Rebate Password). This password must be hashed using the SHA-1 algorithm before being added to the request. Credits requests are not sent on to the Issuer, they are placed directly into the next day's settlement file.
For security reasons this request type is not enabled by default. It must be requested by one of the main contacts on the account. The request type cannot be executed using archived Payers.
Sample request
<?xml version='1.0' encoding='UTF-8'?>
<request type='payment-out' timestamp='20180821100546'>
<merchantid>MerchantId</merchantid>
<account>internet</account>
<channel>ECOM</channel>
<orderid>Xh9cavLrTqK32lT97AeVIw</orderid>
<amount currency='EUR'>1001</amount>
<payerref>03e28f0e-492e-80bd-20ec318e9334</payerref>
<paymentmethod>3c4af936-3732-a393-f558bec2fb2a</paymentmethod>
<comments>
<comment id='1'>Returned item</comment>
<comment id='2'>Break in transit</comment>
</comments>
<refundhash>a51118f58785274e117efe1bf99d4d50ccb96949</refundhash>
<sha1hash>f0a45f1d7aed21e7476c11c22c124f5a44a9c59a</sha1hash>
</request>Create a customer
In order to store a card, the first thing we need to do is set up a customer reference (Payer). You can also choose to store address and contact details alongside it.
Sample 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>Edit a customer
Once a customer has been created you can update their name, address or contact details which can be viewed in Ecommerce Portal.
Sample request
<?xml version="1.0" encoding="UTF-8"?>
<request type="payer-edit" timestamp="20180731090859">
<merchantid>MerchantId</merchantid>
<account>internet</account>
<orderid>OL0f0VYFQTyNG5IulhsMrg</orderid>
<payer ref="0f357b45-9aa4-4453-a685-c69232e9024f" type="Subscriber">
<title>Sir</title>
<firstname>Philip</firstname>
<surname>Marlowe</surname>
<company>Pinkerton</company>
<address>
<line1>Flat 456</line1>
<line2>House 321</line2>
<line3>Basement Flat</line3>
<city>Chicago</city>
<county>DuPage County</county>
<postcode>50001</postcode>
<country code="US">United States</country>
</address>
<phonenumbers>
<home>+0013538547854</home>
<work>+0013535611177</work>
<fax>+001412459498488</fax>
<mobile>+0012554457774</mobile>
</phonenumbers>
<email>test123@example.com</email>
<dateofbirth>19740517</dateofbirth>
<state>IL</state>
<passphrase>Babette</passphrase>
<vatnumber>EU826010755</vatnumber>
<varref>REF1447741</varref>
<custnum>E473637626</custnum>
<comments>
<comment id="1">New Subscription</comment>
<comment id="2">Detective Magazine</comment>
</comments>
</payer>
<sha1hash>8d7e42bba0d9f6ca81f6106bfd74d2911fad888b</sha1hash>
</request>Store a card
Once we have our customer entity created, we can now add cards to it. This request must contain the card data to be stored, a unique reference for it and the customer reference it is to be added to. We'd always recommend processing an authorization against a card or validating it (OTB) before adding it.
Sample request
<?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>
<storedcredential>
<srd>MCCDX3FTU0212</srd>
</storedcredential>
<sha1hash>85fbaf68bb0e4fccd634facf6592b0677489709e</sha1hash>
</request>Edit a card
If your customer's card details change, for example if the expiry date is updated or they get a new card number, you can update the reference in Card Storage using this request. You can update all the card details at once or just the individual bits of data, for example just the expiry date. In the example below we are completely replacing the card with a new one.
Sample request
<?xml version="1.0" encoding="UTF-8"?>
<request type="card-update-card" timestamp="20180731090859">
<merchantid>MerchantId</merchantid>
<account>internet</account>
<orderid>PNjvzlWpS4WWv4V6yPoEuw</orderid>
<card>
<ref>3c4af936-3732-f558bec2fb2a</ref>
<payerref>03e28f0e-40-492e-20ec318e9334</payerref>
<number>5425230000004415</number>
<expdate>1020</expdate>
<chname>Philip Marlowe</chname>
<type>MC</type>
</card>
<storedcredential>
<srd>MCCDX3FTU0212</srd>
</storedcredential>
<sha1hash>403b6d13bf2bfb4e69cac96096a6cd7a44436b29</sha1hash>
</request>Delete a card
If you want to remove a card from Card Storage you can send us a Card Delete request.
There is no ability to UNDO this action so please use with caution.
<?xml version='1.0' encoding='UTF-8'?>
<request type='card-cancel-card' timestamp='20180821100546'>
<merchantid>Merchant ID</merchantid>
<account>internet</account>
<orderid>V8-JEKaJSPqN28vCs91Gxw</orderid>
<card>
<ref>3c4af936-3732-f558bec2fb2a</ref>
<payerref>03e28f0e-40-492e-20ec318e9334</payerref>
</card>
<comments>
<comment id='1'>Subscription Expiry</comment>
<comment id='2'>Customer panel</comment>
</comments>
<sha1hash>6bd2521179a61b721e4becc7afd076f6bfd24d46</sha1hash>
</request>3DS2 - Check Version
To start the 3D Secure authentication process, the first step is to check the version that the card supports. To carry out authentication on a stored card rather than a full PAN is listed below. Global Payments maintains an up-to-date database of BIN ranges and the versions of 3D Secure they support.
If the card is enrolled in 3D Secure 2, the exact version will be returned (2.x.x) along with the necessary URL to facilitate the gathering of device data by the Issuer ACS (if supported). If the card is not enrolled, just the Server Transaction ID will be returned.
Sample request
curl https://api.sandbox.globalpay-ecommerce.com/3ds2/protocol-versions
-H "Content-type: application/json"
-H "Authorization: securehash fb2c8058ce4d03bd66e610fce8a476db722b0f9a"
-X POST
-d '{
"request_timestamp": "2019-04-26T10:16:10.154248",
"merchant_id": "MerchantId",
"account_id": "internet",
"payer_reference": "e193c21a-ce64-4820-b5b6-8f46715de931",
"payment_method_reference": "10c3e089-fa98-4352-bc4e-4b37f7dcf108",
"method_notification_url": "https://www.example.com/dsNotificationUrl"
}'3DS2 - Authentication
Assuming you have already gathered the relevant device data and (conditionally) the ACS Method URL process is complete, your application can now kick-off 3D Secure 2 authentication. We’ve outlined below the required and recommended data to be sent to the authentication endpoint. This includes the billing and shipping details of the customer, at least one phone number, the device data and the transaction details (amount, currency and so on).
You must also include your application’s Challenge Notification URL, a flag indicating the outcome from the ACS Method URL (or whether it took place at all) and a link to an About or Contact page on your website with customer care information.
Sample request (mandatory and recommended fields)
In this example, we’re only passing mandatory fields along with some recommended ones. The more optional fields you send and data you supply, the more likely the authentication for the transaction will be frictionless. For the full list of optional fields and the allowed values in each, see the API Reference for 3D Secure 2.
curl https://api.sandbox.globalpay-ecommerce.com/3ds2/authentications
-H "Content-type: application/json"
-H "Authorization: securehash cdf7f92bb0d80d20ba73034ee7ad2dada9d91825"
-X POST
-d '{
"request_timestamp": "2019-04-26T10:19:32.552327",
"authentication_source": "BROWSER",
"authentication_request_type": "PAYMENT_TRANSACTION",
"message_category": "PAYMENT_AUTHENTICATION",
"challenge_request_indicator":"NO_PREFERENCE",
"server_trans_id": "af65c369-59b9-4f8d-b2f6-7d7d5f5c69d5",
"merchant_id": "MerchantId",
"account_id": "internet",
"card_detail": {
"payer_reference": "e193c21a-ce64-4820-b5b6-8f46715de931",
"payment_method_reference": "10c3e089-fa98-4352-bc4e-4b37f7dcf108"
},
"order": {
"amount": "1001",
"currency": "USD",
"id": "3400dd37-101d-4940-be15-3c963b6109b3",
"address_match_indicator": false,
"shipping_address": {
"line1": "Apartment 852",
"line2": "Complex 741",
"line3": "House 963",
"city": "Chicago",
"postal_code": "50001",
"state": "IL",
"country": "840"
}
},
"payer": {
"email": "james.mason@example.com",
"billing_address": {
"line1": "Flat 456",
"line2": "House 456",
"line3": "Unit 4",
"city": "Halifax",
"postal_code": "W5 9HR",
"country": "826"
},
"mobile_phone": {
"country_code": "44",
"subscriber_number": "7123456789"
}
},
"challenge_notification_url": "https://www.example.com/challengeNotificationUrl",
"method_url_completion": "YES",
"browser_data": {
"accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
"color_depth": "TWENTY_FOUR_BITS",
"ip": "123.123.123.123",
"java_enabled": "true",
"javascript_enabled": "true",
"language": "en-US",
"screen_height": "1080",
"screen_width": "1920",
"challenge_window_size": "FULL_SCREEN",
"timezone": "0",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.110 Safari/537.36"
},
"merchant_contact_url": "https://www.example.com/about"
}'3DS2 - Authorization
If you are processing the payment with Global Payments, now that the 3D Secure process is complete, and depending on the ECI value returned, we can proceed to authorization while including the authentication data. The transaction will be processed as normal and may be successful or declined based on standard criteria; sufficient funds, correct security code entered and so on.
Sample request
<?xml version="1.0" encoding="UTF-8"?>
<request type="receipt-in" timestamp="20180614095601">
<merchantid>MerchantId</merchantid>
<account>internet</account>
<channel>ECOM</channel>
<orderid>AiCibJ5UR7utURy_slxhJw</orderid>
<amount currency="EUR">1001</amount>
<autosettle flag="1"/>
<payerref>03e28f0e-492e-80bd-20ec318e9334</payerref>
<paymentmethod>3c4af936-483e-a393-f558bec2fb2a</paymentmethod>
<paymentdata>
<cvn>
<number>123</number>
</cvn>
</paymentdata>
<mpi>
<eci>5</eci>
<ds_trans_id>c272b04f-6e7b-43a2-bb78-90f4fb94aa25</ds_trans_id>
<authentication_value>ODQzNjgwNjU0ZjM3N2JmYTg0NTM=</authentication_value>
<message_version>2.1.0</message_version>
</mpi>
<sha1hash>f0b45f1d7aed21e7476c11c22c124f5a44a9c59a</sha1hash>
</request>Dynamic Currency Conversion
Use this request to initiate the DCC (Dynamic Currency Conversion) process and determine if there is a currency conversion opportunity with a stored card.
The Order ID used in this request must also be used in the subsequent Authorization.
Sample request
<?xml version="1.0" encoding="UTF-8"?>
<request type="realvault-dccrate" timestamp="20180731152924">
<merchantid>MerchantId</merchantid>
<account>internet</account>
<orderid>4OBdkOuZRPCXarMcaU7ywQ</orderid>
<amount currency="EUR">1001</amount>
<payerref>03e28f0e-4cf0-80-20ec318e9334</payerref>
<paymentmethod>3c4af936-483ea33-f558bec2fb2a</paymentmethod>
<dccinfo>
<ccp>Currency Conversion Processor</ccp>
<type>1</type>
</dccinfo>
<sha1hash>30596f1d07084d533547c3cbf860d5b24f7034a5</sha1hash>
</request>Credential on File
In this guide, we cover the various data elements that need to be passed in order for merchants to manage their own implementation of Credential on File (COF) and Merchant Initiated Transactions (MITs) using our API solution.
For a full description of COF fields and use cases, see our main Credential on File article.
Global Payments Card Storage
If you're using Global Payments Card Storage for one-off and recurring transactions, if the first transaction is flagged correctly, we will automatically manage COF, MIT, and Transaction Grandfathering for all subsequent transactions.
For any payment types—regardless of whether you're using our solution or a third-party's or are storing card details yourself—you can manage all of the messaging yourself. For a complete guide on how to do this, see the examples below.
Supported request types
COF and MIT can be used in the Authorization, Validation (Open-to-Buy/OTB), Charge a Stored Card (Receipt-in), and Validate a Stored Card (Receipt-In-OTB) request types.
Sample request
<?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>
<card>
<number>4263970000005262</number>
<expdate>0425</expdate>
<chname>James Mason</chname>
<type>VISA</type>
<cvn>
<number>123</number>
<presind>1</presind>
</cvn>
</card>
<autosettle flag="1"/>
<!-- Begin CoF Fields -->
<storedcredential>
<type>oneoff</type>
<initiator>cardholder</initiator>
<sequence>first</sequence>
<srd></srd>
</storedcredential>
<!-- End CoF Fields -->
<sha1hash>87707637a34ba651b6185718c863abc64b673f20</sha1hash>
</request>Generate hash
Follow the steps in this section to build the request security hash, concatenate the specified fields and hash them using the SHA-1 algorithm, concatenate the hashed string with your Shared Secret, hash it again, and add the resulted string to the request.
In addition to SHA-1, you can also generate your hash using SHA-256. The resulting hash should be placed in the <sha256hash> tag instead of the <sha1hash> tag. For more information, contact our support team at ecomsupport@globalpay.com.
Build the Request hash
Use the dropdown below to select a request type: Authorization, Validate (OTB), Credit, Create a Customer, Edit a Customer, Store a Card, Edit a Card, Delete a Card, 3DS1 - Verify Enrollment, 3DS2 - Check Version, 3DS2 - Authentication, 3DS2 - Authorization or Dynamic Currency Conversion. After making a selection, the steps on how to build the request hash for that type are provided.
Check hash
Follow the steps in this section to build the response security hash, concatenate the specified fields and hash them using the SHA-1 algorithm, concatenate the hashed string with your Shared Secret, hash it again, and add the resulted string to the request.
Check the Response hash
Use the dropdown below to select a request type: Authorization, Validate (OTB), Credit, Create a Customer, Edit a Customer, Store a Card, Edit a Card, Delete a Card, 3DS1 - Verify Enrollment or Dynamic Currency Conversion. After making a selection, the steps on how to check the response hash for that type are provided.