Xero Invoice Payment Integration to Paylink 3

Paylink 3.1.25 and above supports an integration with Xero Invoices which allows for Xero invoices to be paid through the CityPay Paylink form.  


Payee/Card Holder Perspective

To be able to illustrate how the invoice payment works the following will guide you through a typical payment as processed by the invoice payer and card holder

  1. An invoice is received via email or a href link and viewed online

  2. The payee click on the green button to pay using CityPay. They are redirected to a payment page outlining their invoice payment (note the example is a test transaction)

  3. The transaction has been approved

  4. The invoice is shown as paid

Xero Administrator Perspective

CityPay's Xero invoice payment will push a payment instruction to Xero notifying them of the amount authorised. Xero's system will determine the payment result of an invoice such as PAID. 

An invoice will be shown to be paid via CityPay's payment integration in the header of the invoice.

We also add a note to the invoice to show the reference of the payment. 

When viewed in your account transactions, the payment reference is displayed linking to your reference with your CityPay merchant id and the transaction number


CityPay are integrated with Xero as a Xero partner and will require permission to access your Xero online account. This can be managed through a dedicated management page at https://secure.citypay.com/paylink3/xero-mgm where you will be required to enter your merchant id and service licence key to access your configuration.

Data Shared

CityPay only require data from Xero to be able to produce a payment against an invoice. We therefore share

Data Element Data Action Data Stored Description
Organisation Read
  • shortcode
  • organisation name
  • organisation guid
We require the organisation details to be able to obtain the shortcode and the organisation name to reference your account
PaymentServices Read/Update None We require access to the payment services data to inform you of the payment services configured and add our service as an option
BrandingThemes Read None We require access to the branding themes to list out the payment services associations with these themes
BrandingThemes/{themeId}/PaymentServices Read/Update None We require access to the branding themes payment services to read and update the associated services on your request
Accounts Read
  • payment account guid
We require the ability to read your chart of accounts where EnablePaymentsToAccount is true or the type of account is BANK. This is to allow us to configure the payment service to post transactions to the account when they are processed
Invoices Read
  • Invoice number such as INV-0012 which is used as an identifier
  • Billing address for AVS fraud protection
  • Card holder name
  • Card holder email address
We require the ability to read invoice data to obtain data related to the invoice for display in the online payment form. We require the invoice id, the amount, items and contact information related to the invoice. Information is only stored to be able to action the payment and contact the card holder as and where configured within your CityPay account.
Payments Add None We require the ability to push a payment notification to your configured posting account to mark the invoice as being paid


There is an additional cost for using the invoicing integration and is typically around 0.5% of the cost of your invoice. For exact pricing, please contact your CityPay account manager or support@citypay.com.

New Integration Setup

  1. Navigate to the management portal at https://secure.citypay.com/paylink3/xero-mgm and enter your merchant id and service licence key previously issued to you  https://secure.citypay.com/paylink3/xero-mgm
  2. Once logged in, you will be presented with a request to initialise your service. This can be completed by pressing on Connect to Xero
  3. You will be redirected to your Xero service to authorise the CityPay application. 
  4. Once you have authorised the connection, we will display the account configuration screen. 

  5. You should now notice an active payment service on your Xero account under https://go.xero.com/Settings/PaymentGateways/ 
  6. To use the payment service, it will need to be associated with a branding themes. You can configure branding themes either via the CityPay Xero management interface or via Xero's portal

    To enable via the CityPay Xero management interface, click on the Not Associated button to instigate an association. Note that the interface is unable to disassociate at this moment in time. Any changes will need to be performed via the Xero portal.

  7. You will also need to associate a payment account to post to. This will allow an invoice to be marked as paid within your Xero organisation.

    You are also able to add a new Xero account which will reflect in your Xero organisation, to perform this operation, simple click on the "Add New Account" button.

    CityPay recommend setting up an "Acquirer Bank Account" to pay your invoices into as this will allow you to move the funds once the payments have been settled into your bank accounts.

  8. As part of the the process, fees can also be automatically added to an expense account. This can help in collating automatic invoice fees to a given account. The fees will also be included as part of your CityPay monthly invoice.

Removing the CityPay Paylink Payment Service

To remove the service, you will need to browser to your Payment Services page at https://go.xero.com/Settings/PaymentGateways/ and list your active payment services. Client on edit and select "Remove" from the drop down that appears.

Your service with CityPay will be in a dislodged state, requiring re-setup on the CityPay service panel page.


I receive the message Shortcode has been previously used

This occurs when attempting to configure multiple merchant accounts with the same Xero organisation. We do support multiple configurations as long as the currency differs between each CityPay merchant account. This is due to a limitation from Xero of only providing a shortcode reference and a currency. We therefore are able to determine a unique merchant account based on these 2 values. If you are attempting to configure a new account. Please contact support to clear any previous account settings

I receive the message oauth_problem=token_rejected when configuring an account

This can occur if using your browser history or back button and the expected authentication tokens with Xero are out of sync. Please return to the start of your connection and retry.

When logging in I receive a message saying 403: PaylinkXeroService not licenced

You will need to refer to your account manager to enable the Xero service. The service is not enabled by default.

+44 (0)1534 884000