Transfers between wallets

Move money between your organisation’s own wallets: to fund a project from collections, split income, or settle internal accounts. Transfers need a key that can move money, and only go between your own wallets.

A transfer

curl https://api.catholicpay.example/api/v1/merchant/remittance \
  -H "Authorization: Bearer $CATHOLICPAY_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_wallet_id": "…",
    "amount": "20000.00",
    "narration": "Building levy",
    "reference": "LEV-2026-11"
  }'

It moves from source_wallet_id (your main wallet by default) before the response (201). The response is the transfer, with its status.

Your mandate applies. If your organisation’s mandate says your signatories must approve a transfer like this one, it waits as AWAITING_APPROVAL until they do in the portal.

A wallet set to pay only whitelisted accounts cannot send to another wallet by API (422 WALLET_PROTECTED): an admin does that in the portal.

Check a destination first with POST /merchant/remittance/account-query ({"account_number": "…"}): it names one of your own account or wallet numbers.

Bulk transfers

Up to 200 lines from one wallet:

{
  "source_wallet_id": "…",
  "remittances": [
    { "destination_wallet_id": "…", "amount": "5000.00", "narration": "Youth", "reference": "SPLIT-1" },
    { "destination_wallet_id": "…", "amount": "7500.00", "narration": "Charity", "reference": "SPLIT-2" }
  ]
}

Everything is checked first (every wallet, and the total against the available balance), so a bulk transfer is refused whole or accepted whole. Then the lines run in the background: the response is 202 with status PROCESSING. Each line is its own transfer with its own outcome, never paid twice. You hear remittance.completed when it finishes, or get it with GET /merchant/remittances/{remittance_id}.

List transfers with GET /merchant/remittances (status, kind: SINGLE or BULK).

Test it

With a test key, sandbox money moves between your sandbox wallets. Fund them first with a simulated inflow.