Reverse debited funds from a user account
Learn how to reverse a specific debit transaction made from a user's account. This guide explains the process for refunding a particular charge after it has been debited from a user account.
The user in this document pertains to both the individual and business user types.
Use Cases
- You want to reverse a previously successful debit on a user account.
- You want to return a debit that was made to a user account due to an error or mistake.
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 account's current
topup_limitsandpurse_max_limitmust have enough buffer to accommodate the incoming credit amount.
API Workflow
1
Finish your internal validations
Ensure that your internal validations are completed. Confirm the receipt of funds to the wallet if the transfer relies on external dependencies.
2
Prepare the payload
To facilitate compliance and tracking, prepare the required payload to tag all transactions and identify the source of funds.
Additional transaction metadata
details.pp- Payment processor, which identifies which type of payment was processed or executeddetails.transaction_comments- Any message or internal comments on the transactiondetails.payment_ref- The payment reference identifier generated by the payment service providerdetails.source_account- The fund source account or card number for the debit or creditdetails.source_bank_name- The fund source bank name or the bank issuer of the card (when available)details.source_network_name- The name of the network where the transaction is processed, e.g., Mastercard, VISA, etc. (when available)
3
Reverse an account debit to return funds to a user's account
To reverse a previously debited transaction and return the funds to the source user wallet, you will need to pass the transaction.ID or the transaction ID of the previously successful debit transaction that you want to reverse.
Call Create Debit Reversal Transaction (POST /users/wallets/funds/reversals/{ref_id}) to reverse a previous debit made to a user account.
Create Debit Reversal Transaction request
url --location 'https://{{accounts_base_url}}/{{product_code}}/v1/users/wallets/funds/reversals/4447cfe731a99f3a396221e550a459814d5865294dfe284b94b8930813b2bbb6' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••' \-—data-urlencode 'amount=5' \
--data-urlencode 'details={
\"pp\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\",
\"transaction_comments\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\",
\"payment_ref\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\",
\"source_account\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\",
\"source_bank_name\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\",
\"source_network_name\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\"
}'Reference: Anti-scam Measures
Create Debit Reversal Transaction response
A sample response payload of a successful debit reversal transaction. Please note that a new transaction ID will be generated for the reversal transaction. The only way to correlate the debit and the reversal transaction is through the ref_id or the reference ID of the transaction.
{
"user_id": "cd896adb395fa384a5a8b174a007c34c",
"wallet_id": "033d5a04a5430d67655b7d09aa767d9a",
"transaction": {
"reversal": {
"id": "0bb494e6c5ce11b278bc92aa109e5e30c149e004fa7b8364ed51343b75a7e02a",
"ref_id": "000002C100000000020300000000027F",
"category_details": [
{
"name": "DEFAULT",
"amount": "5.00",
"currency": "USD"
}
]
}
}
}4
Handle errors gracefully
As a financial payment platform, we subject every transaction to a series of checks and validations to ensure adherence to the limits configured for the account. Any resulting failures or errors are communicated via the response payload structure shown below. A comprehensive list of error codes for this API is available on the API reference page.
Sample error response
{
"id":"683e98350c1e8",
"code":400,
"status":"user_parameter_validation_failed",
"title":"User Parameter Validation Failed",
"description":"Field required not met; amount must be greater than 0",
"link":"https://developer.matchmove.com/docs/optimus-prime/docs/Overview/4.%20Handle%20Errors/b.-Error-List.md#user_parameter_validation_failed",
"timestamp":"2025-06-03 14:06:41 +08"
}5
Display / notify transaction status to end user
Closed-loop transactions, like account crediting, do not have any webhook events associated with them. Since these types of transactions are synchronous, the response and status will be received immediately after API execution.
For partners who intend to send a push notification via in-app, email, or SMS — the API response payload containing transaction details and other metadata can be used in message content. To learn more about closed-loop transaction notifications, head to the Anti-Scam Measures section.
Related Links
On this page
- Reverse debited funds from a user account