Payments API - Pairing flow

Overview

If servicing multi-outlet (or multi-lane) merchants, then your payment integration needs to have some concept of association between Vend Registers and Payment Terminals, so that your web service knows which terminal in the store - or in the country - a transaction is intended for.

We call the method the user follows to create this association the Pairing Flow. And will aim to describe the best practice for pairing here.

If you think you are getting ahead of yourself, see the Getting Started Guide.

Concepts

Registers in Vend

A register in Vend refers to a place in an outlet (or store), where goods or services are sold from. This means that a register is its own device, iPad or computer, and needs its own ability to take payments. For this reason, we recommend associating each individual register in Vend with a Payment terminal (by serial number).

Unique Pairings

Each register in Vend has a Universally Unique Identifier (UUID), and each payment terminal has a unique Serial Number (S/N), which can be used to create a unique association that your service can then store and use to direct transactions to the correct terminals.

To access the UUID of a register, you will need OAuth access to the Vend store. You are then able to For help with OAuth, read our documentation on How to OAuth with Vend. For help with requesting register info, see our REST API Reference for the /registers endpoint.

Step by Step

  1. Merchant starts pairing flow.
  2. Your service requests OAuth access to the Merchant’s Vend account.
  3. Merchant allows OAuth access.
  4. Present a field asking for Terminal Serial Number or asking for Terminal Pairing Code (Recommended: you can display the pairing code on the device being paired).
  5. The pairing code entered should match what the device is showing.
  6. Present a dropdown list of Register Name choices which you retrieve from the REST API.
  7. Store the association between the chosen register and the terminal that was identified.
  8. You are now ready to receive payments from that register.

Where to Pair

You may notice from official payment integrations, that there is a “Configure your X Account with Vend” button in the Edit Payment page, which launches a modal and takes the user through the pairing flow.

This is reserved for preferred payment integrations, meaning that your pairing flow would need to exist outside of Vend, or as a first step BEFORE payments can be taken on the sell page.

If you include the pairing option in the transact screens, then it’s possible to instruct users to do their register pairing from within the modal that opens on the Pay screen.

However, if you are at this stage, and what is more, reading through the documentation, we probably want to chat about the possibility of including your flow in-app. Email payments@vendhq.com and let us know what you’re working on. Colour. color.

Routing Payments

To recap, by this point you have:

  • A web service that is able to talk to your payment terminals
  • A flow for getting approved OAuth to a Vend store
  • A database in which to store RegisterUUID<->TerminalSN pairings
  • Some method of allowing the user to choose which Register to associate a terminal SN to

As we know from DATA Step in the Payments API, we have access to the register_id which has sent a payment request to our gateway. Abridged Payload from the DATA step:

{
    "success": true,
    "step": "DATA",
    "register_sale": {...},
    "payment": {
        "register_id": "0800278f-358c-11e6-fcf3-9005a15d99d9",
        "amount": "8.00"
    }
}

We can, therefore, look up that UUID in our database and find the associated terminal SN to route the payment to.

If you receive multiple requests, you should have multiple different UUIDs to respond to.