StaarPG Developer Docs

1Quick start

Every payout is two calls: reserve, then execute. A third, read-only call checks status. That's the entire integration surface.

1. InitSend beneficiary + amount, encrypted, signed. Get back a transaction_id valid for 5 minutes.
2. ExecuteSend the transaction_id back with the identical amount / account / IFSC. Funds move.
3. ResolveListen for the webhook, or poll Status. Read outcome from response_code, never from the HTTP status code.

2Authentication & headers

Every request — including reads — carries these four headers. X-Signature is the one exception: it's required on Init only.

3Encryption

Two independent schemes exist in this API. They share a name (AES-256-GCM) and nothing else. Confusing them is the single most common integration failure we see.

Request & response payloads

Every POST body and every response body (on success) is wrapped as {"data": "<encrypted>"}.

Key derivation & wire format

key   = sha256(api_key + hash_key)              // 32 raw bytes
nonce = random(12 bytes)
wire  = nonce.hex() + ":" + ciphertext.hex() + ":" + tag.hex()

Decrypting a response uses the identical key and format — one implementation handles both directions.

✓ Worked example — illustrative demo credentials, round-trip verified

Using illustrative credentials api_key = demo_5f8a2c91, hash_key = demo_hashkey_b73e19 — never your live keys:

{"amount":"670.00","beneficiary_account":"409002010584125","beneficiary_bank":"UNION BANK OF INDIA","beneficiary_ifsc":"UBIN0822116","beneficiary_name":"SYEDSURAJ","currency":"INR","merchant_ref":"ORDER-20260907-0142","mobile":"7386462468","route_name":"IDFC_ROUTE_001","transfer_type":"IMPS","uid":"CUST-9042"}

{"data":"4f3a1c9e0b7d2f8a11c9d4a2:bbc23a5e…372a3d72:eb8ac10a8c97c3233d4faf71984a10dd"}

Webhooks use a different scheme

Webhook deliveries are encrypted separately, with a different key and a different wire format. You need a second decrypt function for them.

4Request signature

Init requests must carry X-Signature — a keyed SHA-256 over the request metadata plus a hash of the exact body you send.

enc_key   = sha256(api_key + hash_key).hexdigest()
body_hash = sha256(request_body_bytes).hexdigest()
message   = api_key + "|" + timestamp + "|" + merchant_ref + "|" + amount + "|" + body_hash
X-Signature = sha256(message + enc_key).hexdigest()

Practical rule: encrypt first, keep the exact string you're about to POST, hash that string, sign, then send it unchanged. Don't let your HTTP client re-serialize the body after you've hashed it.

✓ Worked example — continues the payload above

Same request: api_key = demo_5f8a2c91, hash_key = demo_hashkey_b73e19, timestamp = 1757260800, merchant_ref = ORDER-20260907-0142, amount = 670.00. The body hashed below is the literal {"data":"…"} string — not the plaintext.

5Validation order

Checks run top-to-bottom and stop at the first failure. A failure earlier in the list masks anything that would have failed later — testing "does my bad signature get rejected" with an amount outside the route's limit will always show 105, never 109.

POST /payout/init/ and /payout/bank/init/

POST /payout/ (execute)

6Transaction flow

A transaction_id from Init is single-use and expires 5 minutes after issue. Execute must reuse it — and must repeat the same amount, transfer_type, beneficiary_account and beneficiary_ifsc from Init, exactly.

7Endpoints

POST https://payout.staarpg.com/api/v3/payout/init/

Own-route merchants. You supply route_name, mapped to your own bank account. Includes a wallet soft-check (step 15 above).

uid, mobile, merchant_ref, amount, currency,
transfer_type, route_name,
beneficiary_name, beneficiary_account,
beneficiary_ifsc, beneficiary_bank
// optional: email, upi, beneficiary_mobile

API-KEY:        demo_5f8a2c91
X-Timestamp:    1757260800
X-Merchant-Ref: ORDER-20260907-0142
X-Signature:    795c071ce19f1d374c72438858ab9b7fa5586faf894d68bc34dfa5244cd28751
Content-Type:   application/json
Body:           {"data":"4f3a1c9e0b7d2f8a11c9d4a2:bbc23a5e…372a3d72:eb8ac10a8c97c3233d4faf71984a10dd"}

{"status":"success","response_code":"000",
 "data":{"transaction_id":"110709070745213648","pg_ref":"110709070745213648","expires_in":300},
 "message":"","timestamp":"1757260801"}

POST https://payout.staarpg.com/api/v3/payout/bank/init/

Platform-route merchants. Identical body to above, without route_name — an acquirer is auto-selected. No wallet-balance step exists on this path — billing is handled outside the per-call wallet check.

