Borneo Transaction API

Introduction

This page describes the high level purpose, usage and differences between the POST .../transaction-requests and PUT .../transaction-requests/{request_id} endpoints

POST vs PUT

Under the transaction-requests resource, the Borneo Transaction API supports the following endpoints:

Unsuccessful request vs Unsuccessful Transaction

There are two key ways in which a response to a transaction request (either endpoint) might be unsuccessful:

Unsuccessful HTTP response

The overall response to the request might indicate failure, such as a Bad Request (see 400, 401, 403, 404, 409, 412, 422, 500, 503)

In these scenarios, no transaction record will have been created with the exception of 422: Unprocessable Entity. In this, the transaction was created and does exist, however the transaction has been declined due to business logic, such as the account not being in an 'ACTIVE' status for example. Details as to why the transaction was 'declined' will be provided in the response body within the result object.

Transaction result

When the http response code API is successful (e.g. 201), it does not necessarily mean that a transaction has been successfully processed.

In this scenario we are able to conclude that a transaction has been created on the PPS system, but the result of that transaction might still be declined. The response body needs to be interrogated to determine the result of the transaction. (See subsequent pages)

Idempotency

Motivation

When a caller fails to receive a response from a transaction request on the non-idempotent POST .../transaction-requests api (e.g. because of a network issue), they cannot know if the request was received and processed, and whether it was successful or unsuccessful. For fear that the transaction be duplicated in the case where the transaction request was indeed received and successfully processed, they wouldn't want to launch a subsequent API call to check/make sure.

Idempotent transaction requests

An idempotent PUT .../transaction-requests/{request_id} overcomes this issue, allowing callers to repeat a request multiple times until such a point as they receive an affirmative response, without fear of duplicating the outcome.

How it works

When using the PUT endpoint, the caller must define a unique ID for the request.

If the caller attempts to make a subsequent api call to the same endpoint, re-using the same request id but providing a different request body to the original, then (so long as the original call successfully reached PPS), this call will be rejected.

If the caller attempts to re-use the same request id and provides the same request body as the original call, then response will be (nearly) identical to the original call.

Idempotent only responses

The possible responses for both the idempotent and non-idempotent APIs are identical with the following exceptions applying to the idempotent API when it is used with the same request id and request body from a previously sent call:

• if the previous call was successfully processed (even resulting in a declined transaction), the api may return an http response code of 200: Successful (rather than 201: Created which would have been seen the first time round)
• if the previous call is still being processed, then the api will return an http response code of 102: Processing
• if the previous call was successfully processed and the same request with the same request_id is submitted again within a short timeframe, it is possible the API will return an http response code of 503: Service Unavailable with the body having title of Transaction Not Replicated. In this instance, the transaction exists, however the data for that transaction has not yet been replicated to the relevant system, so the transaction response body cannot be provided. Retry the request a few seconds later.