Bank Transfer

Bank Transfer allows you to move funds from your business balance to a bank account. You pay the transfer amount plus a charge; the recipient receives the transfer amount.

API vs dashboard

	API	Dashboard
How it works	You send recipient bank details (`bank_name`, `bank_account_number`, and optionally `bank_account_name`, `bank_branch`). The account is validated before the transfer; you can send to any supported bank. No verified business bank account is required.	From the Bank Transfer page you can send to your own account or to a different bank account (with validation).

How bank transfers work

Create a transfer

Create a transfer with amount, description, recipient bank details, and optionally wallet_source. The account is validated before sending.

Charge applied

A charge is applied. Total deducted = amount + charge.

Balance deducted

Balance is deducted from the selected wallet (main or card) immediately before the provider call.

Transfer sent

Transfer is sent to the destination account.

Status set

Status is set to pending, processing, completed, or failed.

Get the result

Poll GET /bank-transfer/{reference} or use webhooks for the final result.

API endpoints

Method	Endpoint	Description
`POST`	`/api/v1/bank-transfer`	Create bank transfer
`GET`	`/api/v1/bank-transfer/services`	Get bank transfer availability & settings
`GET`	`/api/v1/bank-transfer/{reference}`	Get bank transfer details
`POST`	`/api/v1/bank-transfer/validate`	Validate bank account details
`GET`	`/api/v1/bank-transfer/banks`	Get list of supported banks

Authentication

All bank transfer API requests require authentication using your API key. Include your API key in the request headers: Authorization: Basic base64(api_key:api_secret)

Wallet selection

Every business has two wallets. Pass wallet_source to choose which wallet to debit:

Value	Wallet	Description
`main` (default)	Main Wallet	Mobile money collections (MTN, Airtel)
`card`	Card Wallet	Card payment collections

If omitted, wallet_source defaults to main. If a transfer fails, the refund goes back to the same wallet that was debited. Use card to withdraw card payment collections. See Card Payments for how card wallet funds accumulate.

Create a bank transfer

Create a new bank transfer to any valid bank account. Send recipient bank_name and bank_account_number (and optionally bank_account_name, bank_branch). The recipient account is validated before the transfer; you do not need verified business bank details. The balance (transfer amount + charge) is deducted immediately and the transfer is sent. Status is processing or completed on success, or failed on error (balance is refunded on failure). Endpoint POST https://wallet.wearemarz.com/api/v1/bank-transfer Request body

{
  "amount": 100000,
  "description": "Payment for services",
  "bank_name": "Equity Bank",
  "bank_account_number": "60001256421",
  "bank_account_name": "John Doe",
  "bank_branch": "Kampala",
  "wallet_source": "main"
}

bank_account_name, bank_branch, and wallet_source are optional. If bank_account_name is omitted, it is fetched from the validate-account step. If wallet_source is omitted, it defaults to main. Use card to withdraw from the card wallet. Use bank names from /bank-transfer/banks (e.g. Equity Bank, Stanbic Bank).

Request parameters

Parameter	Type	Required	Description
amount	number	Yes	Transfer amount in UGX (required). Recipient receives this amount; a charge is added on top.
description	string	Yes	Description of the transfer (max 500 characters)
bank_name	string	Yes	Recipient bank name (e.g. Equity Bank, Stanbic Bank). Use names from `/bank-transfer/banks`.
bank_account_number	string	Yes	Recipient bank account number. Validated before the transfer.
bank_account_name	string	No	Recipient account name. If omitted, obtained from the validate-account step.
bank_branch	string	No	Recipient bank branch (optional)
wallet_source	string	No	Which wallet to debit: `main` (default) or `card`. Use `card` to withdraw card payment collections.

Response (success) - HTTP 201

The reference is a UUID; use it with GET /bank-transfer/{reference} to check status. Possible status: processing, completed.

