Skip to content

PayXa Docs

Draft documentation for the proposed v1 API. Hosts ending in .example are placeholders until launch.

Quickstart

  • Create a PayXa account and open the dashboard in Test mode.
  • Copy your pxa_test_ secret key from Developers → API keys.
  • Create an order from your backend, then open checkout with the session token.
  • Register a webhook endpoint and fulfil only on payment.verified.

Core concepts

Amounts are in paise. 49900 means ₹499.00.

Detected is not verified. A detected payment has evidence (for example a credit alert) matched to one order. A verified payment has trusted confirmation from a bank or PSP source. Never fulfil on detected.

Frontend events are display-only. Callbacks from the checkout script update your UI. Fulfilment happens on your backend, from a signed webhook or a status you fetched yourself.

Create an order

Always compute the price on your server. Send an Idempotency-Key so retries never create duplicates.

curl https://api.payxa.example/v1/orders \
  -H "Authorization: Bearer pxa_test_..." \
  -H "Idempotency-Key: 7f9c..." \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_order_id": "ORDER-1001",
    "amount": 49900,
    "currency": "INR",
    "customer": { "reference": "customer_102" },
    "checkout": { "expires_in_seconds": 300 }
  }'

Handle webhooks

  • Verify the HMAC-SHA256 signature over the timestamp and raw body.
  • Reject timestamps older than five minutes.
  • Store the event ID and ignore duplicates. Deliveries are at-least-once.
  • Return 2xx quickly; do slow work asynchronously.

See the full sample in the developer hub.

Pair a device

  • Install PayXa Merchant from the official download page.
  • In the dashboard, open Devices → Pair new device to show a short-lived QR.
  • Scan it in the app, then grant push and (optionally) notification access.
  • Run the device diagnostics check before going live.

Testing

Test mode can trigger checkout started, detected, verified, late payment, same-amount conflict and device offline events. Use the webhook tester to send any event to your endpoint.