Track the status of a cross-border payment
This guide explains the webhook statuses available to receive status updates on cross-border payments. Understand the various lifecycle statuses a cross-border payment goes through until it is completed.
The user in this document pertains to both the individual and business user types.
Use Cases
- You want to retrieve the outstanding status of a cross-border payment.
- You want to notify users of the status update of their cross-border payment, using the information received from the webhook payload.
- You want to display the timeline and status changes of cross-border payment transactions in your application.
Prerequisites
- The user profile risk assessment status must not be
risk_flagged. - The user profile must be in an
activestatus. - The user must have an
approvedKYC or KYB status - The user account or wallet must be in an
activestatus. - The user's virtual account must be in an
activestatus. - At least one cross-border payout capability {
LOCAL, SWIFT} is enabled in your program. - At least one cross-border payment or remittance transaction has been initiated from the user (sender) account.
API Workflow
1
Retrieve the status of a specific remittance transaction
There are webhooks available that deliver the various cross-border payout updates. These webhooks are under the Transaction Payout Advisory category. These webhook events will carry a payload containing the status and details of a remittance transaction.
Payout Transaction webhook events
These are transaction status webhooks available under the Transaction Payout Advisory webhook category. API consumers are expected to subscribe to the webhook and handle the remittance transaction states as outlined below.
PAYOUT.TRANSACTION.CROSSBORDER.STATUS | The notification is sent for transaction status change events. This notification event is triggered when a transaction is submitted and moves into pending, processing, successful, failed, and reversed states. | No action required |
PAYOUT.TRANSACTION.CROSSBORDER.REVIEW.STATUS | The notification is sent whenever additional information is required, an update of new information is in progress, or the requirement for new information is closed or completed. | MatchMove will contact the program owner/partner if additional information is needed for the transaction. The program owner will need to respond with the additional information before the transaction can proceed with processing. |
The payload received from the webhooks above will contain some details of the application. Using this information, you should be able to notify your users of any progress on their cross-border payments.
2
Retrieve the status timeline of a specific remittance transaction
The status timeline will reveal the status changes of a remittance transaction from the time it was initiated to its terminal status.
Call Get Transaction Timeline (GET /users/wallets/payouts/remittances/transactions/{id}/timelines) passing the transaction reference identifier of the remittance transaction.
Get Transaction Timeline request
curl --location --globoff 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/transactions/{{transaction_reference_id}}/timelines' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Authorization: : ••••••'Get Transaction Timeline response
{
"pagination": {
"total_records": 7,
"records_per_page": 10,
"total_pages": 1,
"links": {
"self": "https://{{server}}/{{program}}/v2/users/wallets/payouts/remittances/transactions/W9kWJljNwUDM5gjM0cTMtUFRTVVTNd0Ut4EWUB/timelines"
}
},
"data": [
{
"id": "d146c3b413f1491886aa2ac6d47a3098",
"status": "INITIATED",
"sub_status": "TRANSACTION_INITIATED",
"message": "Request received, processing started",
"updated_by": "553cbc85ad41fa69a4ed5d183d5b8e31",
"updated_at": "2025-03-26T00:15:06 +08:00"
},
{
"id": "0730b317d1de4f1c95ed0f5285856bbf",
"status": "PROCESSING",
"sub_status": "USER_STATUS_ACTIVE",
"message": "User active, proceeding",
"updated_by": "553cbc85ad41fa69a4ed5d183d5b8e31",
"updated_at": "2025-03-26T00:15:07 +08:00"
},
{
"id": "fcea02430319412493a9cd88ffd7e22b",
"status": "PROCESSING",
"sub_status": "FUNDS_DEBIT_SUCCESS",
"message": "Funds have been successfully debited from your account.",
"updated_by": "553cbc85ad41fa69a4ed5d183d5b8e31",
"updated_at": "2025-03-26T00:15:07 +08:00"
},
{
"id": "905332ca3e704e01bab919172cd81a93",
"status": "PROCESSING",
"sub_status": "RECIPIENT_RISK_CHECK_COMPLETE",
"message": "Recipient risk is cleared",
"updated_by": "553cbc85ad41fa69a4ed5d183d5b8e31",
"updated_at": "2025-03-26T00:15:08 +08:00"
},
{
"id": "cdb9fa662e484627a22403213e2cb22e",
"status": "SUBMITTED",
"sub_status": "TRANSACTION_SUBMITTED",
"message": "Transaction is submitted to rail provider",
"updated_by": "553cbc85ad41fa69a4ed5d183d5b8e31",
"updated_at": "2025-03-26T00:15:08 +08:00"
},
{
"id": "53e5450a39404bacadbd04e6fd45e818",
"status": "PENDING",
"sub_status": "TRANSACTION_IN_PROGRESS",
"message": "Payment responds with pending payment",
"updated_by": "553cbc85ad41fa69a4ed5d183d5b8e31",
"updated_at": "2025-03-26T00:15:10 +08:00"
},
{
"id": "d88572e89b044d8aa269a619272a0981",
"status": "SUCCESS",
"sub_status": "TRANSACTION_SUCCESS",
"message": "Payment responds with successful payment",
"updated_by": "SYSTEM",
"updated_at": "2025-03-26T00:18:14 +08:00"
}
]
}Related Links
On this page
- Track the status of a cross-border payment