Sign Up with Xero

Learn how to enable the Sign Up with Xero flow with Codat to support your app's certification

Providing the Sign Up with Xero flow is a requirement for all App Store Partners seeking certification, as prescribed by Xero’s certification checkpoints. It is optional for Financial Services Partners, depending on whether you choose to be listed in the App Store.

Sign Up with Xero is a user journey that takes potential customers from the Xero App Store directly to your app. It reduces the number of steps users need to take to sign up to your app and enables Xero to track referrals that originate in the Xero App Store.

Flow implementation options

Xero’s documentation outlines two approaches to Sign Up with Xero:

• Option A

  This option uses a related concept called Sign In with Xero, which enables users to use Xero as an identity provider when logging into your app. This is similar to signing in with Google or Facebook.

  This approach typically requires significantly more developer resource and is not possible for all apps (for example, apps that do not have a completely self-serve onboarding process and need customers to speak to a sales representative first).

• Option B

  This approach is more popular with Codat clients. It is simpler and enables apps to reduce the time and developer resource required to pass the Xero certification.

If you would like to implement Option A of the Sign Up with Xero flow, please notify your Codat account team for assistance. For Option B, follow the guidance below and consult your Codat account team if you have any queries.

Implementing Option B of Sign Up with Xero with Codat

This option of the Sign Up with Xero flow is intended to bring potential customers from the Xero App Store to an inquiry form on your website. The flow allows you to pre-populate the form with OpenID data from Xero, like the customer's name and email address.

If you do not have an existing signup or inquiry form, you should create one, because you will require a URL to redirect customers to during the SUxW journey. In this guide, we refer to this URL as your Sign up success redirect URL.

User flow

Retrieve the Sign Up with Xero URL

The Sign Up with Xero URL is the URL that is shared with the end user for them to authorize access to Xero. This URL is generated by Codat, but requires customization to your Codat instance:

1. Retrieve the clientId and platformKey.

   These two values will form part of the Sign Up with Xero URL.

   Call our GET https://api.codat.io/profile/syncSettings endpoint and pick up the clientId returned in the response. For Xero, the platformKey value is gbol, as captured in our accounting software key list.

2. Generate the URL.

   Use the values retrieved previously to generate a URL with the following structure: https://link-api.codat.io/clients/{ClientID}/signUpWith/{PlatformKey}?link.scopes=openid%20profile%20email

   The link.scopes=openid%20profile%20email parameter ensures that only user identity details are requested during this authorization call.

   You will need to provide this URL to Xero in the App Review Form and enter it into your App Store listing after certification.

When this link is initiated by the customer, it triggers the creation of a company and a connection in Codat, and redirects them to Xero login for authorization. Once authorized, they will be redirected to your Sign up success redirect URL.

Set the Sign up success redirect URL

Navigate to Settings > Auth flow > Redirects to access the Redirects page in the Codat Portal. Under Sign up success redirect URL, enter the base URL of the form you will display to the customer, without any parameter replacements. Your changes will be auto-saved.

Pre-populate customer's account with Xero data

Once the customer authorizes the Xero connection, use the Xero OpenID data to pre-populate onboarding forms or fields. Here is an example redirect with OpenID parameters:

{SignUpSuccessRedirectURL}?companyId=f3069a22-ce9a-499b-b341-a7d6564c65z1&connectionId=4302ebaf-aba6-4763-ba61-47a7992634a3&statusCode=200&openId_email=j.doe%2B1%40codat.io&openId_given_name=John&openId_family_name=Doe

You can also use the Codat API and companyId to read additional information of interest, such as company info. Further guidance on using OpenID data is available here.

Manage the Codat company

When the Sign Up with Xero URL is triggered and a Codat company is created, it has a name that follows the Xero-YYYY-MM-DD-THHMMSS convention. This is because we do not have any identifying information for the user at that point.

If you have specific requirements for company naming, you can update the name via the API using our Update company endpoint. Use the companyId returned as part of the Xero OpenID data.

Manage user cancellation

You should build logic to handle the scenario of a user canceling mid-flow, and serve a relevant error page. This is similar to what we recommend when using our Link auth flow.

As part of the OpenID response parameters, you will receive the appropriate status code that you can manage accordingly. For a full list of our status codes, see Status codes and errors.