Quick start

This takes you from a test key to your first payment, in the sandbox, with no real money.

1. Get a test key. An admin of your organisation creates one in the CatholicPay portal, under Developers → Keys → New key, mode Test. The key (cp_test_…) is shown once: store it in your secrets manager.

   CatholicPay switches the API on for your organisation first: ask your CatholicPay contact.

2. Check the key works. Ask who you are:

   cURL

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

   Node.js

   const res = await fetch('https://api.catholicpay.example/api/v1/merchant/me', {
     headers: { Authorization: `Bearer ${process.env.CATHOLICPAY_SECRET_KEY}` },
   });
   console.log(await res.json());

   Python

   import os, requests
   
   res = requests.get(
       "https://api.catholicpay.example/api/v1/merchant/me",
       headers={"Authorization": f"Bearer {os.environ['CATHOLICPAY_SECRET_KEY']}"},
   )
   print(res.json())

   The response names your organisation and says "mode": "TEST".

3. Take a payment. Create a one-off account number for ₦45,000:

   cURL

   curl https://api.catholicpay.example/api/v1/merchant/account-numbers \
     -H "Authorization: Bearer $CATHOLICPAY_SECRET_KEY" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{"kind": "ONE_OFF", "reference": "INV-1001", "amount": "45000.00", "expires_in_minutes": 60}'

   Node.js

   import { randomUUID } from 'node:crypto';
   
   const res = await fetch('https://api.catholicpay.example/api/v1/merchant/account-numbers', {
     method: 'POST',
     headers: {
       Authorization: `Bearer ${process.env.CATHOLICPAY_SECRET_KEY}`,
       'Idempotency-Key': randomUUID(),
       'Content-Type': 'application/json',
     },
     body: JSON.stringify({ kind: 'ONE_OFF', reference: 'INV-1001', amount: '45000.00', expires_in_minutes: 60 }),
   });
   const { data } = await res.json();
   console.log(data.account_number, data.bank_name);

   Python

   import os, uuid, requests
   
   res = requests.post(
       "https://api.catholicpay.example/api/v1/merchant/account-numbers",
       headers={
           "Authorization": f"Bearer {os.environ['CATHOLICPAY_SECRET_KEY']}",
           "Idempotency-Key": str(uuid.uuid4()),
       },
       json={"kind": "ONE_OFF", "reference": "INV-1001", "amount": "45000.00", "expires_in_minutes": 60},
   )
   data = res.json()["data"]
   print(data["account_number"], data["bank_name"])

   In live, you show the payer this number and they transfer to it from any bank.

4. Play the payer. In the sandbox you make the transfer yourself:

   curl -X POST https://api.catholicpay.example/api/v1/merchant/sandbox/account-numbers/INV-1001/pay \
     -H "Authorization: Bearer $CATHOLICPAY_SECRET_KEY"

5. Confirm it was paid.

   curl https://api.catholicpay.example/api/v1/merchant/verify/INV-1001 \
     -H "Authorization: Bearer $CATHOLICPAY_SECRET_KEY"

   status is now PAID. If you set a webhook URL, you also received account_number.paid.

Next steps

• Set up webhooks so your system hears about payments as they happen.
• Learn the API basics: responses, errors, pagination and idempotency.
• When your integration works in the sandbox, go live.