PPay Wallets

PPay API

Accept payments on your approved websites. Everything below is server to server: never put your API key in a web page or app.

Before you start

Authentication

Send the key as a bearer token:

Authorization: Bearer ppay_live_xxxxxxxxxx_yourSecret

Create a payment

POST https://ppay.pbstudios.in/api/v1/payments with an Idempotency-Key header (8 to 128 characters, new for each payment you create; reusing it with the same body returns the same payment).

{
  "amount_minor": 25000,
  "currency": "INR",
  "title": "100 coins",
  "description": "optional",
  "order_ref": "your-order-id-123",
  "customer": { "email": "buyer@example.com", "phone": "+919876543210", "name": "Buyer" },
  "success_url": "https://yourshop.com/thanks",
  "cancel_url": "https://yourshop.com/cart",
  "metadata": { "anything": "up to 2 KB" }
}

success_url and cancel_url must be on one of your approved websites, or the call is refused. The answer contains checkout_url: send the customer there. They see your name, the price, the convenience fee and the total before paying.

The amount you ask for is what you receive, minus your fee. If a convenience fee applies, the customer pays it on top.

What happens after payment

The customer returns to your success_url with ppay_payment_id, status and order_ref added. Do not trust those parameters. Confirm with the API or the webhook:

Webhooks

Set a webhook address (on an approved website) in Dashboard, API keys. We send payment.succeeded and payment.refunded:

{ "id": "evt_...", "type": "payment.succeeded", "created_at": "...", "data": { ...payment... } }

Each request has a PPay-Signature: t=<unix>,v1=<hex> header. Compute HMAC-SHA256 of <t>.<raw body> with your signing secret, compare to v1 in constant time, and reject if t is older than 5 minutes. Answer with any 2xx. Failed deliveries are retried for about a day. Handle duplicates: use the event id.

Other calls

Errors

Errors are JSON: { "error": "code", "message": "..." }. 401 bad key, 403 not allowed (company or website not approved), 409 duplicate or already used, 422 invalid input, 429 slow down.