A Closer Look at the Payment API
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:
|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:
|stopped|| The payment is in limbo, most likely in the case of too many submits.
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.
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 CodesWhen submitting payments to external banking systems, you may encounter a few additional response codes.
|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|
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.
A payment cannot be completed. Most likely this will need to be resolved by our customer service staff.
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.