Direct debit mandates

A mandate lets you debit a payer’s account at any bank on a schedule, for dues, fees or regular giving. The payer authorises it with their bank once; then each debit is collected into your wallet.

Create a mandate

curl https://api.catholicpay.example/api/v1/merchant/mandates \
  -H "Authorization: Bearer $CATHOLICPAY_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "MND-STU-001",
    "payer_name": "Chidi Okeke",
    "payer_phone": "+2348030002102",
    "payer_email": "parent@example.com",
    "payer_address": "12 Allen Avenue, Ikeja, Lagos",
    "account_number": "0123456789",
    "bank_code": "058",
    "amount": "15000.00",
    "frequency": "MONTHLY",
    "start_date": "2026-12-01",
    "end_date": "2027-07-01",
    "narration": "School fees"
  }'

Mandates are monthly (frequency MONTHLY). reference, amount, payer_name, payer_address, account_number and bank_code are required; the money goes to wallet_id, or your main wallet. Get bank codes from GET /merchant/banks. The mandate is PENDING until the payer authorises it with their bank.

Follow it

Event	When
mandate.updated	The mandate was authorised (ACTIVE), failed, or ended
mandate.debited	A debit succeeded or failed, with its amount and date

Or ask: GET /merchant/mandates/MND-STU-001 for the mandate (with what has been collected), and GET /merchant/mandates/MND-STU-001/transactions for its debits.

Cancel it

POST /merchant/mandates/MND-STU-001/cancel ends it: nothing more is debited.

References

The same reference again returns the first mandate (200), or 409 if the terms differ.

Test it

In the sandbox, authorise a mandate and run its debits, including failed ones.