API Reference/Treasury

Treasury

Endpoints for managing the flow of funds outside the platform. Issue withdrawals to external bank accounts, manually capture incoming bank funds, and manage the fee configurations.

Withdrawals

When a user requests to move their funds out of SwitchLock and into their physical bank account, you initiate a withdrawal. The x-idempotency-key header is strictly required to prevent accidental double-withdrawals.

POST

/v1/treasury/withdraw

Initiates a withdrawal from a user account to an external bank account.

Auth

Field	Type	Required	Description
accountId	uuid	Yes	The UUID of the account to withdraw from.
amount	integer	Yes	Amount to withdraw in cents (e.g., 100 for $1.00).
externalReference	string	Yes	Unique reference identifier for the withdrawal.
bank_name	string	Yes	Name of the recipient institution.
branch_code	string	Yes	Branch code of the recipient institution.
account_number	string	Yes	Account number of the recipient.
account_name	string	Yes	Name on the recipient account.

curl -X POST "https://api.switchlock.co.zw/v1/treasury/withdraw" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..." \
  -H "Content-Type: application/json" \
  -d '{
  "accountId": "string",
  "amount": 1000,
  "externalReference": "string",
  "bank_name": "string",
  "branch_code": "string",
  "account_number": "string",
  "account_name": "string"
}'

Response Example

{
  "id": "txn_01HXYZ...",
  "status": "PROCESSING",
  "amount": "5000",
  "reference": "WD-01HXYZ",
  "created_at": "2026-06-23T11:00:00.000Z"
}

Idempotency required: You must send a unique x-idempotency-key header with this request. If your network connection drops and you retry the same request with the same key, you will safely receive the existing transaction back without double-charging the user.

Manual Bank Capture

If a deposit arrives in your physical bank account via a wire transfer (rather than a payment link), you must manually capture it into the system to keep the physical bank balance in sync with the ledger.

POST

/v1/treasury/bank/capture

Manually records an external bank receipt into the ledger system.

Auth

Field	Type	Required	Description
amount	integer	Yes	Amount in cents.
currency	enum	Yes	Currency code (USD, ZIG).
reference	string	Yes	Bank transaction reference.

curl -X POST "https://api.switchlock.co.zw/v1/treasury/bank/capture" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..." \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 1000,
  "currency": "string",
  "reference": "string"
}'

Configuration

POST

/v1/treasury/seed-configs

Internal utility to populate default fee structures (IMTT rates and platform default fees).

Auth

curl -X POST "https://api.switchlock.co.zw/v1/treasury/seed-configs" \
  -H "x-api-key: zl_sk_your_key_here" \
  -H "x-company-id: cmp_01HXYZ..."

Response Example

{
  "message": "Initial fee configurations seeded successfully"
}

Next steps

Companies API

Manage your tenants and API keys.

Fees & Taxes

Understand the fee engine.