The Vend Developer Hub

Welcome to the Vend developer hub. You'll find comprehensive guides and documentation to help you start working with the Vend API as quickly as possible.

Getting Started

How your Payment Gateway works with Vend.

Overview

The aim of this guide is to provide a practical example of how to get your payment
integration ready for use with Vend.

To use the payment API, your application will need to be set up as a payment
type in the retailer's Vend account. When a user is finished adding products to
a sale, they will click 'Pay', and then on the button for your integration to
take payment.

A modal/lightbox style window will appear containing an iFrame. In this
iFrame we will load the URL you specify (this is referred to as the
payment type's "Gateway URL"). Once your page is loaded into the iframe, you will be able to
communicate with the parent window (in this case the Vend Sell Screen) using
Window.postMessage(), documented here.

Just want the raw docs?

Prerequisites

  • A Hosted Web Gateway (recommend AWS)
    • HTTPS Only
    • Failure Resilient
    • High Availability
  • Familiarity with the postMessage() API
  • A Vend account to test with

In-App Experience

Your payment integration will look just as if it were a built-in payment method,
but when invoked will launch your service via an iFrame of your gateway URL.

Example

  1. I create a public-facing payment gateway at https://mygateway.com which can communicate with
    payment terminals directly.

  2. In my Vend account I go to Setup -> Payment Types.

  1. Choose Add Payment Type.
  1. From the dropdown choose Credit Card and rename it to My Gateway -> Then Save.
  1. Now Edit "My Gateway" -> enter https://mygateway.com (this is your actual gateway URL) in the Gateway (optional) field -> Save. The payment type is now configured to launch my custom payment gateway.
  1. On the Sell screen choose to buy an item -> And press Pay.
  1. Now click the payment button named My Gateway.
  1. The gateway for that payment type is now requested and your gateway will show embedded in a modal.

How it Works

Three arguments are provided as query parameters to your gateway URL. These are the origin (Vend domain prefix, that looks like xxxx.vendhq.com), the register_id which is the identifier for hte current register, and the transaction amount.

Therefore a sale processed on myvendstore.vendhq.com for $50 would look like
this to your gateway:

GET https://mygateway.com?origin=myvendstore.vendhq.com&amount=50.00&register_id=0242ac12-0012-11e7-ec9f-809071f870b8

You then use the Window.postMessage() API, to handle that transaction.
More instructions on how can be found in the Payment API Reference.

Example Flow

  • RECEIVE FROM VEND: A GET request with the payment amount and origin.
  • SEND TO VEND: "DATA" step to get more sale info like register_id so I know which unique register this came from (the retailer could have multiple registers).
  • IDENTIFY TERMINAL: Use the register_id from the DATA step to match which terminal to send the payment to.
  • SEND TO TERMINAL: Payment sent, terminal checks with the processor, and my gateway gets a response of "ACCEPTED".
  • SEND TO VEND: "ACCEPT" step.

Vend then completes the sale and prints a receipt with any receipt_html_extra you provide embedded in the receipt (this might be EMV data or the customer
receipt info).


What's Next

Check out the Pairing Flow Guide for how to handle multiple terminals.

Reference
Pairing Flow