{
  "status": "success",
  "message": "Bank transfer is being processed. Reference: b0faa118-3e00-40ee-9513-67e371f9a32f. It may take a few minutes to complete.",
  "data": {
    "bank_transfer": {
      "id": 1,
      "reference": "b0faa118-3e00-40ee-9513-67e371f9a32f",
      "transaction_uuid": "b0faa118-3e00-40ee-9513-67e371f9a32f",
      "amount": {
        "formatted": "100,000.00",
        "raw": 100000,
        "currency": "UGX"
      },
      "charge_amount": {
        "formatted": "50,000.00",
        "raw": 50000,
        "currency": "UGX"
      },
      "total_amount": {
        "formatted": "150,000.00",
        "raw": 150000,
        "currency": "UGX"
      },
      "description": "Payment for services",
      "status": "processing",
      "wallet_source": "main",
      "bank_details": {
        "bank_name": "Equity Bank",
        "account_name": "John Doe",
        "account_number": "60001256421",
        "branch": "Kampala"
      },
      "balance": {
        "current": "1,000,000.00",
        "after_transaction": "850,000.00"
      },
      "provider": {
        "transaction_id": "TXN-123456",
        "status_code": "122",
        "status_description": "Processing"
      },
      "created_at": "2026-02-20 16:14:46"
    }
  }
}

Get bank transfer availability

Check if bank transfer is available for your business. Subscription details are handled internally and are not exposed. Endpoint GET https://wallet.wearemarz.com/api/v1/bank-transfer/services Response (success)

{
  "status": "success",
  "data": {
    "bank_transfer_available": true,
    "service": {
      "name": "Bank Transfer Service",
      "provider": "Banks"
    }
  },
  "message": "Bank transfer is available."
}

Get transfer details

Retrieve a specific bank transfer by the reference returned from the create endpoint (UUID format). Use this to poll status. Possible status values: pending, processing, completed, failed. Endpoint GET https://wallet.wearemarz.com/api/v1/bank-transfer/{reference} Replace {reference} with the UUID from the create response (e.g. b0faa118-3e00-40ee-9513-67e371f9a32f).

Validate bank account

Validate the recipient account before creating a transfer to ensure it is valid and working. Call this endpoint with bank_name and account_number to get the account holder name and confirm the account exists. Use it when building UIs (e.g. dashboard “Send to a different bank account”) or in your flow before calling create transfer. The create-transfer API also validates internally, but validating first gives you early confirmation and avoids failed transfers. No verified business bank is required. Endpoint POST https://wallet.wearemarz.com/api/v1/bank-transfer/validate Request body

{
  "bank_name": "Equity Bank",
  "account_number": "60001256421"
}

Request parameters

Parameter	Type	Required	Description
bank_name	string	Yes	Name of the bank (e.g. “Equity Bank”, “Centenary Bank”, “DFCU Bank”)
account_number	string	Yes	Bank account number to validate

Response (success)

{
  "status": "success",
  "message": "SUCCESS",
  "data": {
    "account_number": "60001256421",
    "bank_name": "Equity Bank",
    "bank_code": "EQU",
    "account_name": "JOHN DOE",
    "network": "EQU",
    "is_registered": "ACTIVE",
    "valid": true,
    "status_code": 0,
    "status_description": "SUCCESS"
  }
}

Response fields

Field	Type	Description
account_number	string	The validated account number
bank_name	string	The bank name provided in the request
bank_code	string	The bank code (e.g. “EQU”, “CENT”, “DFCU”)
account_name	string	Account holder name as returned by the validation service
network	string	Bank network code (usually same as bank_code)
is_registered	string	Registration status (“ACTIVE” if fully registered)
valid	boolean	True if account is valid and fully registered (`status_code` is 0 and `is_registered` is `ACTIVE`)
status_code	integer	Status code (`0` = success)
status_description	string	Status description (e.g. “SUCCESS”)

Validation errors

BANK_NOT_SUPPORTED (400) - bank name not in supported list
VALIDATION_FAILED (400) - provider rejected the account
SERVICE_NOT_AVAILABLE (400) - no active bank transfer subscription

Get supported banks

Retrieve a list of all supported banks for bank transfers and account validation. This endpoint returns bank codes, display names, and common aliases. Endpoint GET https://wallet.wearemarz.com/api/v1/bank-transfer/banks Response (success)

{
  "status": "success",
  "message": "Supported banks retrieved successfully",
  "data": {
    "banks": [
      { "code": "EQU", "name": "Equity Bank", "aliases": ["Equity Bank", "Equity", "EQU"] },
      { "code": "CENT", "name": "Centenary Bank", "aliases": ["Centenary Bank", "Centenary", "CENT"] },
      { "code": "DFCU", "name": "DFCU Bank", "aliases": ["DFCU", "DFCU Bank"] },
      { "code": "STANBIC", "name": "Stanbic Bank", "aliases": ["Stanbic Bank", "Stanbic", "STANBIC"] },
      { "code": "STAN", "name": "Stanchart Bank", "aliases": ["Stanchart Bank", "Stanchart", "Standard Chartered", "STAN"] },
      { "code": "ABSA", "name": "ABSA Bank", "aliases": ["ABSA Bank", "ABSA"] }
    ],
    "count": 25
  }
}

