Payments
| URL | https://api.xero.com/api.xro/2.0/Payments |
| Methods Supported | GET, PUT |
| Description | Retrieve either one or many payments for invoices and credit notes Apply payments to approved AR and AP invoices |
Elements for Payments
| <Invoice> | ||
| either | <InvoiceID> | ID of invoice you are applying payment to e.g. 297c2dc5-cc47-4afd-8ec8-74990b8761e9 |
| <InvoiceNumber> | Number of invoice 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 | |
Current limitations
Overpayments and prepayments are not currently supported via the API. To add your support for this feature and to be kept up to date on feature development, please vote in our request forum.
PUT Payments
Use this method to apply payments to approved AR and AP invoices.
Below is an example of applying a $32.06 payment to invoice OIT00545 from Account Code 001 on 8 Sept 2009.
<Payments>
<Payment>
<Invoice>
<InvoiceNumber>OIT00545</InvoiceNumber>
</Invoice>
<Account>
<Code>001</Code>
</Account>
<Date>2009-09-08T00:00:00</Date>
<Amount>32.06</Amount>
</Payment>
</Payments>
Below is an example of applying multiple payments to various Invoices (identified by InvoiceID) from various Accounts (identified by AccountID) across various dates.
<Payments>
<Payment>
<Invoice>
<InvoiceID>4ff40be5-89ba-4b94-a8d0-33f156965718</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>
Use this method to retrieve either one or many payments for invoices and credit notes
Optional parameters for GET Payments
| Record filter | You can specify an individual record by appending the value to the endpoint, i.e. GET https://…/Payments/{identifier} |
| PaymentID | The Xero identifier for an Payment e.g. 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
<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>
<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>