DPay API

DPay is payment infrastructure for Pakistan. You integrate once; your customers pay by bank transfer or wallet straight into your own NayaPay or Meezan account; DPay verifies the transfer by reading the bank's own alert email and then sends you a signed payment.succeeded webhook. DPay never holds funds.

Base URL https://api.dpay.com.pk/v1 · JSON in, JSON out · bearer API keys · amounts are integers in paisa (PKR × 100) unless you use amount_decimal.

The API answers on its own host, and so do the pages a customer opens. Every one of those (checkout_url, hosted_invoice_url, a payment link url) comes back to you as an absolute URL, so you never build one yourself.

Quickstart

1. Create an account and name your business.
2. Add a receiving account under Receiving accounts: NayaPay (recommended, verifies in seconds) or Meezan Bank (beta, alerts arrive in 3–5 minutes).
3. Connect the Gmail inbox your bank alerts arrive in (Integrations).
4. Create an API key (Developers). Test keys work on every plan; live keys need a paid plan.
5. From your server, POST /payment_sessions and redirect the customer to checkout_url.
6. Handle payment.succeeded on your webhook and fulfil the order. Never fulfil on a redirect alone.

Authentication

Send your secret key as a bearer token. Test keys start with dpay_test_sk_, live keys with dpay_live_sk_. Keys are stored hashed and shown once, at creation.

Objects created with a live key carry livemode: true, and so do the webhook events about them.

Amounts

amount is an integer in paisa: 500000 = PKR 5,000.00. Where a request accepts money you may send amount_decimal (string or number, up to two decimals) instead. Responses always include both amount and amount_decimal. Currency is always PKR.

Whole rupees only. Pakistani bank and wallet transfers do not carry paisa, so a session for PKR 18.38 can never be matched by an alert and would sit on "Verifying" until it expires. An amount that is not a multiple of 100 paisa is refused with invalid_request: *amount must be a whole number of rupees (a multiple of 100 paisa); Pakistani bank transfers do not carry paisa*. To have DPay round for you, send rounding: "up" or rounding: "nearest"; the session then carries the rounded amount. Rounding is never applied silently. Matching compares whole rupees, so an alert that differs only in paisa is the same transfer.

Idempotency

Send an Idempotency-Key header on POST /payment_sessions and retries return the original session with 200 instead of creating another. Use your order id.

Errors

Every error is JSON with one shape:

Rate limits

Each key has a bucket of 60 requests that refills at one per second. x-ratelimit-remaining is on every response.

Pagination

List endpoints take limit (default 20, max 100) and starting_after=<id>, the id of the last object you saw. Responses are { "object": "list", "data": [...], "has_more": true|false }, newest first.

Payment sessions

A payment session is one checkout: an amount, a customer, a hosted page, and a lifecycle that ends in succeeded, expired, cancelled, ambiguous or failed.

Create

POST /payment_sessions

Whole rupees. amount must be a multiple of 100 paisa. 1838 (PKR 18.38) is refused; 1900 is accepted; 1838 with "rounding": "up" becomes 1900. No Pakistani bank sends paisa, so a session that asks for it can never be paid.

Response 201:

Once verified, verification is filled: { "status": "matched", "confidence": 1, "matched_signals": ["merchant_account", "amount", …], "transaction_id": "txn_…", "verified_at": "…" }, and provider / customer_bank say which of your accounts received it and where the customer paid from.

Retrieve, list, cancel, verify

Payment states

Only status: "succeeded", read from the API or from a signature-verified webhook, means the money arrived. A redirect to success_url proves nothing; the customer can type that URL.

Every transition and the event it emits:

There is no `payment.cancelled` event. An abandoned checkout is reported as payment.expired. GET /webhook_events returns this catalogue.

Payment links

A reusable link: every open creates a fresh payment session with its own reference.

Object: { "id": "plink_…", "object": "payment_link", "title", "amount", "amount_decimal", "currency", "description", "payment_methods", "active", "url", "times_used", "created_at" }.

Invoices

Line items, a sequential number, an optional due date, and a hosted page at hosted_invoice_url where the customer presses Pay, which creates an ordinary payment session.

Object: { "id": "inv_…", "object": "invoice", "number": "INV-0001", "status": "open|paid|void", "customer", "line_items": [{ "description", "quantity", "unit_amount", "amount" }], "amount", "amount_decimal", "currency", "memo", "due_at", "hosted_invoice_url", "payment_session", "subscription", "created_at", "paid_at" }. unit_amount is in paisa. invoice.created and invoice.paid webhooks fire.

Subscriptions

Recurring billing without a card. Bank transfer cannot auto-debit, so each period DPay issues an invoice (due in 7 days) and advances a month; the customer pays that invoice like any other. Send them latest_invoice_url from the subscription.updated webhook.

Object: { "id": "sub_…", "object": "subscription", "status", "customer", "description", "amount", "amount_decimal", "currency", "interval": "month", "next_invoice_at", "latest_invoice", "invoices_issued", "created_at", "cancelled_at" }. Create returns latest_invoice_object too (null when start_at is in the future).

