Payments API - Getting started
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.
- A Hosted Web Gateway (recommend AWS)
- HTTPS Only
- Failure Resilient
- High Availability
- Familiarity with the postMessage() API
- A Vend account to test with
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.
I create a public-facing payment gateway at https://mygateway.com which can communicate with payment terminals directly.
In my Vend account I go to Setup -> Payment Types.
- Choose Add Payment Type.
- From the dropdown choose Credit Card and rename it to My Gateway -> Then Save.
- 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.
- On the Sell screen choose to buy an item -> And press Pay.
- Now click the payment button named My Gateway.
- 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
Therefore a sale processed on myvendstore.vendhq.com for $50 would look like this to your gateway:
You then use the
Window.postMessage() API, to handle that transaction.
More instructions on how can be found in the Payment API Reference.
- RECEIVE FROM VEND: A GET request with the payment amount and origin.
- SEND TO VEND: “DATA” step to get more sale info like
register_idso I know which unique register this came from (the retailer could have multiple registers).
- IDENTIFY TERMINAL: Use the
register_idfrom 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