Quickstart: Accept Your First Payment

Get a test API key, create a hosted checkout session, and handle signed webhook notifications.

Try it in Test Mode First

Test mode moves no real money. Payments, transfers and payouts are simulated, and still create double-entry journal postings in a separate test ledger.

1Get your Test Secret Key

Log into your rafiqPay Dashboard, switch to Test Mode, and navigate to Developers → API Keys. Your secret key starts with rp_test_sk_.

Sample key in the examples

This is an example and does not work. Use the header key menu to switch to a placeholder, then put in your own key.

rp_test_sk_kanzu_9f8a7b6c5d4e3f2a

2Create a Checkout Session

Make a POST /v1/checkout/sessions request to create a payment session. The response contains a url that you redirect your customer to.

Create Checkout Session

cURL · v1

curl -X POST https://api.rafiqpay.net/v1/checkout/sessions \
  -H "Authorization: Bearer rp_test_sk_kanzu_9f8a7b6c5d4e3f2a" \
  -H "Idempotency-Key: KNZ_TUITION_2026_001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "25000.00",
    "currency": "NGN",
    "customerEmail": "student@kanzu.example",
    "customerName": "Ibrahim Danladi",
    "description": "Tuition - Web Development Immersive",
    "orderReference": "KNZ_TUITION_2026_001",
    "successUrl": "https://kanzulearning.com/checkout/success?session={CHECKOUT_SESSION_ID}",
    "cancelUrl": "https://kanzulearning.com/checkout/cancelled"
  }'

Parameter	Type	Requirement	Description
amount	string (decimal)	Required	The payment amount in major units (e.g. "25000.00" for ₦25,000.00).
currency	string	Optional	Only "NGN". Defaults to NGN.
customerEmail	string	Required	The customer’s email.
orderReference	string	Optional	Your own order number, returned on the session and its webhooks.

3Verify Webhook Signatures

Never rely on client-side redirects to fulfil orders. rafiqPay sends an HMAC-SHA256 signed HTTP POST to your webhook endpoint when the session is paid. Verify the signature on the raw body before parsing it.

Verify and Handle Webhook

cURL · v1

// Incoming HTTP POST from rafiqPay (an example)
// Header: RafiqPay-Signature: t=1760980800,v1=9f8e7d...
{
  "id": "evt_01HXYZ87654321",
  "object": "event",
  "type": "checkout.session.completed",
  "createdAt": "2026-10-20T14:32:00.000Z",
  "mode": "test",
  "data": {
    "object": {
      "id": "cs_test_01HXYZA1B2C3D4",
      "object": "checkout.session",
      "status": "complete",
      "currency": "NGN",
      "amount": "25000.00",
      "amountKobo": "2500000",
      "customerEmail": "student@kanzu.example",
      "orderReference": "KNZ_TUITION_2026_001",
      "metadata": null,
      "chargeId": "pay_01HXYZ55",
      "reference": "RP-41207733A1F2",
      "fee": "375.00",
      "feeKobo": "37500"
    }
  }
}

4Test Payments & Bank Transfers

No real card or bank is involved in test mode. Use these routes to pretend the customer paid:

Successful Payment

POST /v1/public/checkout/sessions/:id/simulate

Completes the test checkout as if the customer paid.

You get checkout.session.completed and charge.succeeded.

Bank Transfer

POST /v1/public/checkout/sessions/:id/bank-transfer/simulate

Sends money to the one-time account the checkout opened.

Pass a different amount to see a held transfer.