Payments API

Accept UPI, cards and net banking on your website. PayPe handles the gateway integration, status reconciliation and refunds; you make three API calls.

What you need before starting

• A PayPe merchant account — you receive a MER… merchant ID
• Your website domain, registered with us (sent to the gateway on every charge)
• A server that can make HTTPS requests and receive them

Two ways to integrate

Hosted checkout is a single link. No server code, no keys — send the customer to a PayPe page and we return them to yours. Start here.

Server APIs give you control over the amount, order ID and redirect target, and let you query status and issue refunds from your own backend.

Payment lifecycle

Every payment holds exactly one state. Two of them are final; one is not.

Quickstart

Take a test payment in about two minutes.

1. Send the customer to checkout

Replace the merchant ID with your own. This link works today, with no keys required.

https://api.paype.co.in/?merchant=MER1783999043172

2. Customer pays

PayPe shows the payment page, the customer chooses UPI, card or net banking, and we return them to your result page with the order ID appended.

3. Confirm the result from your server

curl https://api.paype.co.in/api/order-status/PAYPE1783999272545

{
  "state": "COMPLETED",
  "amount": 1000,
  "orderId": "OMO2607140912466357046693"
}

Read state at the root of the response. Nothing else decides whether the customer paid.

Amounts & identifiers

Amounts are in paise

Every amount in every request and response is an integer in paise. Sending 100 charges one rupee, not one hundred. Rounding errors here become refund disputes later, so convert once, in one place in your code.

Order IDs

You may supply your own merchantOrderId, or let PayPe generate one. Either way it must be unique for every attempt, under 63 characters, and contain only letters, numbers, hyphens and underscores.

Keep the bank reference — UTR for UPI, ARN or BRN for cards and net banking. It is what a bank asks for when a customer disputes a charge.

API keys Spec

Server-to-server calls will be authenticated with a key pair issued per merchant from your dashboard: a key ID you may expose, and a secret you must not.

X-PayPe-Key-Id: pk_live_8f3ef32ad3fc
X-PayPe-Signature: HMAC-SHA256(body, secret)
Content-Type: application/json

Keeping the secret secret

• Server side only. Never in browser JavaScript, mobile app binaries, or a repository.
• Store it in your hosting platform's environment settings, not in a file you commit.
• Rotate it from the dashboard if it is ever exposed. Old keys stop working immediately.

Hosted checkout Live

The fastest integration, and the one with the least to get wrong. Link or redirect the customer to your PayPe checkout URL.

<a href="https://api.paype.co.in/?merchant=MER1783999043172">
  Pay with PayPe
</a>

If your account is suspended, checkout refuses the payment before the customer reaches the gateway. An unknown merchant ID is rejected the same way.

Create payment Live

curl -X POST https://api.paype.co.in/api/create-payment \
  -H 'Content-Type: application/json' \
  -d '{"amount": 149.50, "merchantId": "MER1783999043172"}'

{
  "merchantOrderId": "PAYPE1783999272545",
  "redirectUrl": "https://mercury.phonepe.com/transact/…"
}

Order status Live

{
  "state": "COMPLETED",
  "amount": 14950,
  "orderId": "OMO2607140912466357046693",
  "paymentDetails": [
    {
      "paymentMode": "UPI_QR",
      "state": "COMPLETED",
      "rail": { "utr": "455226570184" }
    }
  ]
}

Refund Live

curl -X POST https://api.paype.co.in/api/refund \
  -H 'Content-Type: application/json' \
  -d '{"merchantOrderId": "PAYPE1783999272545", "amount": 50}'

{
  "merchantRefundId": "REFUND1783997069495",
  "amount": 5000,
  "state": "PENDING"
}

Refund status Live

{
  "state": "COMPLETED",
  "amount": 5000,
  "originalMerchantOrderId": "PAYPE1783999272545",
  "splitInstruments": [
    { "rail": { "utr": "455226570184" } }
  ]
}

Webhooks Spec

Rather than polling, register an HTTPS endpoint and PayPe will notify you when a payment or refund reaches a terminal state.

{
  "event": "payment.completed",
  "payload": {
    "merchantOrderId": "PAYPE1783999272545",
    "state": "COMPLETED",
    "amount": 14950
  }
}

Verify every webhook before trusting it

Anyone can send a POST to your endpoint. Compute the expected signature from your webhook secret and compare — reject with 401 if it does not match.

// req.rawBody is the unparsed request body
const expected = crypto
  .createHmac("sha256", process.env.PAYPE_WEBHOOK_SECRET)
  .update(req.rawBody)
  .digest("hex");

if (req.headers["x-paype-signature"] !== expected) {
  return res.status(401).json({ error: "unauthorized" });
}

// Verified. Use payload.state, and reply 200 quickly.
res.status(200).json({ received: true });

Rules for your handler

• Reply 200 fast. Do slow work afterwards. Timeouts trigger retries.
• Expect duplicates. The same event may arrive twice. Check whether you have already processed that order before acting on it.
• Read the root state, and identify the event from event.
• Webhooks are not a guarantee. Networks fail. Keep Order status as your fallback.

Reconciliation Live

PayPe chases every PENDING order on your behalf until it resolves, so an abandoned checkout still ends up with a correct final state in your dashboard.

You do not need to build this yourself. It runs inside PayPe.

Errors

Errors return a JSON body with an error field describing what happened and, where useful, the values involved.

Test in sandbox

Sandbox behaves like production but moves no real money. Use it to exercise every path before you go live — especially the ones you hope never happen.

Cases to cover

Going live

1. Confirm your domain is registered against your merchant account.
2. Swap sandbox keys for live keys in your server environment.
3. Point your webhook URL at your production endpoint and verify signatures there.
4. Run one real payment of ₹1 and refund it, end to end.

Roadmap

Documented here so you can plan. These are not available yet — do not build against them.