Payments API - Getting started

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.

Find the API Reference docs here

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).