Debit funds from a user account
Understand the process for debiting funds from a user's account balance. This guide covers how to make direct adjustments for scenarios like applying service fees or making corrections.
The user in this document pertains to both the individual and business user types.
Use Cases
- You want to collect funds from a user account, such as subscription fees, platform fees, transaction fees, etc.
- You want to collect funds from a user account for payment for services or goods rendered by the main partner.
- You want to “zero out a user account” by transferring all its remaining balance to the partner prefund before the account is closed on the platform.
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
deduct_limitsmust have enough buffer to accommodate the outgoing debit 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
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.
Related Links
On this page
- Debit funds from a user account