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:

• ok Indicates everything is ok and this card can potentially be applied to a sale
• needfullcode Returned if the API requires the full barcode for some reason. Most card lookups can be uniquely found with the last 4 or 5 characters but sometimes all the codes are required, such as (1) duplicates, (2) The card has been marked to require exact verification, (3) The server is any security protection mode and requiring additional user input.
• zero The card/voucher is ok, but has $0 balance
• expired The details are correct but the voucher has expired. Expired is only returned for vouchers that are recently expired, a voucher that expired many years ago cannot be retrieved at all.
• checkpassword This status might be returned if the details were mostly correct but the password has some minor errors, such as one too many or few in a sequence or swapping of characters. If this status is returned, no other information will be returned. The server will not return this everytime, it will typically return this once and not again. Not all retailers will send this status code.

  Example. The user has given 11234, but the password is 11243

  https://..../CardInquiry/ABC123?pass=11234
  {
    "data": {
      "Cards": [
        {
          "Status": "checkpassword"
        }
      ]
    }
  }
  

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

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:

• The response information includes a UsageToken. You can pass this token into other calls such as Creating a Sale, so may not need to store the card details at all.
• 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.
• Individual retailers may impose additional conditions