This page is a ZenPay-styled copy of the Zenith Payments developer documentation. View the original docs

Batch Payments API

A batch payment is a collection of payment entries submitted together for processing. Each entry settles asynchronously against a registered customer.

Create a batch payment#

POST/v2/batchpayments

View this endpoint in the original docs

Creates a batch payment from the supplied request payload.

Authentication: Api-Key + BasicAuth

Request body

Collection of batch payment entries inside a container required to create a batch payment.

Content types: application/json, application/x-www-form-urlencoded · required

Schema: BatchPaymentRequest

Field	Type	Description
`batchPaymentEntries` required	array of object (BatchPaymentDataRecord)	Collection of BatchPayment entry.
`merchantUniqueBatchId`	string	Unique batch id provided by the merchant. Max length: `50`

Example: Batch created

One batch with one entry, accepted. `batchPaymentId` and the `Location` header both identify the new batch.

JSON

{
  "batchPaymentEntries": [
    {
      "customerReference": "cust-batch-7880558552220",
      "merchantUniquePaymentId": "bp-3ff90e78-23a8-40f2-92fd-1ce108aa189f",
      "paymentAccountProxy": "73898fe3d1044245adbcc1b9b597dc11",
      "paymentAmount": 1
    }
  ],
  "merchantUniqueBatchId": "batch-770de16d-8d02-4fbc-a146-0bc16b6ff564"
}

Responses

201 Batch payment created successfully.

application/json · object (BatchPaymentResponse)

Example: Batch created

One batch with one entry, accepted. `batchPaymentId` and the `Location` header both identify the new batch.

JSON

{
  "batchPaymentId": 7161,
  "merchantCode": "1337",
  "merchantName": "Menethil",
  "merchantUniqueBatchId": "batch-770de16d-8d02-4fbc-a146-0bc16b6ff564",
  "warningMessages": ""
}

300 Duplicate merchant unique id. The response will have 'Location' header which will have the orginal batch payment.

application/json · object (AmbiguousResult)

Example: Batch id resent after the first finished

The same `merchantUniqueBatchId` resent after the first batch completed. No new batch: the `Location` header returns the original `batchPaymentId`.

JSON

{
  "message": "The merchant unique id already exists."
}

400 Invalid batch payment details.

application/json · object

Example: Batch id resent immediately

The same `merchantUniqueBatchId` resent while the first was still processing, refused with the reason under `modelState`.

JSON

{
  "message": "The request is invalid.",
  "modelState": {
    "merchantUniqueBatchId": [
      "This request has already been processed. Please use a new MerchantUniqueBatchId for a new request."
    ]
  }
}

500 Something went wrong. Batch payment may or may not be created.

application/json · object (InternalServerErrorResult)

Example request (cURL, sandbox host)

cURL

curl -X POST 'https://api.sandbox.zenpay.com.au/v2/batchpayments' \
  -H 'Api-Key: <your API key>' \
  -u '<username>:<password>' \
  -H 'Content-Type: application/json' \
  -d '{
  "batchPaymentEntries": [
    {
      "customerReference": "cust-batch-7880558552220",
      "merchantUniquePaymentId": "bp-3ff90e78-23a8-40f2-92fd-1ce108aa189f",
      "paymentAccountProxy": "73898fe3d1044245adbcc1b9b597dc11",
      "paymentAmount": 1
    }
  ],
  "merchantUniqueBatchId": "batch-770de16d-8d02-4fbc-a146-0bc16b6ff564"
}'

Get a batch payment#

GET/v2/batchpayments/{batchPaymentId}

View this endpoint in the original docs

Returns the batch payment for the specified batch payment ID.

Authentication: Api-Key + BasicAuth

Parameters

Name	In	Type	Description
`batchPaymentId` required	path	integer <int32>	The unique batch payment identifier.

Responses

200 Batch Payment summary.

application/json · array of object (ApiBatchPaySummary)

Example: Completed batch

The batch once `status` reads `Completed`. Whether each payment succeeded is on the entries endpoint, not here.

JSON

{
  "merchantCode": "1337",
  "merchantName": "Menethil",
  "merchantUniqueBatchId": "batch-770de16d-8d02-4fbc-a146-0bc16b6ff564",
  "processingDate": "2026-09-24T00:41:05.01",
  "status": "Completed",
  "submittedDate": "2026-09-24T00:36:46.94",
  "totalAmount": 1,
  "totalEntries": 1
}

Example: Pending batch

