API Documentation

Quick start

1. Get approvedComplete PrimePay KYC. Your home corridor is activated on approval; additional countries can be enabled later.
2. Create credentialsIn the merchant dashboard, create a sandbox API credential and store the client_secret immediately (it is shown only once).
3. Check productsCall GET /merchants/products/?country_code=IN (or another corridor) to confirm methods and currencies before hard-coding payloads.
4. Send a pay-inExpand a country below, copy the sample payload (always include country_code), and send it with Basic auth plus an Idempotency-Key.

Base URL and envelope

All routes live under /api/v1/. Replace https://<host> with your PrimePay API host.

{
  "code": 200,
  "status": "OK",
  "data": {}
}

{
  "code": 400,
  "status": "BAD_REQUEST",
  "errors": {
    "detail": "payment_method is not enabled for your account."
  }
}

Authentication

Merchant API credentials (server-to-server)

Payment APIs authenticate with a client id and secret. Sandbox and live credentials are separate. Identity always comes from the credential — do not send a merchant id in the body.

• Sandbox client id: pp_sandbox_…
• Live client id: pp_live_…
• Secret: pp_secret_…

Send credentials as HTTP Basic auth, or with X-Client-Id and X-Client-Secret headers. Optional headers: Idempotency-Key (recommended on creates), X-Request-ID (for support tracing).

Create and rotate API credentials from the merchant dashboard (API credentials). The secret is shown only once — store it before leaving the page.

Corridors, environment, and country_code

One merchant account can collect in multiple countries. Each corridor is scoped to sandbox or live, and PrimePay picks the PSP for that route.

• Use ISO-3166-1 alpha-2 codes (IN, PK, BR, ID, …). The code must match an active merchant corridor for your credential environment.
• Your API credential selects sandbox or live. Corridors, rates, and PSP credentials do not cross environments.
• Some rails require whole currency units (no decimals) — see method notes under Pay-in by region.

Idempotency and request tracing

Use these headers on every create request.

• Idempotency-Key — required on pay-in and payout creates. Retries with the same key, environment, operation, and identical payload return the original payment. Changing country_code or amount with the same key returns 409 Conflict.
• X-Request-ID — optional client trace id echoed in logs and support lookups.
• merchant_reference — your order reference, echoed in lists and webhooks (not a substitute for idempotency).

Product availability

Call this before hard-coding a method or currency.

curl https://<host>/api/v1/merchants/products/ \
  -u "$CLIENT_ID:$CLIENT_SECRET"

{
  "code": 200,
  "status": "OK",
  "data": {
    "country_code": "IN",
    "region": "asia",
    "region_label": "Asia",
    "kyc_approved": true,
    "cards": {
      "available": false,
      "reason": "Card issuance is not active for IN.",
      "methods": [],
      "currencies": [],
      "options": []
    },
    "payin": {
      "available": true,
      "reason": "",
      "methods": [
        "UPI"
      ],
      "currencies": [
        "INR"
      ],
      "options": [
        {
          "method": "UPI",
          "currency": "INR",
          "country_code": "IN",
          "min_amount": "1.00",
          "max_amount": "500000.00"
        }
      ]
    }
  }
}

{
  "code": 401,
  "status": "UNAUTHORIZED",
  "errors": {
    "detail": "Invalid client credentials."
  }
}

Pay-in by region

Reference examples for South Asia, Southeast Asia, and Latin America. Expand a country for method fields, request samples, and responses. Your live catalog may enable a subset of these corridors.

Related endpoints

Optional calls after create — submit UTR, refresh status, or list payments.

curl -X POST https://<host>/api/v1/merchants/payments/<public_id>/utr/ \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"utr":"123456789012"}'

curl -X POST https://<host>/api/v1/merchants/payments/<public_id>/refresh/ \
  -u "$CLIENT_ID:$CLIENT_SECRET"

curl https://<host>/api/v1/merchants/wallets/ \
  -u "$CLIENT_ID:$CLIENT_SECRET"

curl "https://<host>/api/v1/merchants/payments/?direction=payin" \
  -u "$CLIENT_ID:$CLIENT_SECRET"

Webhooks

PrimePay notifies your server when a payment's status changes. Register HTTPS endpoints in the dashboard — that is the only notification integration you need.

1. 1

   Create pay-in

   Your server calls POST /merchants/payments/payin/. PrimePay returns payment_url and/or qr_code with status pending. You may receive a payment.pending webhook once instructions are ready.

2. 2

   Customer pays

   The customer completes payment using the link or QR from the response. For offline bank transfers, submit the UTR with POST /merchants/payments/<public_id>/utr/ when applicable.

3. 3

   PrimePay notifies your server

   When status changes (for example pending → succeeded), PrimePay POSTs a signed JSON event to each active webhook URL you configured. Typical sequence: payment.pending, then payment.succeeded or payment.failed when the outcome is final.

Register one or more HTTPS endpoints under Webhooks in the merchant dashboard. The signing secret (whsec_…) is shown only when you create or rotate an endpoint — store it on your server; it is separate from API credentials.

Events: payment.created, payment.pending, payment.unknown, payment.succeeded, payment.failed. Respond with 200 OK to acknowledge delivery.

{
  "id": "evt_a1b2c3d4e5f6789012345678abcdef01",
  "type": "payment.succeeded",
  "created_at": "2026-09-01T10:59:37.215043Z",
  "data": {
    "payment_id": "9ed5d192-c500-4a07-88f9-0cbd5ad83e98",
    "direction": "payin",
    "merchant_reference": "ORDER-IN-UPI-1",
    "client_transaction_id": "PI0A8296C90ED5560DC3F7",
    "status": "succeeded",
    "amount": "100.00",
    "currency": "INR",
    "country_code": "IN",
    "payment_method": "UPI"
  }
}

HTTP/1.1 200 OK
Content-Type: application/json

{"received": true}

Each POST is JSON, HMAC-SHA256 signed over {unix_timestamp}.{raw_body}. Verify using headers X-PrimePay-Timestamp, X-PrimePay-Signature (v1=<hex>), X-PrimePay-Event-Id, and X-PrimePay-Event. Reject timestamps older than 300 seconds. Failed deliveries retry with exponential backoff (same event id and payload).