Observations

Here are a few miscellaneous notes, based mostly on past integrations, where integrators found some aspect of the service confusing or encountered a specific difficulty:

  1. The value in the requestID field in your request message should always be unique, and this includes cases where a single transaction from your perspective involves multiple calls to the Savvy API, for example if your redemption consists of a Balance Enquiry followed by a Redeem. In this case the Balance Enquiry and Redeem should have different Request IDs

  2. The amount in a Balance Enquiry request should only ever contain a zero amount. Including a non-zero amount has the potential to cause unexpected behaviour.

  3. When a reversal request is received, the Savvy platform attempts to locate the transaction to be reversed based on the auth code and a number of other elements. In the case where the Savvy platform determines that the reversal is a duplicate of a reversal that has already been processed, the reversal will not be processed a second time, but responseCode 0 will be returned with a message in the responseText element advising that the transaction has already been reversed

  4. For a balance enquiry the responseText element will contain the expiry date of the card if an expiry date has been set

  5. Transactions that do not issue a card pin to the caller will place the value -1 in the cardPin element as a return value

  6. An attempt to debit a card having a zero balance will not fail outright, but will return a response code of 30 (partial debit). This is correct behaviour, there is no response code for insufficient balance as the transaction is specified to take the balance of the card and return code 30. It was considered unnecessary to have a different response code for a zero balance

  7. If the card has a maximum balance limitation defined then attempting to Load from ’60.00’ to ‘110.00’ with a ’50.00’ top-up fails, as expected, but the card-balance is returned as ’90.00’ (the maximum balance value) rather than just failing outright and not updating the balance at all. The response code 52 is returned to indicate this and the caller must decide if this is desirable. If it is not desirable then a reversal message will undo the load. Note: This is the behaviour in non-Hard Decline mode, when Hard Decline mode is in use the then responseCode 52 is not relevant.

  8. It is not possible to change the anti-fraud limits for a card through this interface, these are parameters set through the merchant portal for a merchant chain by the administrator and enforced by the online gateway interface

  9. Response code 16 (locked card) is only returned for transactions where PIN validation occurs. It will not be returned in response to balance enquiry without PIN or redeem without PIN

  10. Any kind of ‘batching’ where multiple transactions are stored by the integrator and submitted to Savvy at the same time is not recommended and can lead to unexpected results. Transactions should be attempted one at a time as and when they happen

  11. Since the web services are invoked by URL, clients relying on DNS for name resolution are potentially susceptible to an outage in the event of DNS issues outside the control of either the client or Savvy. For this reason, we recommend you use hosts file entries on your system to facilitate name resolution should such an issue occur

Next Section