Our Card Storage solution is designed to enhance your customer's experience while alleviating your PCI Compliance requirements. We store all of the sensitive cardholder data while your application/website can simply store the customer references. You can then call on the HPP to allow your customer to pay with one of their saved cards, they can also update and delete them. It is also possible to raise payments against stored cards using our API.
Card Storage is a chargeable service. Please consult your account manager if you wish to avail of this service.
Card Storage uses a dual token system. Each customer is assigned a unique token reference called a Payer. Each card saved is assigned a Payment Method reference. These references can be supplied by your application/website or can be automatically generated by Global Payments.
In this section, we'll outline how to store cards using the HPP and how to make use of the various Card Storage & Management features.
Create a payer and store a card
In order to enable Card Storage we simply add three fields to our HPP request. You may also choose to supply your own references for the customer and card. If you don't want to charge the card before storing it, you can process an Open-To-Buy (OTB) transaction. This request type checks that it is a valid and active card and that the customer provided the correct security code, address details and 3D Secure authentication. We can also choose to provide the option to the customer to save their card or save it automatically.
The customer and card references will only be created and returned in the response if the authorization or OTB are successful.
Sample Request
<form action="https://pay.sandbox.realexpayments.com/pay" method="POST" target="iframe">
<input type="hidden" name="TIMESTAMP" value="20180613141207">
<input type="hidden" name="MERCHANT_ID" value="MerchantId">
<input type="hidden" name="ACCOUNT" value="internet">
<input type="hidden" name="ORDER_ID" value="N6qsk4kYRZihmPrTXWYS6g">
<input type="hidden" name="AMOUNT" value="1999">
<input type="hidden" name="CURRENCY" value="EUR">
<input type="hidden" name="AUTO_SETTLE_FLAG" value="1">
<input type="hidden" name="HPP_VERSION" value="2">
<input type="hidden" name="MERCHANT_RESPONSE_URL" value="https://www.example.com/responseUrl">
<!-- Card Storage Fields -->
<input type="hidden" name="CARD_STORAGE_ENABLE" value="1">
<input type="hidden" name="OFFER_SAVE_CARD" value="1">
<input type="hidden" name="PAYER_EXIST" value="0">
<input type="hidden" name="PAYER_REF" value="376a2598-412d-4805-9f47-c177d5605853">
<input type="hidden" name="PMT_REF" value="ca46344d-4292-47dc-9ced-e8a42ce66977">
<!-- End Card Storage Fields -->
<input type="hidden" name="SHA1HASH" value="308bb8dfbbfcc67c28d602d988ab104c3b08d012">
<input type="submit" value="Click here to purchase">
</form>Sample Response
If the card is authorized or validated successfully, the response from HPP will contain the various Card Storage references we need. Since we're using HPP Card Management, we only need to store the customer reference for the next step.
Alternatively, you can use the HPP just to store the card and then raise payments against it using our API. For that you'll need both the customer and the card references. We'll also return the card type, expiry date and the cardholder name entered on the HPP for your own reference along with the first six and last four digits of the card number.
All your stored customers can be viewed in Ecommerce Portal in the Customers section, along with the cards saved against them. Here you can manually charge a stored card or set up a scheduled payment.
<!-- Additional Response Fields -->
[REALWALLET_CHOSEN=1,
PAYER_SETUP=00,
PAYER_SETUP_MSG=Successful,
SAVED_PAYER_REF=376a2598-412d-4805-9f47-c177d5605853,
PMT_SETUP=00,
PMT_SETUP_MSG=Successful,
SAVED_PMT_TYPE=VISA,
SAVED_PMT_REF=cd46344a-4292-47dc-9ced-e8a42ce66977,
SAVED_PMT_DIGITS=426397xxxx5262,
SAVED_PMT_EXPDATE=1025,
SAVED_PMT_NAME=James Mason]Display stored cards to the customer
Once we have our customer created, for future transactions we can now send this Payer reference to the HPP which will present all of their stored cards to them. They can choose to proceed with a previously stored card or use a new card. The transaction is then processed as normal using whatever services you have enabled; 3D Secure, Fraud Management, DCC and so on. If they choose to pay with a new card, this can also be saved via the HPP to Card Storage for future use.
If a saved card has expired or is due to expire (within 3 months), the customer will have the choice to update the expiry date or delete the card. The references of any cards edited or deleted will also be returned in the response.
Sample Request
<form action="https://pay.sandbox.realexpayments.com/pay" method="POST" target="iframe">
<input type="hidden" name="TIMESTAMP" value="20180613110737">
<input type="hidden" name="MERCHANT_ID" value="MerchantId">
<input type="hidden" name="ACCOUNT" value="internet">
<input type="hidden" name="ORDER_ID" value="N6qsk4kYRZihmPrTXWYS6g">
<input type="hidden" name="AMOUNT" value="19.99">
<input type="hidden" name="CURRENCY" value="EUR">
<input type="hidden" name="SHA1HASH" value="308bb8dfbbfcc67c28d602d988ab104c3b08d012">
<input type="hidden" name="AUTO_SETTLE_FLAG" value="1">
<input type="hidden" name="HPP_VERSION" value="2">
<input type="hidden" name="MERCHANT_RESPONSE_URL" value="https://www.example.com/responseUrl">
<!-- Card Storage Fields -->
<input type="hidden" name="HPP_SELECT_STORED_CARD" value="376a2598-412d-4805-9f47-c177d5605853">
<input type="hidden" name="PAYER_EXIST" value="1">
<input type="hidden" name="OFFER_SAVE_CARD" value="1">
<!-- End Card Storage Fields -->
<input type="submit" value="Click here to Purchase">
</form>Sample Response
If the customer chooses to use a new card, the fields you receive back in the response will be the same as those we outlined in the first part of this guide. If they complete the transaction with a previously stored card or they edit or delete a card, additional response fields will be returned.
<!-- Additional Response Fields -->
[HPP_CHOSEN_PMT_REF=ca46344d-4292-47dc-9ced-e8a42ce66977,
HPP_EDITED_PMT_REF=078c6d4a-03df-4716-a8ae-dd266f3d041a,
HPP_DELETED_PMT_REF: f80d04d7-bb27-4bf2-a8ac-571deb5222e9]Credential on File
To override the default Credential on File (COF) behavior of the Hosted Payment Page (HPP), you will need to pass the Type, Initiator, and Sequence fields. The SRD field is optional.
For a full description of COF fields and use cases, see our main Credential on File article.
The Type, Initiator and Sequence fields must be populated to be considered valid. If any of these fields are not populated, it will be considered invalid and an error will occur.
Supported Request Types
COF can be used in Authorization and Validation (Open-to-Buy/OTB) with Card Storage.
Sample Request
<form action="https://pay.sandbox.realexpayments.com/pay" method="POST" target="iframe">
<input type="hidden" name="TIMESTAMP" value="20180613141207">
<input type="hidden" name="MERCHANT_ID" value="MerchantId">
<input type="hidden" name="ACCOUNT" value="internet">
<input type="hidden" name="ORDER_ID" value="N6qsk4kYRZihmPrTXWYS6g">
<input type="hidden" name="AMOUNT" value="1999">
<input type="hidden" name="CURRENCY" value="EUR">
<input type="hidden" name="AUTO_SETTLE_FLAG" value="1">
<input type="hidden" name="HPP_VERSION" value="2">
<input type="hidden" name="MERCHANT_RESPONSE_URL" value="https://www.example.com/responseUrl">
<!-- Card Storage Fields -->
<input type="hidden" name="CARD_STORAGE_ENABLE" value="1">
<input type="hidden" name="OFFER_SAVE_CARD" value="1">
<input type="hidden" name="PAYER_EXIST" value="0">
<input type="hidden" name="PAYER_REF" value="376a2598-412d-4805-9f47-c177d5605853">
<input type="hidden" name="PMT_REF" value="ca46344d-4292-47dc-9ced-e8a42ce66977">
<!-- End Card Storage Fields -->
<!-- Credential on File Fields -->
<input type="hidden" name="HPP_STORED_CREDENTIAL_TYPE" value="oneoff">
<input type="hidden" name="HPP_STORED_CREDENTIAL_INITIATOR" value="cardholder">
<input type="hidden" name="HPP_STORED_CREDENTIAL_SEQUENCE" value="first">
<!-- End Credential on File Fields -->
<input type="hidden" name="SHA1HASH" value="308bb8dfbbfcc67c28d602d988ab104c3b08d012">
<input type="submit" value="Click here to Purchase">
</form>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: "Create a payer and store a card" or "Display stored cards to the customer." 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: "Create a payer and store a card" or "Display stored cards to the customer." After making a selection, the steps on how to check the response hash for that type are provided.