Buckzy API docs

Authentication

Sandbox key for this demo: rz_test_bckz_live_demo. In production you send it as HTTP Basic on every server-side call. Never put the live secret in a browser.

Create an order

The ecommerce backend creates an order before the shopper sees checkout. Amount is in rupees for this sandbox (production would use paise).

POST /v1/orders
{
  "amount": 2499.00,
  "currency": "INR",
  "receipt": "ATLAS-1042",
  "customer": { "name": "Asha Rao", "email": "asha@store.in" },
  "methods": ["upi_intent", "upi_collect", "upi_qr", "card", "netbanking", "wallet"],
  "notes": { "title": "Sonic buds" },
  "callback_url": "https://atlas.example/orders/thanks"
}

→
{
  "id": "order_m4k2ab",
  "status": "created",
  "checkout_url": "https://checkout.buckzy.com/order_m4k2ab"
}

Hosted checkout

Redirect the shopper to checkout_url. After pay they return to callback_url. Do not mark the sale paid from that redirect. Wait for the webhook, or poll GET /v1/orders/:id.

Payment methods

Code	What Buckzy does
upi_intent	Opens GPay / PhonePe / Paytm / BHIM with a transaction reference.
upi_collect	Sends a collect request to the VPA the shopper typed.
upi_qr	Issues a dynamic QR bound to the order amount.
card	Hosted card fields + 3DS. You receive a token, never PAN.
netbanking	Bank redirect. Final state from bank callback.
wallet	Wallet authorize + capture.

Webhooks

Posted to the merchant endpoint. Sign every body with HMAC-SHA256. Retry 8 times. Return 401 if the signature fails — Buckzy will retry, the merchant must not fulfill.

X-Buckzy-Signature: t=1758777600,v1=3c1b0e…

signed_payload = "{t}.{raw_body}"
v1 = hex(HMAC_SHA256(webhook_secret, signed_payload))

# Node
const crypto = require("crypto");
const expected = crypto
  .createHmac("sha256", process.env.BUCKZY_WEBHOOK_SECRET)
  .update(`${t}.${rawBody}`)
  .digest("hex");
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1))) {
  return res.status(401).end();
}
if (Math.abs(Date.now()/1000 - t) > 300) return res.status(401).end();

Sandbox secret: whsec_bckz_sandbox_4e2f9a. Playground: dashboard → Webhooks.

payment.captured
{
  "event": "payment.captured",
  "id": "evt_…",
  "created_at": 1758777600,
  "payload": {
    "id": "BCKZLIVE…",
    "order_id": "order_m4k2ab",
    "amount": 2499.00,
    "method": "UPI Intent (GPay)",
    "status": "SUCCESS"
  }
}

Sandbox decline

Use VPA containing fail, or tick Simulate failure on checkout, to get U05 Insufficient Funds.

This documentation describes the sandbox in these HTML files. The demo store calls Buckzy.createOrder() in js/api.js and writes into the same ledger the dashboard reads.