Deduct from Virtual Account

Withdraw funds from an existing virtual account. This operation requires the virtual account to have sufficient balance.

Endpoint: https://api.chapa.co/v1/virtual-account/deduct
Method: POST
Authorization: Pass your secret key as a bearer token in the request header
Content-Type: application/json

Request Parameters

Parameter	Required	Type	Description
`account_number`	Yes	string	The unique identifier of the virtual account from which funds will be deducted
`amount`	Yes	number	Amount to be deducted from the virtual account balance
`tx_ref`	No	string	Your reference for this transaction
`note`	No	string	Reference or description for the deduction transaction

Example Request Body

{
  "account_number": "1234567890",
  "amount": 1000,
  "tx_ref": "REF_1234",
  "note": "Deduction for February 2025"
}

cURL

PHP

Python

Successful Response

{
  "status": "success",
  "message": "Amount deducted Successfully",
  "data": {
    "account": {
      "account_name": "SEMER NUR",
      "account_number": 100314252,
      "account_alias": "1234542",
      "balance": 20,
      "status": "active",
      "currency": "ETB",
      "created_at": "2025-02-21T08:06:54.000000Z",
      "updated_at": "2025-02-21T08:13:25.000000Z"
    },
    "withdrawal": {
      "tx_ref": "VWDYi1qyA6",
      "note": "Connecting Ethiopia to the Global Market",
      "amount": 20,
      "currency": "ETB",
      "created_at": "2025-02-21T08:13:25.000000Z"
    }
  }
}

Response Parameters

Parameter	Type	Description
`status`	string	Status of the request (success/error)
`message`	string	Description of the operation result
`data.account.account_name`	string	Name associated with the virtual account
`data.account.account_number`	number	Unique identifier of the virtual account
`data.account.account_alias`	string	Custom reference name for the account
`data.account.balance`	number	Current balance after deduction
`data.account.status`	string	Current status of the account
`data.account.currency`	string	Currency of the account
`data.account.created_at`	string	Timestamp of account creation
`data.account.updated_at`	string	Timestamp of last account update
`data.withdrawal.tx_ref`	string	Your reference for this debit transaction
`data.withdrawal.note`	string	Description provided for the debit
`data.withdrawal.amount`	number	Amount deducted in this transaction
`data.withdrawal.currency`	string	Currency of the withdrawal
`data.withdrawal.created_at`	string	Timestamp of the withdrawal transaction

Failed Response

{
  "status": "failed",
  "message": "Withdrawal Failed",
  "errors": {
    "insufficient_balance": "Virtual account doesn't have sufficient balance."
  }
}

The virtual account must have sufficient balance to process the deduction successfully.

Refer to our Error Codes page for all responses for this request.

Use Cases

Withdrawals: Process customer withdrawal requests
Refunds: Deduct funds for refund processing
Fees: Deduct service fees or charges
Balance Management: Transfer funds from virtual accounts to business account

Next Steps

Deposit to Virtual Account - Add funds to virtual account
Get Virtual Account - Retrieve virtual account details
Get Virtual Account Debit History - View debit transaction history
Error Codes - Handle errors gracefully