XeroConnect is a B2B solution that allows suppliers to deliver invoices, credit notes and confirm payment for supplier invoices in a cost effective way using secure communications with acknowledgement of delivery that has been designed to leverage existing building-blocks most medium-to-large organisations as part of their ERP and customer facing solutions.
XeroConnect uses Xero's RESTful API for all communication.
The core elements of XeroConnect are:
To setup a XeroConnect customer, a Xero user must grant the XeroConnect Supplier access through our OAuth flow from within the customer portal of the XeroConnect Supplier. Along with a user's OAuth tokens, XeroConnect will obtain organisation details including:
To accomplish this, a user will login to the Suppliers portal and click a 'Connect to Xero' button and be redirected to Xero's authorization screen. A user enters their Xero login details and selects which org to authorise. The connection is authorised and the user is redirected back to the payment service portal. The payment service is now authorized to access Xero's API and complete the setup process.
See details on implementing our standard authorization code OAuth flow here.
See details on implementing our PKCE OAuth flow here.
Once a customer has connected their Xero org, the XeroConnect Supplier then has access to get information from the Xero customers account, including:
Note that these are only examples, and the XeroConnect Supplier should work with their own customers to determine what are appropriate invoice details that may be required
XeroConnect does not support any of the above natively and it is up to the XeroConnect Supplier to provide those within their system.
Shipping charges are generally charged per invoice and account fees are generally charged per payment period.
If there are shipping charges or monthly fees (either access fees for the use of the portal or per supplier card (eg fuel card) cards), you may need to record these against a different account codes. Perform a GET on the Accounts using the WHERE clause to retrieve only accounts where Class== “EXPENSE”. Let the user pick an account and save the choice for later.
Similar to accounting for fees, allowing the Xero organisation to set the account code(s) for purchases will allow the invoices to be processed seamlessly. When selecting an account for purchases, it is recommended that the Class=="DIRECTCOSTS" or Class=="CURRLIAB"
Regardless of the level of detail that may have been set or set by default by the XeroConnect Supplier, the delivery of the Supplier Invoice is done by performing a POST to the Invoices endpoint. Where the customer as a direct debit or agreed commercial arrangement with the supplier, the Invoice can be set to either DRAFT, SUBMITTED or AUTHORISED - these are explained further here.
When generating the Invoice, the Invoice contact should be set to the Contact ID set by the Xero customer within the Supplier Portal.
If the XeroConnect Supplier has allowed for one or more account codes to be set (eg: based off product categories or supplier cards or shipping/postal expenses), these can be set within each line item of the Invoice sent down based on the invoice details, along with the DueDate of the Invoice which would identify when the Supplier expects payment or will process the direct debit.
Where the XeroConnect Supplier supports PDF generation of Invoices, these can also be associated with the Invoice by calling the Invoices/{InvoiceID}/Attachments endpoint to add the PDF attachment to the invoice.
Where there are fees for access or charges per month per employee or supplier card, these can be delivered either as part of the summary invoice or as an individual invoice sent to the Xero organisation. Regardless, the LineItem for the invoice would include the fees account code set above.
Where the XeroConnect Supplier supports PDF generation of Invoices for Fees, these can also be associated with the Invoice in the same manner as a standard invoice as above.
If the Supplier supports Credit Notes, those can also be delivered in a similar way to the delivery of invoices. Credit Notes are created by using the POST CreditNotes call and the XeroConnect Supplier should use the same Contact as the Invoices being sent and have a type of ACCPAYCREDIT. The XeroConnect Supplier can also allocate amounts to a specific InvoiceID which will make matching direct debit payments made to Invoices raised - this is particularly important where the Xero organisation has configured to send individual invoices, not using monthly summaries.
Where the XeroConnect Supplier supports PDF generation of Credit Notes, these can also be associated with the Credit Note in a similar manner to the Invoice attachments by calling the CreditNotes/{CreditNoteID}/Attachments endpoint to add the PDF attachment to the credit note.
If the XeroConnect Supplier is using direct debit, they can also send through the payments received once the direct debit has been successfully processed. This is achieved by performing a PUT payments call and can identify the original invoice id sent to Xero and the amount paid.
Where the XeroConnect Supplier is using direct debit and sending payments to Xero, it is recommended that this processing occur once the Supplier has received confirmation from their banking institution that the funds have been received, not when the Supplier attempts the direct debit as this may result in the Invoice within Xero being marked as paid which will not allow the invoice to be altered subsequently.
