📖 API Reference

Build custom checkout integrations using our REST endpoint architectures and secure webhook relays.

Authentication

Authenticate API requests by passing your workspace private secret key inside the HTTP `Authorization` header. Private keys are prefixed with hp_test_sk_ (for Test Environment) or hp_live_sk_ (for Production Live Environment).

Provide an optional Idempotency-Key header to safely retry requests without accidentally generating duplicates.

Create Order

POST/api/v1/orders

Registers a client order specifying transaction amounts (in minor currency units, e.g. 150000 paise for INR 1500) and buyer contact attributes. Returns the created order object.

Create Checkout Session

POST/api/v1/checkout-sessions

Generates a hosted payment portal URL for a pre-registered order. Redirect buyers to the generated checkout_url to display scan-and-pay UPI screens.

Webhook Verification

HollowPay signs webhook POST events using an `HMAC-SHA256` signature included in the `HollowPay-Signature` header. The signature contains timestamp payloads (in milliseconds) to prevent replay attacks.

HTTP Authorization Headers

Authorization: Bearer hp_test_sk_abc123...
Idempotency-Key: idemp-hash-key-value

cURL Request: Create Order

curl -X POST https://api.hollowpay.com/api/v1/orders \
  -H "Authorization: Bearer hp_test_sk_abc123" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_12345" \
  -d '{
    "amount_minor": 150000,
    "currency": "INR",
    "description": "Premium License Key Deployment",
    "customer": {
      "name": "Jane Miller",
      "email": "jane@example.com",
      "phone": "+91 98765 43210"
    }
  }'

Response Payload: Create Order

{
  "success": true,
  "order": {
    "id": "ord_zdc8192a8381",
    "amount_minor": 150000,
    "currency": "INR",
    "description": "Premium License Key Deployment",
    "status": "created",
    "created_at": "2026-07-08T07:22:00Z"
  }
}

cURL Request: Create Checkout

curl -X POST https://api.hollowpay.com/api/v1/checkout-sessions \
  -H "Authorization: Bearer hp_test_sk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ord_zdc8192a8381",
    "redirect_url": "https://myshop.com/success"
  }'

Response Payload: Create Checkout

{
  "success": true,
  "checkout_session": {
    "id": "cs_081a92b3810a",
    "order_id": "ord_zdc8192a8381",
    "checkout_url": "https://hollowpay.com/pay/c/cs_081a92b3810a",
    "status": "active"
  }
}

Node.js: Verify Webhook Signature

const crypto = require('crypto');

function verifyWebhook(payload, signatureHeader, secret) {
  const [timestamp, signature] = signatureHeader.split(',');
  const signedPayload = `${timestamp}.${payload}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');
  return signature === expectedSignature;
}