| 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 |
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 | |
| 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 an any element (see Filters) |
| order | Order by any element returned (see Order By) |
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
<Payment>
<PaymentID>b26fd49a-cbae-470a-a8f8-bcbc119e0379</PaymentID>
<Date>2007-12-14T00:00:00</Date>
<Amount>281.25</Amount>
<CurrencyRate>1.000000</CurrencyRate>
<PaymentType>ACCRECPAYMENT</PaymentType>
<Status>AUTHORISED</Status>
<UpdatedDateUTC>2008-02-20T08:22:27.847</UpdatedDateUTC>
<IsReconciled>true</IsReconciled>
<Account>
<AccountID>297c2dc5-cc47-4afd-8ec8-74990b8761e9</AccountID>
</Account>
<Invoice>
<Contact>
<ContactID>3e1d3ba5-609a-4e10-bb1d-75b6d31ce922</ContactID>
<Name>Seymour Grimes</Name>
</Contact>
<Type>ACCREC</Type>
<InvoiceID>d3cb96c6-8f3a-45ec-a261-0a7b65d4b877</InvoiceID>
<InvoiceNumber>OIT00504</InvoiceNumber>
</Invoice>
</Payment>
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. | |
| The following elements are only returned on GET requests | ||
| PaymentType | See Payment Types. | |
| UpdatedDateUTC | UTC timestamp of last update to the payment | |
<Payments>
<Payment>
<Invoice>
<InvoiceID>96df0dff-43ec-4899-a7d9-e9d63ef12b19</InvoiceID>
</Invoice>
<Account>
<Code>001</Code>
</Account>
<Date>2009-09-08</Date>
<Amount>32.06</Amount>
</Payment>
</Payments>
<Payments>
<Payment>
<Invoice>
<InvoiceID>96df0dff-43ec-4899-a7d9-e9d63ef12b19</InvoiceID>
</Invoice>
<Account>
<AccountID>297c2dc5-cc47-4afd-8ec8-74990b8761e9</AccountID>
</Account>
<Date>2009-07-13</Date>
<Amount>3375.00</Amount>
</Payment>
<Payment>
<Invoice>
<InvoiceID>0a1d0d71-b001-4c71-a260-31e77c9d4a92</InvoiceID>
</Invoice>
<Account>
<AccountID>a65b0dac-b444-4b41-959b-c1580cd6268f</AccountID>
</Account>
<Date>2009-09-01</Date>
<Amount>393.75</Amount>
</Payment>
<Payment>
<Invoice>
<InvoiceID>93c9be81-1df4-4338-b5dc-e67a89cd2d7c</InvoiceID>
</Invoice>
<Account>
<AccountID>a65b0dac-b444-4b41-959b-c1580cd6268f</AccountID>
</Account>
<Date>2009-07-21</Date>
<Amount>398</Amount>
</Payment>
</Payments>
<Payments>
<Payment>
<CreditNote>
<CreditNoteNumber>CN-007</CreditNoteNumber>
</CreditNote>
<Account>
<Code>090</Code>
</Account>
<Date>2013-09-04</Date>
<Amount>50.00</Amount>
<Reference>Full refund as we couldn't replace item</Reference>
</Payment>
</Payments>
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.
<Payments>
<Payment>
<CreditNote>
<CreditNoteNumber>CN-007</CreditNoteNumber>
</CreditNote>
<Account>
<Code>AUD</Code>
</Account>
<Date>2013-09-04</Date>
<Amount>50.00</Amount>
<CurrencyRate>0.8</CurrencyRate>
</Payment>
</Payments>
<Payments>
<Payment>
<Prepayment>
<PrepaymentID>262c3049-cbf2-4b4b-9fca-60d55b076e35</PrepaymentID>
</Prepayment>
<Account>
<Code>090</Code>
</Account>
<Date>2015-03-25</Date>
<Amount>100.00</Amount>
<Reference>Full refund the customer cancelled their subscription</Reference>
</Payment>
</Payments>
<Payments>
<Payment>
<Overpayment>
<OverpaymentID>1ced4be7-ea6d-4f46-8279-4203e461de80</OverpaymentID>
</Overpayment>
<Account>
<Code>090</Code>
</Account>
<Date>2015-04-01</Date>
<Amount>2000.00</Amount>
<Reference>Refunded overpayment made by mistake</Reference>
</Payment>
</Payments>
Below is an example for applying an automatically reconciled payment to an invoice (useful for conversion purposes)
<Payments>
<Payment>
<Invoice>
<InvoiceNumber>OIT00619</InvoiceNumber>
</Invoice>
<Account>
<Code>001</Code>
</Account>
<Date>2009-09-08</Date>
<Amount>20.00</Amount>
<IsReconciled>true</IsReconciled>
</Payment>
</Payments>
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 |
<Payments>
<Payment>
<Status>DELETED</Status>
</Payment>
</Payments>