POST https://payout.staarpg.com/api/v3/payout/

Execute — the shared second call for both routing modes. No X-Signature header.

transaction_id, amount, transfer_type,
beneficiary_account, beneficiary_ifsc
// each must equal what you sent to /init/, exactly

{"transaction_id":"110709070745213648","amount":"670.00","transfer_type":"IMPS",
 "beneficiary_account":"409002010584125","beneficiary_ifsc":"UBIN0822116"}

{"status":"success","response_code":"001",
 "data":{"pg_ref":"110709070745213648","merchant_ref":"ORDER-20260907-0142",
         "status":"Pending","bank_ref":"","amount":"670.00"},
 "message":"Transaction is being processed. Poll https://payout.staarpg.com/api/v3/payout/status/110709070745213648/ for the final result."}

GET https://payout.staarpg.com/api/v3/payout/status/<pg_ref>/

No body, no X-Signature. pg_ref is the transaction_id from Init. X-Merchant-Ref must equal the transaction's own merchant_ref — a mismatch returns 104, not the transaction, so you can't probe another merchant's data by guessing a pg_ref.

{"status":"success","response_code":"000",
 "data":{"pg_ref":"110709070745213648","merchant_ref":"ORDER-20260907-0142",
         "status":"Success","bank_ref":"UTR2607071345921","amount":"670.00"},
 "message":"Transaction successful"}

GET https://payout.staarpg.com/api/v3/payout/status/merchant/<merchant_ref>/

Same shape as above, keyed by your own merchant_ref — the fallback when Execute never returned a pg_ref (e.g. the response was lost before you read it).

GET https://payout.staarpg.com/api/v3/payout/balance/

Returns available and hold balance per active wallet currency.

{"status":"success","response_code":"000",
 "data":{"merchant_id":"AM6054","wallets":[
   {"currency":"INR","available_balance":"184230.50","hold_balance":"6700.00","wallet_type":"prepaid"}
 ]},"message":""}

8Webhooks

The definitive way to learn a transaction's final state. Fired once the bank leg resolves, and retried on delivery failure — don't rely on Status alone if you can receive these.

Delivery

We POST to your registered webhook_url. Your endpoint must reply with a literal HTTP 200 within 15 seconds — anything else (wrong status code, timeout, connection error) counts as a failed attempt and triggers a retry.

Request shape

Distinct from every API response — the encrypted value sits under the key encrypted, not data, and two plaintext fields ride alongside it unencrypted.

Content-Type:         application/json
X-Webhook-Timestamp:  1757231273
X-Pg-Ref:              110726090713045392

{"encrypted":"<base64 blob>","pg_ref":"110726090713045392","timestamp":"1757231273"}

✓ Worked example — round-trip verified

Decrypted payload — event: payout.status_update

{
  "event": "payout.status_update",
  "data": {
    "pg_ref": "110726090713045392",
    "merchant_ref": "ORDER-20260907-0142",
    "transaction_status": "Success",
    "amount": "670.00",
    "charges": "3.50",
    "gst": "0.63",
    "bank_ref": "UTR2607071345921",
    "bank_remark": "Transaction successful",
    "transfer_type": "IMPS",
    "currency": "INR",
    "transaction_mode": "API_V3",
    "created_at": "2026-09-07T07:45:00+00:00",
    "updated_at": "2026-09-07T07:47:53+00:00"
  }
}

transaction_status here is the raw bank-facing status string (Success / Pending / Failed / Refund) — not the numeric response_code used elsewhere. Map it yourself if your system keys off codes.

9Response envelope

HTTP status is always 200, deliberately — CDN and infra layers only ever see a healthy response. Read response_code inside the body for the real outcome.

{"data": "<wire-format>"}

{status, response_code,
 data, message, timestamp}

Once a success response is decrypted, it unwraps to the same field set as the error shape — status, response_code, data, message, timestamp — so downstream parsing code never branches on outcome, only on whether decryption was attempted.

Pending is not failed

Once your wallet is debited on Execute, we never return a failure for that call again — an interruption after debit always resolves to response_code 001 / Pending, success-shaped and encrypted like any other success, telling you where to poll for the final state.

{
  "status": "success",
  "response_code": "001",
  "data": { "pg_ref": "...", "merchant_ref": "...", "status": "Pending", "bank_ref": "", "amount": "670.00" },
  "message": "Transaction is being processed..."
}

10Field formats

Malformed values fail validation before anything else runs (steps 8/9/10 above) — worth matching exactly, especially amount and IFSC.

11Response codes

12Common integration mistakes

13Get help