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.

Reference

Overview

Vend's Payments API utilises the HTML5 postMessage() API to
allow interactions with the Vend Sell Screen at the point of sale.

Integrators can manipulate the current sale and control its flow, by using options like approve, decline and print.

NOTE: Complete custom gateway sample project available here

Messaging

Messages are expected to be sent and received as JSON-encoded strings.

Sending

Sending messages are done by calling postMessage() on the parent window.

var message = JSON.stringify({
    "step": "DATA"
});

window.parent.postMessage(message, "https://<domain_prefix>.vendhq.com");

Note that you will need to provide the store address for the origin argument.
An origin GET parameter is added to your gateway URL, so you should be able to use window.location.search to find this value.

Response

The response payload when requesting the "DATA" step, as above, includes sales totals and the register_id so that the integrator can differentiate between multiple Vend registers. You can also use this ID to associate registers with payment terminals by serial number, for how to do this see the Pairing Flow Guide.

Example response payload:

{
    "success": true,
    "step": "DATA",
    "register_sale": {
        "id": "5194354d-9080-8dda-11e6-9660dfac7dce",
        "client_id": "web_register",
        "client_sale_id": "5194354d-9080-8dda-11e6-9660dfac7dce",
        "totals": {
            "total_tax": "2.34783",
            "total_price": "15.65217",
            "total_paid": "10.00",
            "total_to_pay": "18.00"
        },
        "line_items": [
            {
                "product_id": "0800278f-358c-11e6-fcf3-9005a15efdc0",
                "quantity": "1",
                "unit_price": "17.39130",
                "unit_tax": "2.60870",
                "tax_id": "00000000-0002-0002-0002-000000000003"
            }
        ],
        "customer_id": "0800278f-358c-11e6-fcf3-9005a1e4b2b9",
        "discount": {
            "product_id": "0800278f-358c-11e6-fcf3-9005a28c9fbf",
            "price": "1.73913",
            "tax": "0.26087",
            "tax_id": "00000000-0002-0002-0002-000000000003"
        }
    },
    "payment": {
        "register_id": "0800278f-358c-11e6-fcf3-9005a15d99d9",
        "amount": "8.00"
    }
}

Types

Messages are JSON objects with one required field.

Required

Key Type Required Description
step string required The step in the transaction process to enact.
success boolean optional DEPRECATED: Whether the step is considered successful.

Possible steps include:

Step Description Action
DATA Request additional information from Vend about the current transaction. Sale JSON Sent.
SETUP The enable_close bool can be sent to toggle the modal close button.
PRINT You may also add content to the receipt with the receipt_html_extra field. Launches print dialogue.
ACCEPT_SIGNATURE It will print a signature slip receipt. You may add content to the receipt with the external_transaction_id, card_last_four, payment_date, terminal_serial_number, signature_url and signature_base64 fields. If printing is enabled an approved transaction receipt will also print. Launches print dialogue and complete sale.
ACCEPT If printing is enabled an approved transaction receipt will also print. Complete sale.
DECLINE If printing is enabled a declined transaction receipt will also print. Return to pay screen.
EXIT Does not close the window but closes all other dialogues and unbinds postMessage handling. Clean exit.

Optional

Key Type Required Description
receipt_html_extra string optional Any text (HTML) you would like added to the receipt.
print boolean optional Whether to print a receipt for this step. Ignored if the step is already set to PRINT.
copy_text string optional The merchant or customer copy label on receipts (defaults to "Customer Copy")
setup object optional Settings for the Payment dialogue.

Setup Options

Key Type Required Description
enable_close boolean optional Show or hide the close button and bar.

Accept and Accept Signature Options

Key Type Required Description
external_transaction_id string (36) optional The transaction identifier from the integrator's system.
reference_id string (36) optional A unique identifier that can be used to control repeat actions, such as preventing double charges (idempotency).
merchant_id string (36) optional The merchant identifier from the integrator system.
terminal_serial_number string (36) optional The serial number of the payment terminal.
terminal_model string (36) optional The model of the payment terminal.
entry_method string optional Enum: SWIPED, KEYED, CONTACTLESS, CHIP, FALLBACK
card_brand string optional Enum: OTHER, VISA, MASTERCARD, AMERICAN_EXPRESS, DISCOVER, DISCOVER_DINERS, JCB, CHINA_UNIONPAY, EBT, ENROUTE, INTERAC, VOYAGER, WEX
card_type string optional Enum: CREDIT, DEBIT
card_last_four string optional The last 4 digits of the card number.
emv_aid string (16) optional EMV application identifier
emv_application_label string (16) optional EMV application label
emv_cryptogram_type string optional Enum: AAC, ARQC and TC
emv_cryptogram string optional Cryptogram returned by the ICC
emv_pin_verified boolean optional To signify if a PIN was used as the verification method for the payment.
emv_tags [object] optional Additional EMV tags which are required on receipt. Each element is a key/value JSON object. e.g. [{ "key" : "4F", "value" : "A0000000000000" }, { "key" : "95", "value" : "0000000000" }]
signature_url string(200) optional The digital signature image as a public URL.
signature_base64 string optional The signature image (PNG format) as a Base64 string. If signature_url has been provided, signature_base64 will be ignored.

Example:

window.parent.postMessage(
'{
    "step": "SETUP",
    "setup": {
        "enable_close": false
    }
}'
, origin);

Receiving

Receiving messages is done by binding the message event on the child window
(your iFrame's window):

window.addEventListener("message", function(event) {
   var data = JSON.parse(event.data);

   // ... handle the messages

}, false);

Examples

For an example of how a gateway works on the Sell Screen, you can create a Credit Card payment type with the gateway URL set as /pay/example. You can then see example steps and data from the sell screen.

This will provide you with a page to test each of the messages. You can use
the source of this as a good starting point.

See also:


What's Next

Pairing Flow