Reporting API

The basics

Base URL

https://payflow.promoticsstudio.com

Method

POST, on every path, including the ones that only read. A signed request carries its parameters in the body; a GET would write your date ranges and your customers’ order references into every access log between you and us.

Content type

application/json. Form encoding is accepted too, which is why include_payments takes true, "true", 1 or "yes" equally.

Credentials

The same merchant id and API secret as the payment API, from your API keys page. This API calls the id merchant_mid; merchant_id is accepted as well, so a client you already have does not need renaming.

Timezone

Pakistan Standard Time, +05:00, for every window and every timestamp. “Today” means today here. Timestamps come back as ISO 8601 with the offset on them, so you never have to assume it.

Currency

PKR, and every amount is a string with exactly two decimal places. Strings rather than JSON numbers on purpose: a language that parses 1999.99 into a float has already lost a paisa somewhere.

Signing a request

Every request carries merchant_mid, timestamp (UNIX seconds) and signature. The signature is a lowercase hex HMAC-SHA256 of the signing string below, keyed with your API secret — the same computation as the payment API, over a shorter pre-image.

Three formulas cover all twelve endpoints. Which one a path uses is printed in its own section, and in the summary table further down.

What is not signed

status, issuer, origin, page and limit are all outside the formula, deliberately. They only ever narrow a result set the signature already authorises in full, so covering them would buy nothing — and it would mean a fresh signature for every page, which makes walking a year of history absurd.

The range slot

For a shorthand, sign the shorthand: last_7_days, not the dates it resolves to. For a custom window, sign the two dates joined by a hyphen — 2026-07-01-2026-07-23 — and not the word custom. Both worked examples are below.

The clock

A timestamp more than 10 minutes from ours is refused with PGW_400_TIMESTAMP before anything else is checked. Run NTP. This is the single most common cause of a signature that looks correct and is rejected anyway.

Worked examples

All four use the secret pgw_sk_example0000000000000000000000000000000000000000, which is obviously not a real one, and the fixed past timestamp 1757000000 so the digests below never change. Reproduce any of them and your implementation matches ours.

signing string  PGW-M-000123|last_7_days|1757000000
signature       76bc4e54b86e7db7c711c2b2f229163b090a4e431fc11c0ab639af895c66c64e

signing string  PGW-M-000123|2026-07-01-2026-07-23|1757000000
signature       a2653151b66fdc82322be86e3778f3beda6a74f7e4e511e2be8264e8afc7e7a3

signing string  PGW-M-000123|PGW-20250904-9f3a2c1b|1757000000
signature       fd6c788fa17d0d8e5c5e0c133ca375d813b41e677ff0558d36f3ea58d18da23e

signing string  PGW-M-000123|1757000000
signature       f00fdb2ac48eb83a5d023bfab237554c7593e2053f9daa02a3f7720d223fe162

The envelope

Every successful response, on every path, has the same top-level keys. A lookup that returns one record still carries pagination; a report with no rows still carries a summary of zeros. Write one parser.

{
  "success": true,
  "request_id": "a3f19c02be7d4416",
  "server_time": "2025-09-04T20:33:20+05:00",
  "merchant_mid": "PGW-M-000123",
  "range": { "range": "last_7_days", "from": "2026-09-04", "to": "2026-09-10", "days": 7 },
  "pagination": { "page": 1, "limit": 50, "total_records": 128, "total_pages": 3 },
  "summary": { },
  "data": [ ]
}

request_id

Unique to the response, not to the request. Quote it in a support email and we can find the exact call in our logs.

summary

Aggregates the whole window, not the page you are on. A summary that described the 50 rows in front of you would be a subtotal pretending to be a total.

pagination

page is 1-based. limit defaults to 50 and is clamped to 200 — ask for more and you get 200 with a total_pages you can act on, rather than an error. A page past the end returns an empty data array.

data

Always an array, even for a lookup, and always present.

Errors use the same success flag and drop the rest — see Errors.

Date ranges

The two ranged reports take either a range shorthand or an explicit from and to pair of YYYY-MM-DD dates. Supply dates without a range and custom is assumed. Supply neither and you get last_7_days.

Both ends are inclusive. A window that runs up to the present ends at the current second rather than at tonight’s midnight, so a total never includes hours that have not happened yet. Rolling windows are anchored to midnight, not to the clock: last_7_days is the seven calendar days ending today, so running the same report twice five minutes apart gives you the same rows.

The widest window one call may cover is 366 days. Beyond that, PGW_400_RANGE — page through in shorter windows.

Rate limits

Per merchant, per minute, in fixed windows. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining; a 429 also carries Retry-After, in seconds, which is exactly how long until the current window ends.

Windows are fixed rather than sliding, so the counter resets on the minute. If you are throttled at :47, waiting the Retry-After the response gave you is enough — there is no benefit to backing off further.

Field reference

Issuers

issuer accepts either the code or the name, and is returned as the code with issuer_name beside it. The codes are permanent.

Statuses

The same vocabulary as the payment API, with the same numeric codes. Only completed payments are settled and paid out.

Origins

Where a payment came from. Both kinds settle identically and carry the same fee — the label exists so you can tell your own integration’s traffic from requests your staff raised by hand.

origin_note carries the description whoever raised a dashboard request typed for their own records, and is null for everything else.

Errors

A failed call answers with the HTTP status from the table below and this body. The success flag is the same one a successful response leads with, so you can branch on one field either way.

{
  "success": false,
  "status": "error",
  "code": "PGW_400_RANGE",
  "message": "The requested date range is invalid or exceeds the maximum window."
}

The ones this API sends most

PGW_400_RANGE

The window is backwards, unparseable, or wider than 366 days. A from after its to is the usual cause.

PGW_400_VALIDATION

A filter value outside its vocabulary, two lookup identifiers where one was expected, or none at all. The message names what was wrong and what is accepted.

PGW_401_AUTH

Almost always a signing string that differs from ours by one character. Check that you signed the shorthand rather than the dates it resolves to, then that you did not include the filters.

PGW_404_NOT_FOUND

No such record under your account. Every query on this API is scoped to you, so another merchant’s reference answers exactly as a nonexistent one does.

PGW_429_RATE_LIMIT

Over the per-minute budget for that group. Retry-After on the response is the exact number of seconds until the window resets.