Batches

---

loadBatch

POST {server}/api/payments/v2/loadBatch

Loads a batch of payments without requiring suppliers to be preloaded. loadBatch creates a supplier from the data provided — requiring less information than addSuppliers — and returns a supplierCode. Once a supplier exists, either loadBatch or loadPayments may be used.

How unique references behave — read before integrating

When paying an existing supplier through loadBatch, only the unique reference is needed to link to that supplier. The consequences are significant:

• If the unique reference is not found, a NEW supplier is created.
• If the unique reference is found and the banking details differ from those stored, the stored bank account details are overwritten with the new ones.

Do not use a fresh unique reference for each payment. Link a unique reference to a specific supplier by storing the supplierCode returned and mapping it to that unique reference. This prevents duplicate suppliers accumulating in the database, and makes updateSuppliers usable later.

Supplier creation can be switched off

Merchant profiles default to creating suppliers on submission of a payment batch. Ask the Payaccsys team to switch supplier creation off if you do not want suppliers created at all.

Service type

Payments default to same-day, clearing between 20:00 and 22:00 on the day. Set immediatePayment or oneDayPayment for another service type — see service types.

Post fields

Name	Type	Required	Description
token	Text	Y	The signed JWT
batchDescription	Text	Y	A reference for the payments batch
payments	Array	Y	1–n of batch payment data
batchReference	Text	O	The BA number of a previously created batch

Payment fields

Name	Type	Required	Description
uniqueReference	Text	Y	Your unique customer reference identifier
supplierType	Text	Y	Identifies the customer — see listSupplierTypes
name	Text	Y	First name where the supplier type is Individual; otherwise the entity name
lastName	Text	CY	Surname. Required where supplier type is Individual
group	Text	O	The name of a group to assign the supplier to
emailAddress	Text	O	The supplier's email address for payment advice
bank	Text	CY	See listBankOptions. Required where payment type is EFT
accountType	Text	CY	See listAccountTypes. Required where payment type is EFT
accountNumber	Text	CY	Required where payment type is EFT
branchCode	Text	CY	Required where payment type is EFT
branchName	Text	O	The branch name
amount	Decimal	Y	The payment amount
paymentDate	Date	Y	The date the payment must action
payeeReference	Text	Y	A payment reference for the payee's statement. For RTC and same-day, limited to 10 digits. For one-day and bank-defined beneficiaries there is no limit
immediatePayment	Boolean	O	Pay immediately. Only applies to real-time clearance participating banks
oneDayPayment	Boolean	O	Pay at midnight on the payment date. Cannot be used with immediatePayment
custom	Text	O	Merchant-defined custom field

Result fields

Name	Type	Required	Description
uniqueReference	Text	Y	Your unique customer reference identifier
supplierCode	Text	Y	The six-character alphanumeric supplier code
status	Text	Y	Success or Failed
paymentReference	Text	N	The payment transaction reference. Returned where status is Success
amount	Decimal	N	The amount deducted
fee	Decimal	N	The fee deducted
message	Text	N	Failure reason
custom	Text	N	Returns the custom field if provided
product	Text	N	The service type actually applied — Same Day Clearance, PayShap, Realtime Clearance or One Day Clearance

The product field is how you learn whether a real-time instruction was converted to PayShap. Conversion is automatic and cannot be requested in the payload — see participating banks.

Example

{
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "batchDescription": "Payments for 2020-05-29",
  "payments": [
    {
      "uniqueReference": "tes056",
      "name": "JOE SOAP",
      "group": "Test",
      "emailAddress": "joesoap@example.com",
      "bank": "Standard Bank",
      "accountType": "Cheque",
      "accountNumber": "700000000",
      "branchCode": "051001",
      "amount": "99.95",
      "paymentDate": "2020-05-29",
      "payeeReference": "ABC Company",
      "custom": "PAY-68Bf1863d5114"
    }
  ]
}

{
  "uniqueReference": "tes057",
  "status": "Success",
  "paymentReference": "PT4236",
  "amount": -199.95,
  "fee": -6.65,
  "custom": "PAY-78Bf1863d5118",
  "product": "Payshap"
}

---

cancelBatches

POST {server}/api/payments/v2/cancelBatches

Cancels batches by batch reference.

Immediate payments cannot reliably be cancelled. Immediate payment transactions sweep every five minutes, so cancellation cannot be guaranteed.

Post fields

Name	Type	Required	Description
token	Text	Y	The signed JWT (listed as supplier Code in the source guide — see known issues)
batchReferences	Array	Y	Batch references for cancellation

Response

Name	Type	Required	Description
jti	Text	Y	The unique JWT ID
status	Text	Y	Number cancelled out of the number submitted
availableBalance	Decimal	Y	The wallet's available balance
totalPaymentsCancelled	Decimal	Y	Total amount cancelled
totalFeesCancelled	Decimal	Y	Total of fees cancelled
totalCancelled	Decimal	Y	Total of payments and fees cancelled
batches	Array	Y	1–n of batch cancellation results

Per batch: batchReference, status (Cancelled or Failed), supplierCode, amountCancelled, feeCancelled, and message where failed.