Payments


Overview

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

Elements for Payments

<Invoice> or <CreditNote>
either <InvoiceID> or <CreditNoteID> ID of invoice or credit note 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> An optional parameter for the payment. A boolean indicating whether you would like the payment to be created as reconciled when using PUT, or whether a payment has been reconciled when using GET
The following elements are only returned on GET requests
<Status> The status of the payment. This will always be AUTHORISED
<PaymentType> See Payment Types.
<UpdatedDateUTC> UTC timestamp of last update to the payment

PUT Payments

Use this method to apply payments to approved AR and AP invoices or refund AR or AP credit notes.

Example – single payment

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-08</Date>
    <Amount>32.06</Amount>
  </Payment>
</Payments>

Example – multiple 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>

Example – credit note refunds

Below is an example of refunding the full amount of $50.00 of credit note CN-007 to a bank account

<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>

Example – Creating a reconciled payment

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>

POST Payments

Use this method to delete (reverse) payments to approved AR and AP invoices.
Note that payments created via batch payments and receipts are not supported.
Payments cannot be modified, only created and deleted.

Required parameters for POST Payments

PaymentID The Xero identifier for an Payment e.g. 297c2dc5-cc47-4afd-8ec8-74990b8761e9

Example – delete a payment

Below is an example of deleting a payment. In order to delete a payment, you must POST to the resource ID for the payment.
e.g POST /Payments/b05466c8-dc54-4ff8-8f17-9d7008a2e44b

<Payments>
  <Payment>
    <Status>DELETED</Status>
  </Payment>
</Payments>

GET 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>