Debit 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

Debit funds from a user wallet to the prefund

Call Create Debit Transaction (DELETE /users/wallets/funds) to debit funds from a user wallet and credit to the prefund.

You can use any of these user identifiers (user_id, mobile, email) to identify the source of the transfer. In this example, we will use the user_id of the owner of the source account.

Create Debit Transaction request

 
curl --location --request DELETE 'https://{{accounts_base_url}}/{{product_code}}/v1/users/wallets/funds' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••' \
--data-urlencode 'user_id={{user_id}}' \
--data-urlencode 'amount=10' \
--data-urlencode 'details={
    \"pp\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\",
    \"transaction_comments\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\",
    \"payment_ref\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\",
    \"merchant_name\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\"
}'

Reference: Anti-scam Measures

Create Debit Transaction response

 
{
    "id": "1ef851022a58f9971334aea933f286db936bba7833ccf476d2f55ece9c0dd308",
    "ref_id": "000002C1000000000002000000000279",
    "user_id": "01e09f4194c7640d672574fee7723a1f",
    "wallet_id": "f6beb0bf2fe263ac1ffb4d30c6d789f0",
    "confirm": "skip",
    "sor_transaction": null,
    "category_details": [
        {
            "name": "DEFAULT",
            "amount": "10.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.