Payments

The checkout flow

After you create a session, your customer completes payment on the hosted checkout page at the checkout_url. The page handles collecting the UPI payment, the transaction reference, and optional proof — you don't build these steps yourself.

What the customer does

On the checkout page, the customer pays the shown amount over UPI, then submits the 12-digit transaction reference (UTR) from their payment app. We match that reference against the incoming bank credit and confirm the payment.

Follow-up endpoints

These endpoints back the checkout page. They use the session token in the URL and do not require your API key. The hosted checkout page calls them for you; they are documented here so you understand the full lifecycle.

Submit UTR

POST /payments/session/{session_token}/submit-utr

Body: {"utr":"312482855519"}. On success, returns {"status":"UTR_SUBMITTED","message":"UTR received — verifying payment"}.

Situation

Status

Response

Missing UTR

400

{"error":"utr required"}

Invalid UTR format

422

{"error":{"code":"INVALID_UTR_FORMAT","message":"That doesn't look like a UTR — check the 12-digit reference number in your payment app"}}

Unknown session

404

{"error":"Session not found"}

Session already in a final state

409

{"error":"Session is already <STATUS>"}

Session expired

410

{"error":"Session expired"}

More than 10 submissions per minute for the same session

429

{"error":{"code":"UTR_SUBMISSION_RATE_LIMITED","message":"Too many UTR submissions. Please wait a minute and try again."}}

Upload payment proof

POST /payments/session/{session_token}/proof

Sent as multipart/form-data with a file field named proof. Accepts JPG, PNG, WebP, or HEIC up to 5 MB. On success, returns {"ok":true,"uploadedAt":"..."}. Limited to 5 uploads per 15 minutes per session, and 10 per minute per IP address.

Cancel a session

POST /payments/session/{session_token}/cancel

No body required. Only sessions that are CREATED or UTR_SUBMITTED can be cancelled; the session becomes FAILED and a FAILED webhook is sent.

Situation

Status

Response

Unknown session

404

{"error":"Session not found"}

Status cannot be cancelled

409

{"error":"Cannot cancel session with status <STATUS>"}

Was this helpful?
Was this helpful?