Reverse debited funds from a user account

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 executed
• details.transaction_comments - Any message or internal comments on the transaction
• details.payment_ref - The payment reference identifier generated by the payment service provider
• details.source_account - The fund source account or card number for the debit or credit
• details.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.