| URL | https://api.xero.com/api.xro/2.0/Payments |
| Methods Supported | GET, PUT, POST |
| Description | Retrieve either one or many payments for invoices and credit notes
Apply payments to approved AR and AP invoices Allow you to refund credit notes Delete (reverse) a payment Allows you to refund prepayments and overpayments Allows you to retrieve history Allows you to add notes |
To pay multiple AR or AP invoices in a single transaction use the BatchPayments endpoint.
Use this method to retrieve either one or many payments for invoices and credit notes
| Date | Date the payment is being made (YYYY-MM-DD) e.g. 2009-09-06 | |
| CurrencyRate | Exchange rate when payment is received. Only used for non base currency invoices and credit notes e.g. 0.7500 | |
| Amount | The amount of the payment. Must be less than or equal to the outstanding amount owing on the invoice e.g. 200.00 | |
| Reference | An optional description for the payment e.g. Direct Debit | |
| IsReconciled | An optional parameter for the payment. Conversion related apps can utilise the IsReconciled flag in scenarios when a matching bank statement line is not available. Learn more | |
| Status | The status of the payment. | |
| PaymentType | See Payment Types. | |
| UpdatedDateUTC | UTC timestamp of last update to the payment | |
| BatchPaymentID | Present if the payment was created as part of a batch. | |
| BatchPayment | Details of the Batch the payment was part of. See Batch Payments for more details. | |
| Account | The Account the payment was made from | |
| Invoice | The Invoice the payment was made against | |
| CreditNote | The Credit Note the payment was made against | |
| Prepayments | The Prepayment the payment was made against | |
| Overpayment | The Overpayment the payment was made against | |
| Record filter | You can specify an individual record by appending the PaymentID to the endpoint, i.e.
GET https://.../Payments/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 any element ( see Filters ). Only certain elements are optimised to ensure performance across organisations of all sizes. |
| Order | Order by any element returned ( see Order By ). Only certain elements are optimised to ensure performance across organisations of all sizes. |
| Page | Up to 100 payments will be returned per call when the page parameter is used e.g. page=1 |
In order to make our platform more stable, we've added a high volume threshold limit for the GET Payments Endpoint.
The most common filters have been optimised to ensure performance across organisations of all sizes. We recommend you restrict your filtering to the following optimised parameters.
| When using individually or combined with the AND operator: | |||
| PaymentType | equals | where=PaymentType="ACCRECPAYMENT" | |
| Status | equals | where=Status="AUTHORISED" | |
| Date | greater than | where=Date>DateTime(2020, 01, 01) | |
| Invoice.InvoiceId | equals | where=Invoice.InvoiceID=guid("96988e67-ecf9-466d-bfbf-0afa1725a649") | |
| Reference | equals | where=Reference="INV-0001" | |
| When using with the OR operator: | |||
| PaymentId | equals | where=PaymentID=guid("0a0ef7ee-7b91-46fa-8136-c4cc6287273a") OR PaymentID=guid("603b8347-d833-4e65-abf9-1f465652cb42") | |
| Invoice.InvoiceId | equals | where=Invoice.InvoiceId=guid("0b0ef7ee-7b91-46fa-8136-c4cc6287273a") OR Invoice.InvoiceId=guid("693b8347-d833-4e65-abf9-1f465652cb42") | |
?where=Type=="ACCRECPAYMENT" AND Status=="AUTHORISED"This would translate to the following URL once encoded.
https://api.xero.com/api.xro/2.0/Payments?where=Type%3D%3D%22ACCRECPAYMENT%22+AND+Status%3D%3D%22AUTHORISED%22%0D%0A
The following parameters are optimised for ordering:
The default order is UpdatedDateUTC ASC, PaymentId ASC. Secondary ordering is applied by default using the PaymentId. This ensures consistency across pages.
The example below is fetching a payment on an AR invoice in the base currency of the organisation
GET https://api.xero.com/api.xro/2.0/Payments/b26fd49a-cbae-470a-a8f8-bcbc119e0379
Use this method to apply payments to approved AR and AP invoices or refund AR or AP credit notes.
| Invoice or CreditNote or Prepayment or Overpayment | ||
| either | InvoiceID or CreditNoteID or PrepaymentID or OverpaymentID | ID of the invoice, credit note, prepayment or overpayment you are applying payment to e.g. 297c2dc5-cc47-4afd-8ec8-74990b8761e9 |
| InvoiceNumber or CreditNoteNumber | Number of invoice or credit note you are applying payment to e.g. INV-4003 | |
| Account | ||
| either | AccountID | ID of account you are using to make the payment e.g. 294b1dc5-cc47-2afc-7ec8-64990b8761b8. This account needs to be either an account of type BANK or have enable payments to this accounts switched on (see GET Accounts) . See the edit account screen of your Chart of Accounts in Xero if you wish to enable payments for an account other than a bank account |
| Code | Code of account you are using to make the payment e.g. 001 ( note: not all accounts have a code value) | |
| Date | Date the payment is being made (YYYY-MM-DD) e.g. 2009-09-06 | |
| CurrencyRate | Exchange rate when payment is received. Only used for non base currency invoices and credit notes e.g. 0.7500 | |
| Amount | The amount of the payment. Must be less than or equal to the outstanding amount owing on the invoice e.g. 200.00 | |
| Reference | An optional description for the payment e.g. Direct Debit | |
| IsReconciled | A boolean indicating whether the payment has been reconciled. | |
| Status | The status of the payment. | |
Below is an example of refunding a part amount of $100 of a credit note to a bank account in a different currency to the credit note.
Below is an example for applying an automatically reconciled payment to an invoice (useful for conversion purposes)
Use this method to delete (reverse) payments to invoices, credit notes, prepayments & overpayments. Note that payments created via batch payments and receipts are not supported. Payments cannot be modified, only created and deleted.
| PaymentID | The Xero identifier for an Payment e.g. 297c2dc5-cc47-4afd-8ec8-74990b8761e9 |
View a summary of the actions made by all users to the payment. See the History and Notes page for more details.
Example of retrieving a payment's history
GET https://api.xero.com/api.xro/2.0/Payments/{Guid}/History
Add a note which will appear in the history against a 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