Xero invoice automation guide

This guide outlines the workflow for enabling Xero integration with the Pinch API to collect payments automatically against Xero invoices, or to store customer payment details (see Pre-Approval).

Prerequisites

Before starting, make sure you have:

• A fully approved Pinch Merchant Portal account. (Register here if you don't already have one.)
• Your Merchant ID, Secret Key, and Publishable Key from the Integrations section of the Merchant Portal. See Authentication for how to use them.
• Xero integration enabled and syncing in the Pinch Merchant Portal.
• The account flags Generate Payments from API and Create Agreements from API Source enabled (contact Pinch support to turn these on).
• Webhooks configured and handled (as described below).

Existing Payer (Xero Contact) workflow

Use this flow when the Payer already exists in Xero as a Contact:

1. A Contact is created in Xero. With the Sync all Payers to Pinch API account flag enabled, Pinch pulls the contact in automatically. Retrieve the Pinch Payer ID (pyr_XXXXXXXX) from the API and save it for later use.
2. Present the Payer with a payment details form in your platform.
3. Tokenise their payment details client-side using the Pinch CaptureJS script.
4. Use the token to call POST /payers/{payerId}/sources and add a Payment Source to the Payer.
5. The Payment Source appears in the Merchant Portal as a Pre-Approval. From this point, any invoice that comes in from Xero will be automatically paid on its due date using this Source.

New Payer workflow

Use this flow when the Payer does not yet exist in either Pinch or Xero:

1. Present the Payer with a sign-up and payment details form in your platform.
2. Tokenise their payment details client-side using the Pinch CaptureJS script.
3. Call POST /payers to create the Payer, and save the returned Payer ID (pyr_XXXXXXXX).
4. Use the token to call POST /payers/{payerId}/sources and add a Payment Source.
5. Wait for the payer-updated webhook event — this fires once Pinch has synced the Payer to Xero and the Contact has a Xero Contact ID. At that point the Payment Source also appears in the Merchant Portal as a Pre-Approval.
6. Once the Pre-Approval is active, any invoice from Xero will be automatically paid on its due date.