Payer wallets & funding

A payer is a customer with their own wallet on your account and a permanent account number their family pays into. You then charge the wallet for what they owe: fees, uniforms, trips. The money never leaves your account: it moves from the payer’s wallet into yours.

1. Sync a payer

curl https://api.catholicpay.example/api/v1/merchant/customers/webpayers/sync \
  -H "Authorization: Bearer $CATHOLICPAY_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "external_reference": "STU-001" }'

Name an existing customer by customer_id or external_reference; with first_name and last_name too, a customer is created if none exists. The response’s payer has their wallet_id and account_number. Syncing again only updates their details (200).

2. Their family pays in

Give the family the payer’s account number. Each payment credits the payer’s wallet and sends customer.funded, with the amount and the sender.

For a set amount, such as a term’s fees, issue a one-off number:

curl https://api.catholicpay.example/api/v1/merchant/customers/{id}/webpayer/funding-account \
  -H "Authorization: Bearer $CATHOLICPAY_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "amount": "45000.00" }'

It lasts expires_in_minutes: from 15 minutes to 90 days, 30 days by default. Look it up with GET /merchant/funding-accounts/{reference}.

3. Charge the wallet

curl https://api.catholicpay.example/api/v1/merchant/customers/{id}/webpayer/charge-wallet \
  -H "Authorization: Bearer $CATHOLICPAY_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "30000.00",
    "transaction_ref": "FEES-T1-001",
    "description": "First term fees"
  }'

The amount moves from the payer’s wallet into wallet_id (your main wallet by default) and you hear customer.charged. Charging needs a key that can move money.

• Each transaction_ref is charged once: the same one again returns the first charge (200).
• A wallet without enough money gives a charge with status FAILED, kept on record. Nothing moves.
• Up to 50 charges at once: POST …/webpayer/charge-wallets with {"charges": [ … ]}. Each item answers for itself, with its charge or its error.

See the wallet’s history

GET /merchant/customers/{id}/transactions lists the payer wallet’s latest 100 entries: payments in and charges out, newest first.

Test it

In the sandbox, fund a payer yourself, then charge them.