Withdrawals

A withdrawal sends money from one of your wallets to a bank account. It is a payout under your organisation’s mandate: your signers verify and approve it in the portal before the bank sends it, as for any payout your organisation makes.

Requirements

• A live key that can move money, created by an admin in the portal. The withdrawal is prepared in that admin’s name.
• At least ₦1,000.
• One withdrawal every 15 seconds per key (429 WITHDRAWAL_TOO_SOON).

Create a withdrawal

curl https://api.catholicpay.example/api/v1/merchant/withdrawals \
  -H "Authorization: Bearer $CATHOLICPAY_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "WD-2026-001",
    "wallet_id": "…",
    "amount": "250000.00",
    "bank_account_id": "…",
    "narration": "Diocesan levy"
  }'

Send it to one of your organisation’s saved bank accounts (bank_account_id), or to any account (account_number with bank_code).

Follow it

status	Meaning
PENDING_VERIFICATION	Waiting for your verifiers
PENDING_APPROVAL	Waiting for your approvers
COMPLETED	Sent by the bank
REJECTED	A signer rejected it; nothing was sent
FAILED	The bank could not send it

Get it with GET /merchant/withdrawals/WD-2026-001, with its signatures and outcome, or watch wallet.debited. The same reference again returns the first withdrawal (200). List them with GET /merchant/withdrawals.

Whitelisted accounts

Accounts your admins whitelist on a wallet in the portal can receive withdrawals from that wallet once a cooling-off period has passed:

curl https://api.catholicpay.example/api/v1/merchant/whitelisted-accounts \
  -H "Authorization: Bearer $CATHOLICPAY_SECRET_KEY"

Each shows can_receive_funds, minutes_until_available and signer_status. Pay one with POST /merchant/whitelisted-accounts/withdraw (wallet_id, bank_account_id, amount, at least ₦50).

Your signers approve each whitelisted account once in the portal. After that (signer_status: "APPROVED"), withdrawals to that account from that wallet go without further signatures. Until then they wait for your signers like any withdrawal.

Withdrawals need a live key: with a test key they are refused (422 LIVE_ONLY), and the whitelist is empty.