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
- Your company must be approved, and the website that will send customers back must be approved too (Dashboard, Websites).
- Create an API key in Dashboard, API keys. It looks like
ppay_live_xxxxxxxxxx_...and is shown once. - All amounts are whole paise (
25000is Rs 250.00). Currency is alwaysINR.
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:
GET https://ppay.pbstudios.in/api/v1/payments/{id}orGET https://ppay.pbstudios.in/api/v1/payments?order_ref=your-order-id-123- Only
"status": "paid"means paid.
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
GET https://ppay.pbstudios.in/api/v1/payments?status=paid&limit=20&starting_after=<payment id>GET https://ppay.pbstudios.in/api/v1/balance: your available, settling and held amounts.
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.