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. Both take a JSON body.

Transaction queries

POST /v1/transactions. 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` delayed, `1` success, `2` fail, `3` cancelled, `4` error.	all

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 (not "expired"). The value set is -1 delayed, 1 success, 2 fail, 3 cancelled, 4 error.

Payment confirmation screen

GET /v1/transactions/{token}/status-screen returns the payment-confirmation screenshot for a successful transaction, as image/png, scoped to your merchants. Branch on the HTTP status:

Status	Meaning
`200`	The screenshot, returned as `image/png`.
`400`	The transaction is not a successful payment, so no status screen applies (`validation_failed`).
`401`	The token is unknown, or the transaction is not in your scope. The two are indistinguishable by design, so this never confirms whether another tenant's token exists. Also returned when the bearer token itself is missing or invalid (`unauthorized`).
`404`	A successful, in-scope transaction that has no screenshot on file (`not_found`).

Every non-200 returns the standard error envelope, so a single failure handler covers them all.

curl -s -w "%{http_code}\n" \
  "https://dev.boapi.ppgw.net/v1/transactions/YOUR_TXN_TOKEN/status-screen" \
  -H "Authorization: Bearer YOUR_TOKEN" -o status.png

FNB Smart Blocked

List

POST /v1/fnbsb.

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

{
  "items": [
    {
      "id": 5521,
      "merchantid": 10544,
      "dateflagged": "2026-07-03T11:04:00Z",
      "merchantreference": "ORDER-12345",
      "frombankaccount": "******54821",
      "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/fnbsb/stats returns count and amount totals bucketed by state over a date range (default: last 30 days).

curl -s -X POST https://dev.boapi.ppgw.net/v1/fnbsb/stats \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "merchantid": 10544, "fromdate": "2026-06-01", "todate": "2026-06-30" }'

{
  "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.

Transactions & FNB Smart Blocked

On this page