Accept a payment (Hosted Checkout)

1. Create a Checkout Session

Call POST /v1/checkout/sessions with the order amount as a Naira string, your customer’s email, and your successUrl / cancelUrl. The answer carries url: send the customer there.

curl -X POST "https://api.rafiqpay.net/v1/checkout/sessions" \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a" \
  -H "Idempotency-Key: idem_chk_kanzu_01" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "35000.00",
    "currency": "NGN",
    "customerEmail": "amina@kanzu.ng",
    "description": "Arabic Intensive Cohort 4",
    "orderReference": "KANZU-ORD-41",
    "successUrl": "https://kanzu.ng/enrolled?session_id={CHECKOUT_SESSION_ID}",
    "cancelUrl": "https://kanzu.ng/pricing"
  }'

2. What the customer sees

The checkout page offers card, bank transfer, and Pay with rafiqPay (from the customer’s rafiqPay wallet). A card payment is made on the payment provider’s page, which can also offer USSD. A customer who picks bank transfer is shown an account number, its bank and account name, the exact amount to send, and a countdown until the account closes. They send the money from their own banking app, and the page moves on by itself once it arrives.

You do not need to do anything different for bank transfers. A transfer of the right amount, in time, completes the checkout session and sends charge.succeeded, just like a card payment. See Bank transfer at checkout for what happens when a transfer does not match.

3. Fulfil the order from the webhook

Fulfil the order when charge.succeeded (or checkout.session.completed) reaches your webhook endpoint, not when the customer lands on your successUrl. A customer paying by transfer may close the page before the money arrives.

Offering to save the card

Pass saveCard: true when you create the session to show a "Save this card" box on the checkout page. The card is saved only if the customer ticks the box and pays by card. You then get payment_method.saved, and you can charge the card later without the customer present. See Saved cards.

The box is never shown unless you ask for it. The only exception is the invoice of a subscription that collects by card and has no card yet: that checkout always offers to save one.