Payment services integration


Overview

The online invoicing functionality within Xero presents a great opportunity for Xero customers to utilize payments services and streamline the payments process to more effectively manage their cash flow.

Background: video overview of sales & online invoicing in Xero.


Opportunity

NZ$200 billion of accounts receivable invoices were raised and processed in Xero in the 12 months to 31 March 2018. Upon signing our standard revenue share agreement, you’ll be granted access to our Payment Service API to build a #beautiful payment experience for Xero users and their customers.

Payment Services will undergo our standard App partner review process in order to be certified as an official Xero App partner and be promoted in the Xero App Marketplace.

The steps to become a certified Xero App partner are outlined in our partner page - ­ once you register for the partner program, we’ll connect you with the regional Financial Web team to discuss commercial terms.


Payment Service Setup

Connect to Xero

To setup a payment service, a user must grant the payment service access through our standard oAuth flow. Along with a user’s oauth tokens, the payment service will obtain organisation details and account preferences for recording payments and fees.

To accomplish this, a user will login to the payment service 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.

Create Payment Service

Perform a GET on the PaymentServices to check if your payment service already exists for this organisation.

If it doesn’t exist, perform a PUT on PaymentService with the required fields to add your payment service as an option for use with Branding Themes.

It’s important to note the PaymentServiceURL is the link for the PayNow button. The url should include the parameters invoiceId, currency, amount and shortCode.

Example:
https://www.mypaymentservice.com/?invoiceId=[INVOICEID]&currency=[CURRENCY]&amount=[AMOUNTDUE]&shortCode=[SHORTCODE]

Payment Service and Branding Themes

Branding themes determine the look of an invoice as well as the payment service offered to a customer. Each time an invoice is created, the selected branding theme will include the associated payment service if one exists.

Perform a GET on BrandingThemes. Let the user to select a branding theme(s) to use. Now, you can perform a POST to BrandingThemes using the BrandingThemeID identifier and PaymentServiceId in the body.

Account for Payment

You’ll need the chart of accounts to record a payment to an invoice. Perform a GET on Accounts using the WHERE clause to retrieve only accounts where EnablePayments=true OR Type==”BANK”. These are the only type of accounts that can be used for Payments. Let the user pick an account and save the choice for later.

Account for Fees

You’ll need to record any fees related to the payment service. 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.

Organisation Shortcode

Perform a GET on Organisation and save the shortCode for later. This allows you to lookup a user’s information in your database based on the shortCode passed by the PaymentServiceUrl.

Customer Payment flow

Click the PayNow button

End customer opens the Xero online invoice clicks the 'Pay Now button'

The request is sent to the payment service url with the relevant values.

Example
https://www.mypaymentservice.com/?invoiceId=efd8f620-c6be-44d2-b84c-f29423b1f496&currency=USD&amount=100&shortCode=!xy456

This page will be hosted by the payment service - example below.

Validate Invoice

The payment service can identify the Xero organisation by matching the shortcode from the url (with a shortcode retrieved from the Organisation endpoint during setup) to identify the Xero org that is being paid and retrieve stored oauth token.

With our oauth token we can perform a GET on Invoices and retrieve the invoice using the InvoiceId as the identifier to confirm the balance is still outstanding.

Record Payment

Once the payment is successfully processed, you’ll record a payment to the invoice in Xero. Perform a PUT on Payments and use the saved payment Account.

Record Fees

Don’t forget to record any fees related to processing this payment.

If the payment Account is a bank, you can perform a PUT on BankTransactions and create a Spend Money transaction using the expense Account.

If the payment Account is not a bank, you can perform a PUT on ManualJournals and create a credit and debit JournalLines to account for any fees.

Show Invoice is Paid

Let the customer know the payment was successfully recorded in Xero by redirecting them back to the online invoice. The online invoice now displays as paid.