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 must have an
approvedKYC status. - The user profile must be in an
activestatus. - The user profile risk assessment status must not be
risk_flagged(v1). This is not applicable in v2. - 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 cross-border transaction (via webhook)
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.
Cross-border Payout Transactions 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.
Deprecation notice:
As part of our platform terminology update from "transactions" to "payments," these legacy webhook events have been renamed. Partners are encouraged to subscribe to the updated webhook names below to continue receiving status updates.
| 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 |
| 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 cross-border transaction (deprecated)
The status timeline will reveal the status changes of a remittance transaction from the time it was initiated to its terminal status.
Deprecation notice:
Partners are encouraged to switch to the enhanced method of tracking transaction cross-border transaction statuses.
See the replacement method at 3. Retrieve the status timeline of a specific cross-border transaction (new).
Call List Cross-border Payout Transaction Timelines (GET /users/wallets/payouts/remittances/transactions/{transaction_reference_id}/timelines) passing the transaction reference identifier of the remittance transaction.
List Cross-border Payout Transaction Timelines 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: : ••••••'
List Cross-border Payout Transaction Timelines 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"
}
]
}
3
Retrieve the status timeline of a specific cross-border payment (new)
The status timeline will reveal the status changes of a remittance payment from the time it was initiated to its terminal status.
Call List Cross-border Payout Payment Timelines (GET /users/wallets/payouts/remittances/payments/{payment_id}/timelines) passing the payment reference ID of the remittance transaction.
List Cross-border Payout Payment Timelines request
curl --location --globoff 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/payments/{{payment_id}}/timelines' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Authorization: : ••••••'
List Cross-border Payout Payment Timelines response
{
"pagination": {
"total_records": 5,
"records_per_page": 10,
"total_pages": 1,
"links": {
"self": "http://{{}}/{{program_code}}/v2/users/wallets/payouts/remittances/payments/C5UORBzN3ADN2kTM5cTMtQ0UV1UTHNVLOhFV/timelines?page=1&records_per_page=10"
}
},
"data": [
{
"id": "fc61eb98a8f24aaeb9e92bdcc83837e7",
"status": "INITIATED",
"sub_status": "TRANSACTION_INITIATED",
"message": "Request received, processing started",
"updated_by": "f88934dbba144b9ca0955b2ce3f149ea",
"updated_at": "2026-10-14T21:17:57 +08:00"
},
{
"id": "eb40a5d94f6044c0980db09571d1cf38",
"status": "PROCESSING",
"sub_status": "USER_STATUS_ACTIVE",
"message": "User active, proceeding",
"updated_by": "f88934dbba144b9ca0955b2ce3f149ea",
"updated_at": "2026-10-14T21:17:59 +08:00"
},
{
"id": "23a0b2e6ad564766b0554d5a20823518",
"status": "FUNDS_SECURED",
"sub_status": "FUNDS_DEBIT_SUCCESS",
"message": "Funds have been successfully debited from your account.",
"updated_by": "f88934dbba144b9ca0955b2ce3f149ea",
"updated_at": "2026-10-14T21:18:00 +08:00"
},
{
"id": "eadd5b612fb643a485f0311763529555",
"status": "CONFIRMED",
"sub_status": "RECIPIENT_RISK_CHECK_COMPLETE",
"message": "Recipient risk is cleared",
"updated_by": "f88934dbba144b9ca0955b2ce3f149ea",
"updated_at": "2026-10-14T21:18:01 +08:00"
},
{
"id": "0282b53d06d14f9bb9addb26b3a4789d",
"status": "SUBMITTED",
"sub_status": "TRANSACTION_SUBMITTED",
"message": "Transaction is submitted to rail provider",
"updated_by": "f88934dbba144b9ca0955b2ce3f149ea",
"updated_at": "2026-10-14T21:18:02 +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": "98e5450a39404bacadbd04e21d45e811",
"status": "UNDER_REVIEW",
"sub_status": "INITIATED",
"status_message": "The RFI Team requires additional information.",
"activity_type": "STATUS_UPDATE_WEBHOOK",
"created_at": "2026-10-01 14:30:00",
"under_review_history": [
{
"status": "UNDER_REVIEW",
"sub_status": "INITIATED",
"provider_review_ref": "evt_d3n3iavvima100lp71kg",
"platform_review_ref": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"event_type": "payout.compliance_hold",
"response_status": "",
"created_at": "2026-10-01 14:30:00",
"updated_at": "",
"review_requests": [
{
"platform_review_ref": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"entity_type": "payout_details",
"entity_request_data": [ { "...": "..." } ],
"created_at": "2026-10-01 14:30: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"
}
]
}
4
Retrieve the current status of a specific cross-border transaction (new, via API)
Use this method to retrieve the latest, real-time status of a specific remittance transaction.
Call Get Cross-border Payout Payment Status (GET /users/wallets/payouts/remittances/payments/{payment_id}/statuses) passing the payment reference ID of the remittance transaction.
List Cross-border Payout Payment Statuses request
curl --location --globoff 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/payments/{{payment_id}}/statuses' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Authorization: : ••••••'
List Cross-border Payout Payment Statuses response
{
"status": "FUNDS_SECURED",
"sub_status": "FUNDS_DEBIT_SUCCESS",
"status_message": "Funds have been debited from the user's wallet.",
"created_at": "2026-10-01 14:30:00"
}
Related Links
On this page
- Track the status of a cross-border payment