Cash Pick Up Service
‘Cash Pick Up’ is a service where the recipient receives funds in the form of physical cash at a designated payout location.
Overview of the process:
WorldRemit notifies the recipient (via SMS or email) that a transaction is available for them to collect. This message contains a unique WorldRemit Transaction Identification Reference.
When the recipient presents this reference at one of your locations for collection, the payment process is as follows:
Lock the transaction
Read the details
Validate the recipient
Pay the transaction (or unlock it if the transaction cannot be paid for some reason)
Please note: it is mandatory for correspondents to implement an auto-unlock process if a transaction has been locked for more than 20 mins and has not been successfully paid.
The sequence diagrams below provides an overview of both successful and unsuccessful cash pick up transactions:
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 response and provides a list of all transactions in awaiting states available for payout.
Please note: the method will return an empty list if there are no pending transactions. Any other response code will be an error. Check out the full list of reponse 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 response codes. The list of response codes is available here. 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 sent 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.
Two-Factor Authentication (2FA)
In order to adhere to regulations in certain countries, WorldRemit has built a Two-Factor Authentication method for cash pick up services. The Operations Team will assist with the enablement of this feature when your account is configured if required.
If 2FA is part of the service you’re providing, WorldRemit will send a second SMS to the recipient’s mobile device which includes a 7-digit number (Collection Pin) to be presented to the Cashier when picking up cash. We use third parties for sending SMS messages, so it is difficult to guarantee a delivery timeframe for the second SMS. The final digit in the 7-digit verification code is a Luhn checksum digit, which can optionally be used to ensure that the code has been typed correctly in your application.
Please note: Your pay out process will need to accommodate the additional step of providing the second SMS Collection Pin to the Cashier.
The following sequence diagrams will illustrate both successful and unsuccessful cash pick up processes:
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.
Additional Optional 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.
See the full list of response codes 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, and you can find the full list of response codes here.
Change Recipent Details
‘Change Recipient’ requests will be sent when the transaction cannot be processed due to incorrect recipient details, or when a sender has requested a change of recipient. You will only be sent these requests for transactions that you have previously processed.
After you have received a request, you should lock it before doing any further processing to ensure it is not picked up again. The next step is to set the response marking the Change Recipient request as successful or failed.
Change Recipient Details Sequence Diagram
Change Recipient Request Webhook
This notification will be triggered when a new ‘Change Recipient’ request is created for a transaction that is currently being processed by your system.
Change Recipient Awaiting
This method retrieves the pending transaction change beneficiary requests. The retrieved list contains transactions that are currently in- flight and have an open change recipient request.
Change Recipient Lock
This method locks the ‘Change Recipient’ request. This ensures the request will not be picked up again.
Request
This method requires one of the optional input parameters to be included. The ‘Change Recipient’ request is identified by a Transaction ID, which can be the UUID ID of the transaction, or the reference. The request body attached to this request should be empty.
Response
This method returns an HTTP 200 OK response if the ‘Change Recipient’ request has been successfully locked. Any other response will result in an error, the details of which can be found here.
Change Recipient Set Response
This method marks the Change Recipient request as completed. The success property inside the request body needs to be set up in order to mark this request as a success or failure.
Request
The body of the Change Recipient Set Response request has the “success” field as mandatory. In the case where the recipient data change was successful, this is to be set as ‘true’ . Additional information can be provided in the comment field, which is optional.
If the Change Recipient request is not successful and the transaction details are not updated in your system, the “responsecode” and “responsemessage” fields become mandatory.
Example request body:
{
"properties": {
"success": "False",
"responsecode": "0830",
"responsemessage": "Unable to Change Recipient",
"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 Change Recipient request will be completed. Any other response will result in an error, the details of which can be found here.
Webhooks
Webhooks allow for instant notification of awaiting requests for your account, thereby facilitating faster processing. The WorldRemit team will implement webhooks for 'Awaiting Transactions' and 'Get Status' on your behalf.
Find a more indepth overview of how webhooks are used in our APIs 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.