Skip to main content

​
Endpoint

POST /wallets/transactions

​
Description

Use this endpoint to create a transaction that either adds funds to a wallet (credit) or removes funds from a wallet (debit). The wallet balance is updated immediately upon successful processing.

​
Request Body

{
  "amount": 500,
  "description": "Customer payout",
  "type": "debit",
  "wallet_id": "3d2e3f3e-3b3c-4907-a4fd-e241203440d7"
}

​
Request Fields

FieldTypeRequiredDescription
wallet_idstring (UUID)YesWallet to be debited or credited
amountnumberYesTransaction amount (in wallet currency)
typestringYesTransaction type: debit or credit
descriptionstringNoReason or note for the transaction

​
Supported Transaction Types

TypeDescription
creditAdds funds to the wallet balance
debitRemoves funds from the wallet balance

​
Response

​
Success Response (200 OK)

{
  "data": {
    "transaction_id": "transaction_id",
    "wallet_id": "wallet_id",
    "type": "debit",
    "amount": 500,
    "balance_after": 1500,
    "created_at": "2025-07-24T10:15:30Z"
  }
}

​
Common Errors

Status CodeDescription
400Invalid request
401Unauthorized
404Wallet not found
409Insufficient balance for debit
422Invalid transaction type

​
Notes & Best Practices

  • Ensure the wallet is active before initiating a transaction.
  • Debits will fail if the wallet balance is insufficient.
  • Use clear and descriptive transaction descriptions for auditing.
  • Avoid using this endpoint for external payments; use dedicated payout or funding endpoints instead.

​
Common Use Cases

  • Customer payouts
  • Refunds
  • Wallet top-ups
  • Internal balance adjustments