Skip to content
CatholicPayDevelopers

Wallet payment requests

When your payer uses the CatholicPay app, you can ask them to pay from their CatholicPay wallet. They see the request in the app and approve it with their PIN, or decline it.

Terminal window
curl https://api.catholicpay.example/api/v1/merchant/payment/charge-wallet \
  -H "Authorization: Bearer $CATHOLICPAY_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+2348030000073",
    "amount": "2500.00",
    "transaction_ref": "DUES-2026-11-073",
    "description": "November dues"
  }'

Find the member by phone or email. The request is PENDING until they answer:

Event When
payment_request.paid They approved: the money is in your wallet (wallet_id, or your main wallet)
payment_request.declined They declined

A request nobody answers within 24 hours (expires_at) becomes EXPIRED. No webhook is sent for that: check pending requests with GET /merchant/payment-requests/DUES-2026-11-073.

Each transaction_ref is used once: the same one again returns the first request (200).

In the sandbox members are not present, so a request is paid at once and no money moves.