Card Inquiry API

Returns full details for barcoded prepay cards or vouchers. This permits an external application to retrieve information about cards and the current balances available. As this API can potentially be exposing sensitive information there is a higher level of requirements on callers than other APIs.

/request/card_inquiry

Validates a prepay or discount voucher card number and returns the available balance and other details. This API is typically used by eCommerce websites to allow customers to pay online using prepay cards issued instore.

Attributes
Typically Public	No
Query parameters obeyed
Filters	card pass
Response formats	JSON, XML, binary
Price	Standard
Security	High
Live Example (login required)	/online/ref/card_inquiry.htm

/RetailAPI_1_2_3_4/request/card_inquiry.json?filter=card(34513)&filter=pass(abc) 
	View JSON Sample (Prepay Card)
	View XML Sample (Prepay Card)

/RetailAPI_1_2_3_4/request/card_inquiry.xml?filter=card(91283)&filter=pass(47d) 
	View JSON Sample (Discount Voucher)
	View XML Sample (Discount Voucher)

Where this endpoint is called from a web server on behalf of a client browser (ie a shopper has entered their card# and password into a web page, and the web server processing that web page issues the call to the RetailAPI endpoint), then the API call will generally require details about the user session in order to implement anti fraud measures. The information required is all HTTP headers from a request (any recent request is acceptable, the requested URL is not important) and details of the remote users IP address.

How to Capture Card Details

A prepay card or a discount voucher will have a long barcode that uniquely identifies it and a corresponding password. Rather than requiring the user enter all the characters in the barcode, they need only enter the last 4 or 5 characters of the barcode, and the password. The more characters of the barcode you require users to enter the more secure and accurate overall requests will be, but at a cost of greater user inconvenience.

For example, you might create a form such as

Enter the last 4 digits of your card number

Enter the card password (printed on back)

You may of course capture the full barcode if you wish or if you are using a barcode scanner of some kind.

Once you have the card you need to validate these against the fieldpine API for the retailer. There are several options

Capture the card details on the browser and use you server to interact with fieldpine api servers. This is a recommended solution. More details

Advanced Notes

The API is CORS enabled on fieldpine api servers. For unauthenticated requests it is heavily restricted with low traffic limits, so is not suitable for production use, except for very small situations. To authenticate your CORS request requires your server to request a single use token, which the client must provide.

You should put serious consideration into how you handle the passwords in your server. We understand that you probably need to store them in a database for a period of time, so suggest the following:

Store the password using a reverisable encryption scheme, such as a subsitution cipher. While these offer no real protection and are easy to break, they do at least require slightly more work than simply downloading your database.
Erase the password stored in your database as soon as you know longer need it. Typically you will need the card#/password to create a new sale for an eCommerce site, once the sale has been acknowledged in the server you no longer need to retain the password and could erase it.
Try not to store the password in log files and diagnostic files.