Transactions & FNB Smart Blocked

Query EFT transactions across your merchants, and read FNB Smart Blocked listings and statistics. Both are read-only and scoped to your merchants.

Two read-only surfaces let you see activity across your merchants: transaction queries and FNB Smart Blocked listings and statistics. Both are scoped to the merchants your Master Account owns — you can restrict to a single merchant, but never widen beyond your own.

Transaction queries

POST /v1/transactions (JSON body) or GET /v1/transactions (query string) — same filters, same result. All filters are optional.

curl -s -X POST https://dev.boapi.ppgw.net/v1/transactions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "fromdate": "2026-07-01", "todate": "2026-07-15", "merchantid": 10544, "paymentstatus": 1 }'

{
  "items": [
    {
      "id": 887421,
      "merchantid": 10544,
      "paymentstatus": 1,
      "paymentdescription": "Successful",
      "amount": 100.00,
      "currency": "ZAR",
      "merchantreference": "ORDER-12345",
      "startdts": "2026-07-14T09:12:04Z",
      "transactiondts": "2026-07-14T09:12:41Z"
    }
  ],
  "count": 1,
  "fromdate": "2026-07-01T00:00:00Z",
  "todate": "2026-07-15T00:00:00Z",
  "notice": null
}

Filters and defaults

Filter	Meaning	Default
`fromdate`	Inclusive start date (`yyyy-MM-dd` or ISO).	7 days ago
`todate`	Inclusive end date.	today
`merchantid`	A single merchant in your scope.	all your merchants
`paymentstatus`	`1` success, `2` fail, `3` cancelled, `4` error.	all of 1–4

The date-range cap

The date window is capped at 31 days. If you ask for a wider range, the server narrows it and returns a notice describing what it did — the window is never silently truncated. The fromdate and todate in the response are the effective dates that were applied, so always read those back rather than assuming your requested range was honoured verbatim.

{ "count": 5000, "fromdate": "2026-06-15T00:00:00Z", "todate": "2026-07-16T00:00:00Z",
  "notice": "The requested range exceeded 31 days and was narrowed." }

paymentstatus here follows the EFT convention: 4 means error. The value set is 1 success, 2 fail, 3 cancelled, 4 error.

FNB Smart Blocked

FNB Smart Blocked data is backed by the payment gateway. When the gateway connection is not configured or is unreachable, these endpoints return 503 with code gateway_unavailable — a dependency outage, distinct from an application error. Retry with backoff.

List

POST /v1/fnb-smart-blocked or GET /v1/fnb-smart-blocked.

curl -s "https://dev.boapi.ppgw.net/v1/fnb-smart-blocked?merchantid=10544&fromdate=2026-07-01" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "items": [
    {
      "id": 5521,
      "merchantid": 10544,
      "dateflagged": "2026-07-03T11:04:00Z",
      "merchantreference": "ORDER-12345",
      "frombankaccount": "••••4821",
      "amount": 250.00,
      "state": 2,
      "statelabel": "blocked",
      "lasterror": null,
      "lastupdate": "2026-07-03T11:20:00Z"
    }
  ],
  "count": 1
}

When fromdate is set, the list returns the oldest 1000 from that date forward (ascending). When omitted, it returns the most recent 1000.
frombankaccount is masked — never a full account number.
state is 0 pending, 1 released, 2 blocked (with statelabel for readability).

Statistics

POST /v1/fnb-smart-blocked/stats or GET /v1/fnb-smart-blocked/stats returns count and amount totals bucketed by state over a date range (default: last 30 days).

{
  "pending":  { "count": 4,  "amount": 1200.00 },
  "released": { "count": 12, "amount": 8300.00 },
  "blocked":  { "count": 3,  "amount": 640.00 },
  "fromdate": "2026-06-16T00:00:00Z",
  "todate": "2026-07-16T00:00:00Z"
}

Scoping, always

Both surfaces obey the same tenant rule as everything else: supplying a merchantid that isn't yours does not leak another tenant's data. Omit merchantid to query across all your merchants; supply one to narrow to a single merchant you own.