For POS engineers + kiosk integrators

Balaji PayIntegration spec

Add Balaji Pay as a payment option on a kiosk POS in two endpoints — one outbound POST, one signed callback. We handle the underlying processor (card via hosted checkout, carrier billing, regional methods), so you only ever integrate against this contract.

00TL;DR

01Authentication

appkey:    <your_appkey>
random:    <fresh_nonce>                    // 32-char hex recommended
signature: md5(appkey + random + appsecret)  // lowercase hex
Content-Type: application/x-www-form-urlencoded

The randomnonce should be fresh per request. We don't enforce a replay window server-side at v1, but a varying nonce means observed requests aren't trivially replayable, and it makes the signature non-deterministic across calls (handy for log forensics). Keys are issued one per environment (sandbox + production) and rotated on request — no integration changes when we rotate, you just receive a new value via the credential handoff portal.

02Request

Production: POST https://pay.balajibrands.com/payment/create
Sandbox: POST https://balaji-pay-sandbox.vercel.app/payment/create

payment_sn=P-2026-0042-271699
&order_sn=ORD-2026-0042
&device_type=printer
&trade_amount=49.99
&body=Phantom%203%20Custom%20Print
&notify_url=https%3A%2F%2Fyour-pos.example%2Fbalaji-pay%2Fcallback
&redirect_url=https%3A%2F%2Fyour-pos.example%2Forder%2F271699
&device=%7B%22id%22%3A%22CCK020-SANDBOX%22%7D         // JSON-string-embedded
&sku=%7B%22name%22%3A%22iPhone%2015%20Pro%20Max%22%7D // optional
&phone=%7B%22number%22%3A%22%2B12135551234%22%7D            // optional

03Response

200 OK with a wire envelope that wraps the actual payload in data. Read code === 1 as success; anything else is an error (see §09).

{
  "code": 1,
  "msg":  "success",
  "data": {
    "transaction_id": "txn_PCAa9dQ7fMNxfu1aPxHd",
    "cashier_url":    "https://pay.balajibrands.com/c/hck_yx7uDuTlgZnCMkZSjF4V"
  }
}

04Callback

When a payment succeeds we POST a signed notification to the notify_url you provided on the original /payment/create.

Headers:
  appkey:    <our_appkey>
  random:    <fresh_nonce>
  signature: md5(appkey + random + appsecret)
  Content-Type: application/x-www-form-urlencoded

Body:
  payment_sn=P-2026-0042-271699
  &transaction_id=txn_PCAa9dQ7fMNxfu1aPxHd
  &trade_amount=49.99
  &paytime=1746058214

Reply with HTTP 200 + the literal body SUCCESS to acknowledge. Anything else triggers our retry sweep — exponential backoff capped at 30 minutes, max 10 attempts, ~1h50m total before the notification is flagged for manual reconciliation in the admin ops queue.

Notifications are at-least-once. Use payment_sn as your idempotency key — duplicate deliveries for the same payment must be no-ops in your handler.

05Signature

import { createHash, timingSafeEqual } from "crypto";

function verify(headers, appsecret) {
  const appkey    = headers["appkey"];
  const random    = headers["random"];
  const presented = (headers["signature"] || "").toLowerCase();
  if (!appkey || !random || !presented) return false;

  const expected = createHash("md5")
    .update(appkey + random + appsecret)
    .digest("hex");

  if (presented.length !== expected.length) return false;
  return timingSafeEqual(
    Buffer.from(presented, "hex"),
    Buffer.from(expected, "hex")
  );
}

06Status query

When the customer returns to your redirect_urlafter payment terminates, query the canonical status before you mark the order paid. The success callback is reliable but async — query first if you need an immediate decision in the customer's flow.

GET /payment/query?transaction_id=<txn_*>
Same appkey / random / signature headers as /payment/create.

{
  "code": 1,
  "msg":  "success",
  "data": {
    "transaction_id": "txn_PCAa9dQ7fMNxfu1aPxHd",
    "payment_sn":     "P-2026-0042-271699",
    "status":         1,                  // 0 = unpaid, 1 = paid, 2 = refunded
    "paytime":        1746058214,
    "refund_amount":  "0.00",
    "refund_time":    0
  }
}

07Refund

Issue a full refund against a paid transaction. Partial refunds are not supported at v1.

POST /payment/refund, form-urlencoded body, same appkey / random / signature headers.

transaction_id=txn_PCAa9dQ7fMNxfu1aPxHd
&reason=Customer%20requested%20cancellation  // optional

{
  "code": 1,
  "msg":  "success",
  "data": {
    "refund_id": "rfnd_a3f9c08b1234"
  }
}

A subsequent /payment/query on the same transaction_id will surface status: 2 + populated refund_amount and refund_time.

08Status taxonomy

The status field on /payment/query is a three-state enum:

09Errors

OpenPay errors return HTTP 200 with code in the 1001–1500 range. The HTTP status reflects whether we failed (5xx) versus whether your request failed (200 + non-1 code).

10Credential handoff

During onboarding (and on rotations) Balaji ships your appkey + appsecret via a passphrase-gated handoff portal — never raw email, never Slack DM, never voice.

11Phase-1 (legacy)

The original Balaji Pay contract used Bearer auth on POST /api/checkouts with a JSON body, plus an HMAC-SHA256 callback to a fixed URL per environment. It's still alive — partners integrated before 2026-04-30 don't need to migrate immediately. New integrations should use the OpenPay spec above.

The legacy Phase-1 sandbox tools still mint and verify against the original contract — useful if you're debugging an existing integration before migrating.

Ready to wire it up? Try the sandbox →