Get Batch Status API

Use this endpoint to retrieve the status of a submitted batch and per-row outcomes.

URL path - /billing/sites/{siteId}/batches/{batchReference}

Method - GET

Overview

Partners poll this endpoint until state is settled. All batches reach a terminal state within 24 hours of submission.

The response includes a per-row breakdown with the final state of each row. Successful rows carry a settledAt timestamp; failed rows carry a failureReason.

A settled batch indicates that every row has reached a terminal state — it does not by itself imply success. Inspect rowSummary.failed and the per-row failureReason values to distinguish a fully successful batch from one that settled with failures.

Polling

Poll no more frequently than once every 30 seconds for the same batchReference. Apply exponential back-off on 429 Too Many Requests responses, honouring the Retry-After header. Sustained polling beyond the 24-hour SLA is unnecessary — escalate via support if a batch has not settled within the SLA.

Request Headers

Header Name	Header Value	Notes
Authorization	Bearer access_token	Access token must include scope billing:batches:read
Pyng-Api-Version	urn:pyng:api:billing:version:v1	Required. See API Versions.

Path Parameters

Parameter Key	Parameter Data Type	Notes
siteId	string	Unique identifier of the Site that owns the batch. The Site must belong to the calling Organisation.
batchReference	string	Partner-supplied identifier provided when submitting the batch

Response

Status Code - 200 OK

Parameter Key	Parameter Data Type	Required	Notes
data	object	Y	object of BatchStatusResponse type
traceId	string	Y	Unique identifier of the request

BatchStatusResponse

Parameter Key	Parameter Data Type	Required	Notes
batchReference	string	Y	Partner-supplied batch reference
state	string	Y	One of BatchState
submittedAt	integer	Y	Unix timestamp in milliseconds, when the batch was first accepted
settledAt	integer	N	Unix timestamp in milliseconds. Present only when state is settled.
rowCount	integer	Y	Number of rows in the batch
rowSummary	object	Y	object of RowSummary type
rows	array	Y	Per-row outcomes. See RowOutcome.

RowSummary

Parameter Key	Parameter Data Type	Required	Notes
pending	integer	Y	Rows that have not yet reached a terminal state
succeeded	integer	Y	Rows that completed successfully
failed	integer	Y	Rows that failed terminally

RowOutcome

Parameter Key	Parameter Data Type	Required	Notes
rowReference	string	Y	Partner-supplied row reference, echoed from the original submission
customerReference	string	Y	Customer the row debited
amount	integer	Y	Debit amount, echoed from the original submission
description	string	N	Echoed from the original submission. Present only if a description was supplied at submission.
state	string	Y	One of RowState
settledAt	integer	N	Unix timestamp in milliseconds. Present only when state is succeeded.
paymentReference	string	N	Pyng-issued opaque identifier for the settled debit, used for reconciliation and support. Present only when state is succeeded. Treat as opaque; the format is intentionally not documented and may change.
failedAt	integer	N	Unix timestamp in milliseconds. Present only when state is failed.
failureReason	string	N	One of FailureReason. Present only when state is failed.

RowState

Value	Notes
pending	Row has not yet reached a terminal state
succeeded	Debit completed and settled successfully
failed	Debit terminally failed

FailureReason

Value	Notes
customerNotActive	The targeted customerReference is not in linked state
insufficientFunds	The customer's payment agreement reported insufficient funds
limitExceeded	Row amount exceeds a per-customer or per-batch limit
processingFailure	Internal payment pipeline reported a terminal failure

Examples

Request

GET /billing/sites/{siteId}/batches/acme-20260504-001 HTTP/1.1
Host: sample.pyng.com.au
Authorization: Bearer access_token
Pyng-Api-Version: urn:pyng:api:billing:version:v1

Response — In Progress

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "data": {
    "batchReference": "acme-20260504-001",
    "state": "inProgress",
    "submittedAt": 1777939200000,
    "rowCount": 2,
    "rowSummary": { "pending": 1, "succeeded": 1, "failed": 0 },
    "rows": [
      {
        "rowReference": "INV-1234",
        "customerReference": "ACME-001",
        "amount": 12500,
        "description": "Invoice #1234",
        "state": "succeeded",
        "settledAt": 1777941000000,
        "paymentReference": "9f3c2e8a-7b1d-4f6c-9e02-1a7d5f4e3b8c"
      },
      {
        "rowReference": "INV-1235",
        "customerReference": "ACME-002",
        "amount": 5000,
        "state": "pending"
      }
    ]
  },
  "traceId": "9ae2e340-b983-4274-b400-c974a9ab40ab"
}

Response — settled

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "data": {
    "batchReference": "acme-20260504-001",
    "state": "settled",
    "submittedAt": 1777939200000,
    "settledAt": 1777941075000,
    "rowCount": 2,
    "rowSummary": { "pending": 0, "succeeded": 1, "failed": 1 },
    "rows": [
      {
        "rowReference": "INV-1234",
        "customerReference": "ACME-001",
        "amount": 12500,
        "description": "Invoice #1234",
        "state": "succeeded",
        "settledAt": 1777941000000,
        "paymentReference": "9f3c2e8a-7b1d-4f6c-9e02-1a7d5f4e3b8c"
      },
      {
        "rowReference": "INV-1235",
        "customerReference": "ACME-002",
        "amount": 5000,
        "state": "failed",
        "failedAt": 1777941075000,
        "failureReason": "insufficientFunds"
      }
    ]
  },
  "traceId": "9ae2e340-b983-4274-b400-c974a9ab40ab"
}

Error Response — Not Found

HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8

{
  "errors": [
    {
      "code": "urn:pyng:platform:billing:error:batch:not-found",
      "displayMessage": "No batch found for the provided batchReference.",
      "target": "batchReference"
    }
  ],
  "traceId": "9ae2e340-b983-4274-b400-c974a9ab40ab"
}