Customers

Built automatically from every succeeded payment that carried an email.

Object: { "id": "cus_…", "object": "customer", "email", "name", "payments_count", "total_volume", "total_volume_decimal", "currency", "last_bank", "first_paid_at", "last_paid_at", "created_at" }.

Events

Everything that happened, for audit and reconciliation.

Object: { "id": "evt_…", "object": "event", "type", "payment_session", "from", "to", "data", "created_at" }.

Webhook endpoints

Omit events (or send ["*"]) to receive everything. Store the returned secret as DPAY_WEBHOOK_SECRET; it is never shown again.

Registration is idempotent per URL. URLs are normalised (host case, default port, trailing slash) and one endpoint exists per URL per merchant. Posting a URL that already exists returns 409 with the existing endpoint (and no secret) — so a redeploy that re-registers does not leave a second endpoint whose deliveries are signed with a secret you threw away. To rotate that endpoint instead, send "replace": true: the events and description are updated, the secret is rotated, and the new secret is returned once. If you have lost a secret, POST /webhook_endpoints/:id/rotate_secret returns a new one; the old one stops verifying immediately.

An unknown event name is refused with the full list of valid ones. There is no payment.cancelled; an abandoned checkout arrives as payment.expired.

test.ping is sent by Send test event on the Developers page. It is signed like every other event and delivered whether or not the endpoint subscribes to it, so it proves the URL and the secret together.

Webhooks

DPay POSTs a JSON event to each enabled endpoint that subscribes to its type:

Headers: DPay-Signature (t=<unix>,v1=<hex hmac>), DPay-Event-Id, DPay-Event-Type, Idempotency-Key (same as the event id). Respond 2xx within 10 seconds. Deliveries come from 135.181.161.16 with user-agent DPay-Webhooks/1.0; allow that address if you filter, but trust the signature, not the IP. Failures retry after 30s, 2m, 10m, 1h and 6h (six attempts in all), so handle each `DPay-Event-Id` once and make your handler idempotent.

Event types: payment.created, payment.pending, payment.processing, payment.succeeded, payment.failed, payment.expired, payment.ambiguous, payment.refunded, payment.disputed, invoice.created, invoice.paid, subscription.created, subscription.updated, subscription.cancelled.

Verify signatures

Compute HMAC-SHA256(secret, "<t>.<raw body>"), compare in constant time to v1, and reject timestamps more than 300 seconds old in either direction. Your server's clock must be right for that check to pass — an NTP-synced clock is a requirement, not a nicety. Use the raw request bytes: re-serialising JSON breaks the signature, so read the body before any framework parses it ($request->getContent() / php://input, req.text() or express.raw, request.body in Django, request.raw_post in Rails).

What the customer sees

At checkout_url the customer chooses the bank or wallet they are paying from (any of 45 Pakistani institutions, not only the ones you accept) and optionally the last 4 digits of that account. DPay shows your receiving account with the exact amount and a reference to put in the transfer note. They pay in their own banking app, press I have sent the payment, and the page polls until the bank's alert is matched. NayaPay alerts land within seconds; Meezan's in 3–5 minutes. The amount is shown in whole rupees ("PKR 1,900", never "PKR 1,900.00").

`success_url`. After verification the page offers a *Continue* button to your success_url with two parameters appended: dpay_session_id and dpay_status. Treat the arrival as a hint to look the session up, not as proof: a customer can open that URL at any point, including while payment is still verifying or after it expired, so your page must read the order's real state and handle *not yet confirmed*.

Lifetime. A session lives for expires_in seconds (15 minutes by default, 24 hours at most). When that ends the session becomes expired and payment.expired fires — for a customer who never paid as much as for one who was slow. A late alert can still be honoured by merchant review, which fires payment.succeeded then.

Sandbox

Exercise verification without moving money: while signed in to the dashboard, POST a simulated bank alert for any payment the customer has marked as sent, and verification runs on it exactly as it would on the real email:

wrong_amount_paisa sends what a bank actually would: whole rupees, for a session that asked for paisa. It reproduces the failure that used to strand customers on "Verifying", and shows that matching now treats it as the same transfer.

The sandbox and production share one validation path — the same createSession, the same matcher, the same webhook code — so what the sandbox refuses, production refuses, and what it matches, production matches.

A local webhook receiver that verifies signatures lives at https://dpay.com.pk/api/webhooks/echo.

Plans and limits

Every checkout counts once against the merchant's monthly plan (API, dashboard, link, invoice). Free: 25 payments a month and test keys only. Paid plans raise the limit and unlock live keys; Growth and Scale also brand the hosted checkout with the merchant's logo, accent colour and trust line (Settings → Checkout branding). Over the limit, creation fails with 402 plan_limit_reached; nothing is charged automatically. Machine-readable reference: https://dpay.com.pk/llms-full.txt.

Health, status and your own configuration

A human-readable status page is at https://dpay.com.pk/status. Every 429 and 503 carries a Retry-After header, in seconds; honour it. Every merchant response carries x-response-time.