Card checkout

A checkout is a payment page hosted by CatholicPay. You create it, send the payer to its payment_url, and they pay by card. Card details never touch your systems.

1. Create a checkout

curl https://api.catholicpay.example/api/v1/merchant/checkouts \
  -H "Authorization: Bearer $CATHOLICPAY_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "ORD-77",
    "amount": "4000.00",
    "customer_name": "Ada Obi",
    "email": "ada@example.com",
    "redirect_url": "https://shop.example.org/thanks"
  }'

{
  "data": {
    "reference": "ORD-77",
    "amount": "4000.00",
    "fee": "60.00",
    "charged_amount": "4060.00",
    "status": "PENDING",
    "payment_url": "https://checkout.catholicpay.example/…",
    "redirect_url": "https://shop.example.org/thanks"
  }
}

The amount is at least ₦100. Your organisation’s web payment fee is added to what the payer pays: they pay charged_amount, and amount reaches your wallet (wallet_id, or your main wallet).

2. Send the payer to the page

Redirect the payer to payment_url. After paying they see the outcome, then return to your redirect_url.

3. Confirm the payment

Don’t treat the return to your redirect_url as proof of payment. Confirm it on your server, by webhook or by asking:

• Webhook: payment.succeeded or payment.failed, with the checkout.
• Ask: GET /merchant/checkouts/ORD-77, or GET /merchant/verify/ORD-77.

status is PENDING, PAID, FAILED or EXPIRED. A pending checkout is checked with the card provider when you ask, so the answer is current.

References

The same reference again returns the first checkout. With a different amount it is refused with 409 REFERENCE_USED.

Test it

In the sandbox, approve or decline the card yourself. No test card numbers are needed.