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
Allows you to refund prepayments and overpayments

GET Payments

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

Optional parameters for GET Payments

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>

PUT Payments

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.

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>
      <InvoiceID>96df0dff-43ec-4899-a7d9-e9d63ef12b19</InvoiceID>
    </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>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>

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

Below is an example of refunding the full amount of $100.00 of prepayment 262c3049-cbf2-4b4b-9fca-60d55b076e35 to a bank account
<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>

Example - overpayment refunds

Below is an example of refunding the full amount of $200.00 of overpayment 1ced4be7-ea6d-4f46-8279-4203e461de80 to a bank account
<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>

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

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>