The batch while `status` is still `Pending`. Poll until it reads `Completed`.

JSON

{
  "merchantCode": "1337",
  "merchantName": "Menethil",
  "merchantUniqueBatchId": "batch-770de16d-8d02-4fbc-a146-0bc16b6ff564",
  "processingDate": "2026-09-24T00:36:46.893",
  "status": "Pending",
  "submittedDate": "2026-09-24T00:36:46.94",
  "totalAmount": 1,
  "totalEntries": 1
}

404 Batch payment not found.

application/json · object

500 Unable to get the batch payment.

application/json · object

Example request (cURL, sandbox host)

cURL

curl -X GET 'https://api.sandbox.zenpay.com.au/v2/batchpayments/{batchPaymentId}' \
  -H 'Api-Key: <your API key>' \
  -u '<username>:<password>' \
  -H 'Accept: application/json'

List batch payment entries#

GET/v2/batchpayments/{batchPaymentId}/entries

View this endpoint in the original docs

Returns the entries for the specified batch payment.

Authentication: Api-Key + BasicAuth

Parameters

Name	In	Type	Description
`batchPaymentId` required	path	integer <int32>	The unique batch payment identifier.

Responses

200 List of batch payment entries.

application/json · array of object (ApiBatchPayEntry)

Example: Entry for an unknown customer

An entry whose `customerReference` matched no customer. The response is still 200, so entry failures show in `entryStatus`, not the HTTP status.

JSON

[
  {
    "cardTypeValue": 0,
    "customerReference": "no-such-customer-ref",
    "entryStatus": "Customer not found",
    "isPaymentRecalled": false,
    "isPaymentRefunded": false,
    "isPaymentRetryScheduled": false,
    "merchantCode": "1337",
    "merchantName": "Menethil",
    "merchantUniquePaymentId": "bp-949b6ff2-0f7e-46e5-a474-46dd7b172862",
    "paymentAmount": 1,
    "paymentStatus": ""
  }
]

Example: Pending entry

An entry not yet processed: no payment reference, fees or processed amount yet.

JSON

[
  {
    "cardTypeValue": 0,
    "customerName": "Test Card",
    "customerReference": "cust-batch-7880558552220",
    "entryStatus": "BatchPay Entry Pending",
    "isPaymentRecalled": false,
    "isPaymentRefunded": false,
    "isPaymentRetryScheduled": false,
    "merchantCode": "1337",
    "merchantName": "Menethil",
    "merchantUniquePaymentId": "bp-3ff90e78-23a8-40f2-92fd-1ce108aa189f",
    "paymentAmount": 1,
    "paymentStatus": ""
  }
]

Example: Processed entry

A processed entry, carrying its `paymentReference`, the fee split and the masked card number.

JSON

[
  {
    "baseAmount": 1,
    "cardCategory": "International Cards",
    "cardTypeString": "MasterCard",
    "cardTypeValue": 2,
    "customerFee": 0,
    "customerName": "Test Card",
    "customerReference": "cust-batch-7880558552220",
    "entryStatus": "BatchPay Entry Processed",
    "isPaymentRecalled": false,
    "isPaymentRefunded": false,
    "isPaymentRetryScheduled": false,
    "lastDigits": "555555XXXXXX4444",
    "merchantCode": "1337",
    "merchantFee": 0.05,
    "merchantName": "Menethil",
    "merchantUniquePaymentId": "bp-3ff90e78-23a8-40f2-92fd-1ce108aa189f",
    "merchantWithheldAmount": 1,
    "paymentAmount": 1,
    "paymentCard": "MasterCard",
    "paymentDate": "2026-09-24T00:40:36.03",
    "paymentMethod": "Credit / Debit Card",
    "paymentReference": "247446",
    "paymentResource": "https://api.sandbox.b2bpay.com.au/v2/payments/247446",
    "paymentStatus": "Successful",
    "processedAmount": 1,
    "processorReference": "d989e5ded6bc9fcec1f8",
    "settlementDate": "2026-09-25T00:00:00"
  }
]

404 Batch payment not found.

application/json · object

500 Unable to get the batch payment.

application/json · object

Example request (cURL, sandbox host)

cURL

curl -X GET 'https://api.sandbox.zenpay.com.au/v2/batchpayments/{batchPaymentId}/entries' \
  -H 'Api-Key: <your API key>' \
  -u '<username>:<password>' \
  -H 'Accept: application/json'

Need help with your integration?Talk to the Zenith Integrations Team.

Email integrations Talk to us