Payments
Payments to suppliers already stored. To pay without preloading suppliers, use
loadBatch.
loadPayments
POST {server}/api/payments/v2/loadPayments
Loads payments for existing suppliers set up with the EFT payment type.
Payments default to same-day, clearing between 20:00 and 22:00 on the day. To
use another service type, set immediatePayment or oneDayPayment.
Post fields
| Name | Type | Required | Description |
|---|---|---|---|
token | Text | Y | The signed JWT |
payments | Array | Y | 1–n of payment data (typed Text and marked optional in the source guide — see known issues) |
Payment fields
| Name | Type | Required | Description |
|---|---|---|---|
supplierCode | Text | Y | The six-character alphanumeric supplier code of the supplier to pay |
amount | Decimal | Y | The payment amount |
paymentDate | Text | Y | The date the payment must action |
reference | 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 |
sendPaymentAdvice | Boolean | O | Send a payment advice to the stored email address |
immediatePayment | Boolean | O | Pay immediately. Only applies to participating banks |
oneDayPayment | Boolean | O | Pay at midnight on the payment date. Cannot be used with immediatePayment |
Response
| Name | Type | Required | Description |
|---|---|---|---|
jti | Text | Y | The unique JWT ID |
status | Text | Y | Number of payments successful out of the number submitted |
availableBalance | Decimal | Y | The wallet's available balance |
totalPayments | Decimal | Y | Total of payments |
totalFees | Decimal | Y | Total of fees |
totalDeductions | Decimal | Y | Total of payments and fees |
payments | Array | Y | 1–n of payment results |
Per payment: supplierCode, status, paymentReference, amount, fee, and
message where failed.
Example
{
"jti": "{UNIQUE VALUE}",
"status": "1 of 2 Payments Scheduled",
"availableBalance": 257.19,
"totalPayments": -99.95,
"totalFees": -6.65,
"totalDeductions": -106.6,
"payments": [
{
"supplierCode": "JOE001",
"status": "Success",
"paymentReference": "PT4235",
"amount": -99.95,
"fee": -6.65
},
{
"supplierCode": "RON002",
"status": "Failed",
"message": "Supplier code does not exist"
}
]
}
Amounts and fees are returned as negative values, being deductions from the wallet.
cancelPayments
POST {server}/api/payments/v2/cancelPayments
Cancels payments by payment reference.
Immediate payments cannot reliably be cancelled. Immediate payment transactions sweep every five minutes, so cancellation of an immediate payment 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) |
paymentReferences | Array | Y | 1–n of payment references |
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 of payments cancelled |
totalFeesCancelled | Decimal | Y | Total of fees cancelled |
totalCancelled | Decimal | Y | Total of payments and fees cancelled |
payments | Array | Y | 1–n of cancellation results |
Per payment:
| Name | Type | Required | Description |
|---|---|---|---|
paymentReference | Text | Y | The payment or batch reference |
status | Text | Y | Cancelled or Failed |
supplierCode | Text | O | The six-character alphanumeric supplier code |
amountCancelled | Decimal | O | The amount cancelled |
feeCancelled | Decimal | O | The fee refunded |
message | Text | O | Failure reason |
The response example returns the refunded values as paymentRefund and
feeRefund rather than amountCancelled and feeCancelled.
paymentStatus
POST {server}/api/payments/v2/paymentStatus
Checks the status of loaded payments, by payment reference, by date or date range, or by batch.
Post fields
| Name | Type | Required | Description |
|---|---|---|---|
token | Text | Y | The signed JWT |
paymentReferences | Array | Y | 1–n of payment references |
paymentDate | Date | O | The date of scheduled payments. When paymentDate is used, paymentReferences is ignored |
toPaymentDate | Date | O | When used, the search becomes a range between paymentDate and toPaymentDate |
batchReference | Text | O | The BA number of a previously created batch |
Response
| Name | Type | Required | Description |
|---|---|---|---|
jti | Text | Y | The unique JWT ID |
status | Text | Y | Payment Status Results |
payments | Array | Y | 1–n of payment references |
Per payment:
| Name | Type | Required | Description |
|---|---|---|---|
paymentReference | Text | Y | The payment transaction reference |
supplierCode | Text | Y | The six-character alphanumeric supplier code |
status | Text | Y | Submitted · Completed · Failed · Cancelled |
message | Text | Y | A message specific to the transaction status |
paymentDate | Date | Y | The date for the payment action |
dateSubmitted | Date | Y | The date and time the payment was submitted |
dateCompleted | Date | Y | The date the transaction was finalised |
paymentAdvice | Date | Y | The date the payment advice was sent |
Example
{
"jti": "{UNIQUE VALUE}",
"status": "Payment Status Results",
"payments": [
{
"paymentReference": "PT4235",
"status": "Submitted",
"supplierCode": "JOE001",
"message": "Scheduled via API",
"paymentDate": "2020-05-29",
"dateSubmitted": "2020-05-22 12:49:24",
"dateCompleted": null,
"paymentAdvice": null
}
]
}