A Closer Look at the Payment API

Life-Cycle

A single payment is created upon initial payment request (POST). As a payment is subsequently processed by us, and in the case of outbound payments, by a clearing system, one or more of the following events are associated with it:

Event Description
rejected The payment is valid (well-formed) but one or more business rules have failed.
For example: not enough funds, insufficient financial authority, account is not on a white-list or is black listed
accepted The payment passes both validation and business rules. Funds are debited from client account.
submitted The payment has been sent to the relevant clearing system.
executed The payment has been processed by the relevant clearing system.
reversed The payment could not be executed after having been accepted. There are three cases:
  • submission results in a bank rejection
  • a return message is received from the bank after the fact
  • stopped payments getting manually marked as returned based on external information
stopped The payment is in limbo, most likely in the case of too many submits.

A "typical" outbound payment will have three events associated with it: accepted, submitted and executed.

Tracking Requests

In addition to the standard Transactive request IDs, payments have several other identifiers which help to track your payments and ensure their idempotency:

  • InstructionId – This is a an idempotency reference provided by you. If Transactive receives a payment request with the same InstructionId and body as a prior request, Transactive will return the payment in its current status. If the body of the payment request is NOT identical, Transactive will reject the request.
  • Sender Reference – This is a non-unique reference for your benefit, it is only visible inside Transactive (not passed onto clearing systems). It can be used to identify the payment from a business perspective, for example order number etc. We advise not to use the Sender Reference as the InstructionId because if the payment is rejected for any reasons, say lack of funds, you will not be able to create another one with the same InstructionId
  • Description – This is a “reference” for the beneficiary that should show up on the bank statement of the destination account. It can be the same as the Sender Reference or different.
  • id (aka Payment Id) – This is a unique id for the payment both within Transactive and whichever clearing system handles its submission.

All Instruction Ids should be guaranteed to be unique, e.g. GUID or UUID.

When created by the portal, payment request Instruction Ids are automatically supplied.

Retrying

With regard to submitting payments, we ensure idempotency by requiring unique payment Instruction Ids. Payments may be retried as long as the Instruction Id and body of the payment stay the same.

If no response is received, repeat your call. No harm can come from doing so.

Payment Specific HTTP Response Codes

When submitting payments to external banking systems, you may encounter a few additional response codes.
Code Definition
201 Payment created but in a rejected state - no recourse
202 Payment accepted but processing incomplete - no recourse except to contact Transactive
409 Payment exists but its body is changed - retry with new request ID or with identical details

201

A payment has been permanently rejected. This is most likely because of an issue originating within one of our clearing systems. For example, a target bank might reject a perfectly good payment request because a target account has recently been closed.

202

A payment cannot be completed. Most likely this will need to be resolved by our customer service staff.

409

The details of a payment retry have been changed. This is not allowed. A retry must be effectively the same as the original payment.

All responses use  application/json, regardless of the request type.