Quickstart

Four things have to be true before a payment can complete: your account is active, you hold an API key, at least one phone is paired with your receiving number, and a callback secret is set. The going live page covers all four.

1. Open a checkout session

Send the amount and your own order reference. Everything else is optional, but a webhook_url is what makes the payment reach your server without polling.

POST /api/v1/checkout/initialize

curl -X POST "$KRONX_BASE_URL/api/v1/checkout/initialize" \
  -H "x-api-key: $KRONX_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "amount": "1200.00",
    "order_id": "ORD-1042",
    "customer_name": "Rumana Akter",
    "customer_contact": "01711111111",
    "success_url": "https://yourshop.example/orders/ORD-1042/thanks",
    "cancel_url": "https://yourshop.example/orders/ORD-1042",
    "webhook_url": "https://yourshop.example/webhooks/kronx"
  }'

2. Read the response

200 OK

{
  "success": true,
  "checkout_url": "https://pay.your-kronx-domain/pay/3f8c2a10-5b7e-4d21-9c6f-8e1a2b3c4d5e",
  "payment_id": "kpay_5f1c8a2d4b3e4f7a9c1d2e3f4a5b6c7d",
  "trid": "kpay_5f1c8a2d4b3e4f7a9c1d2e3f4a5b6c7d",
  "expires_at": "2026-02-28T10:51:00.000Z"
}

Store payment_id against your order. It is the same value that comes back as trid in every callback for this session, so it is what you match on later. Then redirect the buyer to checkout_url.

Calling initialize twice with the same order_id is safe.The second call returns the existing session, with the same payment_id and the same expires_at, instead of creating a second one. Retrying a timed-out request does not double-charge anyone.

3. Handle the callback

When the payment is confirmed, ToruPay POSTs this body to your webhook_url with an x-kronx-signature header.

POST your webhook_url

{
  "order_id": "ORD-1042",
  "payment_status": "COMPLETED",
  "trid": "kpay_5f1c8a2d4b3e4f7a9c1d2e3f4a5b6c7d",
  "amount": 1200
}

Verify the signature before you trust the body, then mark the order paid. The webhooks page has working verification code for Node.js, PHP and Python.

4. Test it end to end

Open a session for a small real amount against a test order.
Send that amount from a phone to your receiving number.
Enter the TrxID from the SMS on the hosted page.
Check that your endpoint received the callback and that the dashboard shows the transaction as applied.

NextAuthentication →