API documentation

Demo reference — endpoints return sample payloads until providers are connected.

Authentication

Every request sends X-API-Key and a X-Signature HMAC-SHA256 of the raw body computed with your API secret. Secrets are never returned by any endpoint.

Idempotency

Send Idempotency-Key on every create call. Repeating a key returns the original transaction instead of creating a duplicate.

Status machine

PENDING → PROCESSING → SUCCESS | FAILED. Backwards or skipped transitions are rejected.

POST/api/public/v1/payinCreate a pay-in order and receive a hosted payment URL.

Request body

{
  "merchant_order_id": "ORD-20260819-1001",
  "amount": 4500.00,
  "currency": "USD",
  "customer": { "email": "aria.k@example.com" },
  "callback_url": "https://shop.example/webhooks/payin"
}

Response 200

{
  "transaction_id": "TXN_900101",
  "status": "PENDING",
  "amount": 4500,
  "fee": 112.5,
  "net": 4387.5,
  "payment_url": "https://pay.gateway.example/p/TXN_900101"
}

POST/api/public/v1/payoutRequest a payout to a beneficiary account.

Request body

{
  "merchant_order_id": "PO-20260819-7781",
  "amount": 1200.00,
  "beneficiary": { "account": "•••4421", "ifsc": "EXMP0001" }
}

Response 200

{
  "transaction_id": "TXN_900102",
  "status": "PROCESSING",
  "fee": 14.4,
  "net": 1185.6
}

GET/api/public/v1/transactions/:idFetch the current state of any pay-in or pay-out.

Request

No body — authenticated GET request.

Response 200

{
  "transaction_id": "TXN_900101",
  "type": "PAYIN",
  "status": "SUCCESS",
  "updated_at": "2026-08-19T04:11:20Z"
}

GET/api/public/v1/balanceCurrent available and pending merchant balance.

Request

No body — authenticated GET request.

Response 200

{
  "merchant_id": "MER_1001",
  "available": 482340.55,
  "pending": 18220.00,
  "currency": "USD"
}

Webhooks

We POST every terminal status change to your callback URL, signed with X-Signature. Respond 2xx within 10s or we retry with exponential backoff for 24 hours.

Webhook payload

{
  "event": "payin.success",
  "transaction_id": "TXN_900101",
  "merchant_order_id": "ORD-20260819-1001",
  "status": "SUCCESS",
  "amount": 4500,
  "signature_version": "v1"
}

Telegram bot commands

/balance — current available balance
/today — today's pay-in and pay-out
/orders pending — pending order count
/status TXN_900101 — single transaction status
/recent — last 10 transactions

Only whitelisted group IDs and users linked to your merchant account receive replies.