Retail API
Documentation
Online POS
More

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 PublicNo
Query parameters obeyed
Filterscard pass
Response formatsJSON, XML, binary
PriceStandard
SecurityHigh
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.

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.

Retrieving Card Details. Direct from Client Browser

Website«--»Client Browser«--»Fieldpine.com API

If you are retrieving the details directly from the end users browser or app, you can create a call and directly fetch the details. As your call to Fieldpine requires an Api-Key, the key you use will be visible to end users. You should not use a general purpose api-key for this, and should request an api-key that can only perform card inquiries.

Example

var card = document.getElementById("cardno").value;
if (card.length < 4) {
	alert("Please enter at least the last 4 digits of the barcode");
	return;
}
var pass = document.getElementById("cardpass").value;
if (pass.length < 4) {
	alert("Please enter the password on the back of the card");
	return;
}

var req = null;
if (window.XMLHttpRequest)  req = new XMLHttpRequest(); 
else if (window.ActiveXObject)  req = new ActiveXObject("Microsoft.XMLHTTP"); 
else req = new XMLHttpRequest(); 

if (req) {
	req.open("GET", "/RetailAPI_1_2_3_4/request/card_inquiry.json?filter=card(" +encodeURIComponent(card) +")&filter=pass(" +encodeURIComponent(pass) +")" , true);
	req.setRequestHeader("X-Api-Key", "YOUR-KEY-GOES-HERE");
	req.send(null);
}

When the Fieldpine servers receive a request directly from the browser they broadly perform the following checks

  1. Verify the API key is valid
  2. Velocity check this users browser and IP address to verify they are not attempting to bulk scan for cards
  3. Verify that the request rate for this retailer from all sources is not exceeding thresholds. If this rate is too high then all requests for card information may be restricted.

Retrieving Card Details. Via your Own Website

Client Browser«--»Website«--»Fieldpine.com API

If you prefer, you can have your webserver perform the request for card information rather than the end client browser. This means that your API key is not exposed and the Fieldpine servers can be more certain they are talking to an authorised application

When calling from your website, the API requires some details about the end user making the request:

In order to send this additional information, you will probably need to perform a POST request rather than a GET

Failure to send the above additional information, or knowingly sending false information will result in more restrictions being applied, so the API may not function at all. To be clear, it is a requirement that the above information is sent with each request to this endpoint. The various restrictions applied on this API cannot be removed or reduced. This Card Inquiry API is not suitable for situations where no security or low security is desired.