API reference

The basics

Base URL

https://payflow.promoticsstudio.com Every path on this page is relative to it.

Method

POST on every endpoint, including the one that only reads a payment’s status. Parameters travel in the body, because a query string would leave them in access logs, browser history and proxy caches.

Body

JSON with Content-Type: application/json, or ordinary application/x-www-form-urlencoded. Both are read the same way, so use whichever your HTTP client makes easy.

Currency

PKR, uppercase. Anything else is refused as a validation error rather than corrected, because normalising it would change the text your signature was computed over.

Authentication

Three extra fields on every request — merchant_id, timestamp and signature — sent in the body alongside everything else. There is no authorization header and no bearer token to refresh.

Signing a request

Join the values the endpoint asks for with a pipe character, in the order given, then take the HMAC-SHA256 of that string keyed with your API secret and send the hex digest as signature. Nothing is hashed twice, nothing is base64-encoded, and the field order in your JSON body does not matter — only the order inside the signing string does.

Two rules that account for most first-day failures

1. Sign the amount in exactly the form you send it — two decimal places, always. 1999.90, never 1999.9; 500.00, never 500. If the two differ by so much as a trailing zero the digests will not match, and the failure arrives as PGW_401_AUTH, which looks like a credential problem and is not.
2. Sign the currency exactly as you send it: uppercase PKR. We do not fold case for you, precisely so a casing slip is reported as the validation error it is instead of resurfacing as a signature mismatch you cannot see the cause of.

The timestamp

Unix seconds, UTC. A request is accepted only while its timestamp is within 10 minutes either side of our clock, so a captured request cannot be replayed tomorrow — and a server whose clock has drifted will start failing with PGW_400_TIMESTAMP. If you see that code, check NTP before you check your code.

The payment flow

Creating a payment and charging it are deliberately two calls. The first reserves the amount and your order reference and hands back an id; the second is where the customer’s wallet gets involved. That split is what lets you keep one integration whether the customer pays on our checkout page or on yours.

1. Create the payment. You get a txn_id and a checkout_url. Nothing has been charged and the customer has not been contacted.
2. Collect the payment method. Send the customer to checkout_url and we handle it — wallet choice, mobile number, confirmation screen, retries, and the outcome page. Or collect those details on your own page and call one of the three charge endpoints yourself.
3. The customer confirms on their handset. This is the part neither of us controls. A wallet charge answers 202 while it is pending, so treat that as “asked, not answered” and do not fulfil the order on it.
4. Take the outcome. We POST it to your IPN URL if you have set one, and you can ask for it at any time with the status endpoint. Both read the same ledger, so they cannot disagree; the webhook is just faster than polling.

Endpoints

Webhooks

Set an IPN URL in your dashboard and we will POST the outcome of every payment to it as JSON, signed with the same secret you sign requests with. It is the same information the status endpoint gives you, delivered instead of asked for — and it is the only way to hear about a payment the customer completes minutes after leaving your site. The URL must be https and publicly reachable; we do not follow redirects.

{
  "merchant_id": "PGW-M-000123",
  "event_id": "evt_2f9c41a7be03d5816c74e9a0b2",
  "txn_id": "PGW-20250904-9f3a2c1b",
  "order_ref": "ORDER-4417",
  "status": "completed",
  "status_code": 200,
  "amount": "1999.99",
  "currency": "PKR",
  "gateway": "jazzcash",
  "fee_amount": "200.00",
  "net_amount": "1799.99",
  "message": "The payment was completed and funds were received.",
  "timestamp": 1757000000,
  "signature": "..."
}

merchant_id|txn_id|status|amount|currency|order_ref|timestamp

Statuses

Every payment is in exactly one of these. The words and the numbers are ours, and they are the same in an API response, a webhook, your dashboard and your statement.

In flight means keep listening. Final means stop — the one move out of a final status is completed becoming refunded, which arrives as its own webhook. Only completed payments are settled and paid out to you.

Errors

Any request that does not succeed answers with the HTTP status from the table below and this body. There is no other error shape, and this list is closed — if you switch on code, you have covered everything we can send you.

{
  "status": "error",
  "code": "PGW_400_VALIDATION",
  "message": "Required fields missing or invalid."
}

The three that get misread

PGW_401_AUTH

Almost always a signing string that differs from ours by one character, not a bad secret. Check the amount’s trailing zero first, then the field order, then whether you signed the values you actually sent.

PGW_400_TIMESTAMP

Your clock, not your code — the request arrived more than 10 minutes away from ours. It can also mean a request sat in a retry queue too long before being sent.

PGW_409_STATE

The payment exists but is not chargeable: it has already been charged, or it is past its session. Create a new payment rather than retrying this one.