Library OpenApi Overview About these APIs Architecture Authentication Error Responses Locating a Server Sessions Design Guides Guides and Hints Examples Pricing for Websites Accepting Vouchers PreAuth Payment Replication Common Apis The most used APIs Create New Sale Payment Completion Multiple Locations Delivery Addresses Create New Sale v2 Customers Locations Products Staff WebHooks eCommerce Apis These APIs are often used with eCommerce website integrations Get Pricing Card Inquiry Report & Analysis Grouped or analysed report data. Typically used to build reports and dashboards Today Login Access Pinboard ReportRequest Advanced Information More indepth information Caller Handling HTTP Protocol Bulk Data Downloads Document Uploading RetailConfig Under Development Details of APIs that will be available shortly. Documentation provided is for early adopters Get Receipt

Card Inquiry

Looks up loyalty and prepay cards issued to customers. Verifies passwords, returns balances

Retailers often issue various forms of cards and discount coupons to customers. This api allows you to capture a card number, verify it is valid and obtain any additional information about the card such as expiry date. The API works over all customer focused promotions that use a barcode or coupon code. If an application uses this API to retrieve card information then those cards can be applied to SaleCreate to reduce the potential for errors.

This is a high security api as it can potentially verify the existence and value of stored value cards. If you are using this api on a public facing website there can be some additional restrictions over and above the normal security requirements. More on Authentication

The response information includes the field "UsageToken". This value can be passed into the Create Sale API as part of the payment information. The token is designed to be safer to store than card numbers and passwords, but should still be carefully protected. UsageTokens have a finite lifetime and will be invalidated if not used. A UsageToken is not a reservation or claim over any monetary amount, it is only confirmation that the card was successfully retrieved.

For each card record returned a Status field will be retured as well:

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 OpenAPI 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 typically 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.

If the result of the /CardInquiry request returns a status of "needfullcode", you will need to prompt for the full voucher code. This should be rare, and will appear less often with the more characters you collect initially.

Validating the Card, direct from client Browser

The simplest way to validate a card is to directly call this API from the client browser. This ensures that API receives all information it needs to make an intelligent security decision. The response will include a "UsageToken" that you can use henceforth to refer to this voucher, saving you from needing to save passwords.

When calling directly from the browser, you still require an ApiKey. As these are easily retrievable by snoopers the API key you use will be low security. The ApiKey itself will actually contain the words "VisibleKey" as part of it.

Validating the Card, via your WebServer

If you prefer you can pass the captured details to your webserver, where some server side logic you provide validates against the /CardInquiry Api. This does not expose an ApiKey to the client but can require slightly more effort from the web developer.

Advanced Notes

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