Bank Transfer
Bank Transfer is an instant payout service our Payout API offers where the recipient receives funds in their bank account.
To integrate a service of this type you must develop against the standard requirements for all integrations: Transaction Awaiting, Transaction Set Response, Transaction Set Paid.
A webhook needs to be registered for this integration type. It is expected that your system will make a successful request to the ‘Transaction Awaiting’ method within seconds of receiving the new transaction notification.
Please note: You should make use of the awaiting function to retrieve any new transactions, cancellations and change recipient details requests
Sequence Diagram for the Synchronous Flow
For synchronous transactions, the flow happens in a single request which has one-way communication. The sequence diagram below explains the synchronous way of communicating with our API.
Sequence Diagram for the Ansynchronous Flow
For asynchronous flow calls, separate requests which have callbacks facilitate two-way communication where you make a call to us and we reply at a later time with the result.The sequence diagram below explains the asynchronous transaction flow.
Integration Methods
Transaction Webhook: This notification will be triggered when a new transaction is ready to be processed by the Correspondent.
Transaction Awaiting: This functionality retrieves the pending transaction requests. These transactions will be auto-locked by default to enable quicker servicing. Auto-locking can be disabled if required, but the ‘Transaction Set Lock’ method must be implemented instead.
The ‘Transaction Awaiting’ functionality must be executed immediately after a webhook notification is received. However, to avoid missing transactions ready for processing due to notifications not received, you must implement a continuous loop of calling ‘Transaction Awaiting’ at a regular interval. The suggested time period is 5 minutes. This method returns an HTTP 200 OK and provides a list of all transactions in awaiting states available for payout.
Please note: the method will return an empty list is there are no pending transactions. Any other response code will be an error. Check out the full list of response codes here.
Transaction Set Response: This functionality processes your response for the transaction based on your response code and response message. To use this functionality you will need to map your system response codes to the WorldRemit reponse codes. These response codes provide transaction state updates, with the bulk of them describing a failure with transaction processing (e.g. failed account validation) where the transaction cannot be paid out to the beneficiary. The operational expectation for this service is that a response is set within 5 minutes of the transaction being ingested by your system.
Additionally, ‘Transaction Set Response’ can be used to provide transaction state updates while processing. This is required if the transaction cannot be paid immediately and will be processed asynchronously. An example case would be the sender needing to undergo a Know Your Customer (KYC) check in order to payout to proceed.
This method returns a HTTP 200 OK response if the response code and message provided have been successfully recognised. Based on the result of the response code, the transaction will be moved into that state. Any other response will be an error and the transaction state will not be changed.
Transaction Set Paid: This method marks the transaction as paid, which is a final transaction state. There are several mandatory parameters required in the request body for the paid request to be accepted, which are configured depending on the product type and compliance regulations.
Please note: If you generate a reference id from your system which you would like the WorldRemit Operations team to quote when communicating with your support team provide it in the “txnreference” property of the body of the request. This method returns an HTTP 200 OK response if the transaction has been successfully paid.
Mandatory features
Heartbeat Health Check
It is mandatory for correspondents to implement a continuous heartbeat functionality which generates a call to the Payout API Heartbeat endpoint at a fixed interval of time. This will provide proof that the WorldRemit Correspondent Platform and correspondent system are available and is monitored by the WorldRemit Operations Team. An SLA for the maximum allowed downtime of your system will be agreed with the Operations and Business Development Teams at WorldRemit.
'Get status' requests
Transaction Status Request is required functionality for all types of integrations. This method is used for troubleshooting by the WorldRemit Operations Team.
When a webhook notification of ‘Transaction Status Request’ type is received, the list of awaiting requests must be retrieved using the ‘Transaction Status Awaiting method. For each request the correspondent must respond by providing an update by calling Transaction Set Response or Transaction Set Paid. If no noteworthy update has happened, there can be a repeat of the latest state update already provided.
Transaction Status Request Sequence Diagram
Transaction Status Webhook
Webhooks allow for instant notification of awaiting requests for your account for faster processing. This notification will be triggered when WorldRemit requires a status update for a transaction that you are processing on your system. This is typically used when a transaction is processed asynchronously, or when a transmission error occurs during processing.
Find additional details about webhooks and how they work here.
Transaction Status Awaiting
Transaction Status Awaiting retrieves the pending transaction status requests. These will be auto-locked by default to enable quicker servicing.
POST /transactionstatus/awaiting
Auto Locking can be disabled if necessary, but the Transaction Status Lock method must be implemented instead.
POST /transactionstatus/awaiting
Find additional details about transaction states here.
Optional Additional Features
Transaction Cancellation Requests
The Cancellation methods allow you to receive cancellation requests that may be generated for an in-flight transaction.
After you have received a request, you should lock it before doing any further processing to ensure it is not picked up again by your system or another correspondent. You should then set the response marking the cancellation as ‘successful’ or ‘failed’.
Cancellation Awaiting Sequence Diagram
Cancellation Request Webhook
A cancellation request notification will be triggered when a new cancellation request is created for a transaction that is currently being processed by your system.
Cancellation Awaiting
The ‘Cancellation Awaiting’ method retrieves the pending transaction cancellation requests. The list generated consists of transactions that are currently in-flight and have an open cancellation request that you must process.
Cancellation Lock
The ‘Cancellation Lock’ method locks the ‘Transaction Cancel’ request. This ensures the request will not be picked up again resulting in duplicate processing.
Request
This method requires one of the optional input parameters to be included. The Cancellation Request is identified by a Transaction ID, which can be the GUID ID of the transaction, or the reference, or a wrid field. The request body attached to this request should be empty.
Response
This method returns an HTTP 200 OK response if the Cancellation Request has been successfully locked. Any other response will result in an error, the details of which can be found here.
Cancellation Set Response
This method marks the Cancellation Request as completed. Full configuration requires setting the success property inside the request body to mark this request as a success or a failure.
Request
The body of the ‘Cancellation Set Response’ request has the success field as mandatory. In the case of a successful cancellation this needs to be set as ‘true’. Additional information can be provided in the comment field, which is optional.
If the Cancellation Request is not successful and the transaction is not cancelled in your system, the “responsecode” and “responsemessage” fields become mandatory.
Example request body:
{
"properties": {
"success": "False",
"responsecode": "0810",
"responsemessage": "Unable to Cancel",
"comment": "Transaction is already Paid"
}
}
Response
This method returns an HTTP 200 OK response if the response code and message provided have been successfully recognised. Based on the result of the response code, the Cancellation Request will be completed. Any other response will be an error, the details of which can be found here. If an error is generated the transaction state will not be changed.
Webhooks
Webhooks allow for instant notification of awaiting requests for your account for faster processing. WorldRemit Engineers will implement webhooks for Awaiting Transactions and Get Status.
Find a more in-depth understanding about webhooks here.
Transaction States & Flow
Transaction Flow
The details of the transaction flow will depend on both the transaction product type (i.e. cash pick up, mobile money or bank transfer) and on whether you process payments asynchronously or synchronously through your system.
The WorldRemit Operations Team will collaborate with you on the optimal workflow when your account is set up.
Here is the key terminology and definitions:
Authorized: the transaction has been authorized for payment, will now be picked up and the correspondent will be notified of the incoming transaction
Correspondent Awaiting: the transaction can be read from the API using the ‘Awaiting’ method call
Correspondent Processing: the correspondent has read the transaction and/or marked the transaction as locked for payment (this depends on the type of product and workflow assigned to your account). At this stage, WorldRemit is awaiting a response.
Correspondent Acknowledge: this used only for asynchronous processing. This workflow will be assigned to you if there is a delay between reading and paying a transaction, specifically when you are sending the transaction to a remote third-party system for processing.
Paid: the transaction has been marked as paid.
Failed: the transaction has been marked as failed.
Retry: the transaction is delayed, and transmission will be retried later.
Cancelled (Not Refunded): the transaction has been marked as cancelled. There are additional steps to a transaction flow that will be picked up by our Customer Service Team to ensure that the sender is credited the funds.