Stanbic Bank (code STANBIC) and Stanchart Bank / Standard Chartered (code STAN) are different banks. Use the exact bank name from this list when validating or transferring to avoid provider errors.

Usage tips

Use any of the bank names from the aliases array when calling /bank-transfer/validate
The code field is a unique identifier for each bank
Bank names are case-insensitive, so “Equity Bank”, “equity bank”, or “EQUITY BANK” all work
Always use /bank-transfer/banks to get the current list; bank codes must match exactly for the provider to accept the transfer

Transfer statuses

When you create or query a transfer, status can be:

Status	Meaning
`pending`	Created, not yet sent to provider
`processing`	Sent to provider; completion pending
`completed`	Successfully completed
`failed`	Provider or system error; balance is refunded on create failure

Prerequisites

For the API: provide recipient bank details (bank_name, bank_account_number) in each request. The account is validated before the transfer; no verified business bank account is required.
An active bank transfer service (subscription is handled internally)
Sufficient balance in the selected wallet (transfer amount + charge). Use wallet_source = main or card.
Account must not be frozen. Only one transfer can be processing or pending at a time.

Best practices

Check availability

Use GET /bank-transfer/services to see if bank transfer is available for your business.

Verify balance

Ensure you have sufficient balance in the selected wallet: you pay transfer amount plus charge; the recipient receives the transfer amount. Check available_balance (main wallet) or card_balance (card wallet) from GET /balance.

Handle webhooks

Set up webhooks to receive real-time notifications when your bank transfers are processed, completed, or failed.

Store references

Save the reference number returned in the response. Use it to check the status of your transfer later.

Check status

Transfers can have statuses: processing, completed, or failed. Use the reference to check status via the GET endpoint.

Validate first

Validate before sending: call POST /bank-transfer/validate with bank_name and account_number before creating a transfer.

Error responses

Error responses include an error_code and data with details. On provider failure your balance is refunded.

Error	Meaning
`INSUFFICIENT_BALANCE`	Insufficient main wallet balance
`ACCOUNT_FROZEN`	Your business account is currently frozen
`SERVICE_NOT_SUBSCRIBED`	No active bank transfer subscription
`BANK_CODE_NOT_FOUND`	Bank name not supported
`INVALID_BANK_ACCOUNT`	Recipient account could not be validated
`VALIDATION_ERROR`	Invalid or missing fields
`REQUEST_NOT_FOUND`	Bank transfer request not found
`API_CONNECTION_FAILED`	Provider request failed; balance is refunded
`PROCESSING_TRANSFER_EXISTS`	You already have a transfer being processed
`TRANSFER_FAILED`	Transfer could not be completed; balance refunded

Debugging & logging

Bank transfer requests and responses are logged for troubleshooting. Check storage/logs/laravel.log and storage/logs/bank-YYYY-MM-DD.log for request/response entries.

Get started

Collections

Disbursements

Bills & airtime

Webhooks & platform

Build tools

Support

API vs dashboard

How bank transfers work

API endpoints

Authentication

Wallet selection

Create a bank transfer

Request parameters

Response (success) - HTTP 201

Get bank transfer availability

Get transfer details

Validate bank account

Request parameters

Response (success)

Response fields

Validation errors

Get supported banks

Usage tips

Transfer statuses

Prerequisites

Best practices

Check availability

Verify balance

Handle webhooks

Store references

Check status

Validate first

Error responses

Debugging & logging

​API vs dashboard

​How bank transfers work

​API endpoints

​Authentication

​Wallet selection

​Create a bank transfer

​Request parameters

​Response (success) - HTTP 201

​Get bank transfer availability

​Get transfer details

​Validate bank account

​Request parameters

​Response (success)

​Response fields

​Validation errors

​Get supported banks

​Usage tips

​Transfer statuses

​Prerequisites

​Best practices

Check availability

Verify balance

Handle webhooks

Store references

Check status

Validate first

​Error responses

​Debugging & logging

API vs dashboard

How bank transfers work

API endpoints

Authentication

Wallet selection

Create a bank transfer

Request parameters

Response (success) - HTTP 201

Get bank transfer availability

Get transfer details

Validate bank account

Request parameters

Response (success)

Response fields

Validation errors

Get supported banks

Usage tips

Transfer statuses

Prerequisites

Best practices

Error responses

Debugging & logging