1. Prerequisites

• Generate a partner API key with the payments scope — API Keys section, this portal.
• Register a webhook subscribed to the payment lifecycle events — Webhooks section, this portal.
• Have at least one approved maker user and one approved beneficiary on your corporate account.

2. Create a checkout session — server-to-server only

Call this from your backend, using your secret API key. Never call it from a browser or embed the key in client code.

curl -X POST https://<bank-api-host>/v1/partner/payout-checkout/sessions \
  -H "x-api-key: cms_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: order-88213-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{
    "makerUserId": "user-1780460729021-815",
    "amount": { "value": 125000, "currency": "INR" },
    "transactionReference": "order-88213",
    "beneficiaryId": "bene-acme-vendor-001",
    "redirectUrl": "https://your-erp.example.com/payments/return",
    "cancelUrl": "https://your-erp.example.com/payments/cancelled",
    "metadata": { "orderId": "88213", "department": "procurement" }
  }'

{
  "sessionId": "pcs_live_5f2a9c1e4b3d4a2e9f6c7d8e1a2b3c4d",
  "token": "9f86d081884c7d659a2feaa0c55ad015",
  "hostedUrl": "https://checkout.example-bank.com/payout/9f86d081884c7d659a2feaa0c55ad015",
  "expiresAt": 1785400200000
}

3. Redirect the maker's browser

A full-page redirect, not an iframe embed — this is what lets one integration work identically for a browser-based ERP and a native app like Tally that can only open a system browser.

// your frontend / ERP, after calling your own backend
// which in turn called the API above
window.location.assign(session.hostedUrl);

4. What the maker does — no work required from you

• Reviews the frozen amount, beneficiary, and your reference.
• Picks a package, debit account, and payment method — automatically filtered to what their role permits.
• Requests and enters a one-time code sent to their own registered email.
• Is redirected to your redirectUrl (or cancelUrl if they cancel).

Explicit cancellation on the hosted page first terminates the session on the server (marking it cancelled) and then returns the maker to your cancelUrl. Closing the browser tab or navigating away does not cancel the session — untouched sessions expire through the normal 15-minute TTL. Your backend can confirm cancellation by polling GET /v1/partner/payout-checkout/sessions/:sessionId.

The payout then enters the same approval matrix, CBS debit, and clearing pipeline as every other payment channel — checker approval still applies unless a no-approval tier is configured.

5. Reconcile — reuse your existing webhook integration

Store the sessionId returned when you create the session. Redirect and cancel URLs are navigation-only: they do not contain a transaction ID. Poll the session endpoint with that stored ID to reconcile the hosted checkout.

Before the maker completes authorization, transaction is null. Once it is present, use transaction.transactionId for Partner API authorization, transaction-status calls, and webhook correlation. A submitted checkout has been accepted for approval; it is not yet a settled payment.

{
  "checkout": {
    "sessionId": "pcs_live_5f2a9c1e4b3d4a2e9f6c7d8e1a2b3c4d",
    "status": "submitted",
    "expiresAt": "2026-08-01T10:30:00.000Z",
    "completedAt": "2026-08-01T10:18:42.000Z"
  },
  "transaction": {
    "transactionId": "batch-pcs-5f2a9c1e4b3d",
    "transactionReference": "order-88213",
    "status": "pending_approval"
  }
}

Correlate lifecycle webhooks by data.object.transactionId, the same transaction ID returned by session polling.

{
  "id": "evt_...",
  "type": "transaction.paid",
  "created": 1785400300000,
  "data": {
    "object": {
      "object": "transaction",
      "transactionId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "jobId": null,
      "apiRefNumber": "order-88213",
      "reference": "order-88213",
      "status": "paid",
      "source": "payout_checkout",
      "amount": { "value": 125000, "currency": "INR" },
      "utr": "HDFCN2026080100778",
      "bankReference": "BANKALPHA-DISP-6BA7B810...",
      "timestamps": { "paidAt": 1785400300000 }
    }
  }
}

Subscribe to webhooks for final payment outcomes. Polling the checkout session is useful for recovering the transaction ID, not for replacing lifecycle reconciliation.