Batch Payments

Overview

URL https://api.xero.com/api.xro/2.0/BatchPayments
Methods Supported GET, PUT
Description Create a batch payment
Retrieve batch payments

Batch payments allow you to bundle multiple bills or invoices into one payment transaction. This means a single payment in Xero can be reconciled with a single transaction on the bank statement making for a much simpler bank reconciliation experience.

Limitations of batch payments

  • You can only make batch payments in the organisation base currency
  • You can’t create a batch payment with a mixture of sales invoices and bills
  • You can’t include credit notes, prepayments or overpayments on batch payments

GET BatchPayments

Use this method to retrieve batch payments

Account ID of the account used to make the payment. This account needs to be either an account of type BANK or have enable payments to this accounts switched on (see GET Accounts)
Particulars, Code, Reference (NZ Only) Optional references for the batch payment transaction. It will also show with the batch payment transaction in the bank reconciliation Find & Match screen. Depending on your individual bank, the detail may also show on the bank statement you import into Xero. Max length =12.
Details (Non-NZ Only) These details are sent to the org’s bank as a reference for the batch payment transaction. They will also show with the batch payment transaction in the bank reconciliation Find & Match screen. Depending on your individual bank, the detail may also show on the bank statement imported into Xero. Maximum field length = 18
Narrative (UK Only) Only shows on the statement line in Xero. Max length =18
BatchPaymentID The Xero generated unique identifier for the bank transaction (read-only)
Date Date the payment is being made (YYYY-MM-DD) e.g. 2018-09-06
Payments The collection of one or more payments that make up the batch
Type PAYBATCH for bill payments or RECBATCH for sales invoice payments (read-only)
Status AUTHORISED or DELETED (read-only). New batch payments will have a status of AUTHORISED. It is not possible to delete batch payments via the API.
TotalAmount The total of the payments that make up the batch (read-only)
IsReconciled Booelan that tells you if the batch payment has been reconciled (read-only)
UpdatedDateUTC UTC timestamp of last update to the payment
Elements for Payments
Invoice The ID of the Invoice the payment was made against
PaymentID The Xero generated unique identifier for the payment (read-only)
BankAccountNumber The suppliers bank account number the payment is being made to
Particulars, Code & Reference TNZ Only) The information to appear on the supplier's bank account and bank statement.
Details The information to appear on the supplier's bank account.
Amount The amount being paid

Optional parameters for GET Batchpayments

Record filter You can specify an individual record by appending the BatchPaymentID to the endpoint, i.e.
GET https://.../BatchPayments/297c2dc5-cc47-4afd-8ec8-74990b8761e9
Modified After The ModifiedAfter filter is actually an HTTP header: ‘If-Modified-Since‘. note payments created or modified since this timestamp will be returned e.g. 2009-11-12T00:00:00
Where Filter by an any element ( see Filters )
order Order by any element returned ( see Order By )

Example response when retrieving an individual batch payment (NZ)

GET https://api.xero.com/api.xro/2.0/BatchPayments/54fb5c27-b2bc-4d54-a92f-a86b765d71c1

PUT BatchPayments

Use this method to create batch payments

Account ID of the account used to make the payment. This account needs to be either an account of type BANK or have enable payments to this accounts switched on (see GET Accounts)
Particulars, Code, Reference (NZ Only) Optional references for the batch payment transaction. It will also show with the batch payment transaction in the bank reconciliation Find & Match screen. Depending on your individual bank, the detail may also show on the bank statement you import into Xero. Max length =12.
Details (Non-NZ Only) These details are sent to the org’s bank as a reference for the batch payment transaction. They will also show with the batch payment transaction in the bank reconciliation Find & Match screen. Depending on your individual bank, the detail may also show on the bank statement imported into Xero. Maximum field length = 18
Narrative (UK Only) Only shows on the statement line in Xero. Max length =18
Date Date the payment is being made (YYYY-MM-DD) e.g. 2018-09-06
Payments The collection of one or more payments that make up the batch
Elements for Payments
Invoice The ID of the Invoice the payment was made against
BankAccountNumber The suppliers bank account number the payment is being made to
Particulars, Code & Reference TNZ Only) The information to appear on the supplier's bank account and bank statement.
Details The information to appear on the supplier's bank account.
Amount The amount being paid

Example request to create an ACCPAY batch payment (NZ)

PUT https://api.xero.com/api.xro/2.0/BatchPayments

Example request to create an ACCREC batch payment

PUT https://api.xero.com/api.xro/2.0/BatchPayments

Retrieving History

View a summary of the actions made by all users to the batch payment. See the History and Notes page for more details.

Example of retrieving a batch payment's history

GET https://api.xero.com/api.xro/2.0/BatchPayments/{Guid}/History

Add Notes to a Batch Payment

Add a note which will appear in the history against a batch payment. See the History and Notes page for more details.

Example of creating a note against a payment

PUT https://api.xero.com/api.xro/2.0/Payments/{Guid}/History