System Integrated QR Code

Merchant Presented mode

The merchant displays the QR Code and the customer uses their mobile
device to scan the code.

Static QR codes are static pre-printed codes, normally on a sticker, that you attach to a point-of-sale location, vending machines, taxis etc. Static codes are a quick and cost effective solution to get started.

Dynamic QR codes is codes where amount and other data is embedded within the code. It requires a monitor or printer to display the dynamic code for the customer. Locations where you would want a dynamic QR code is restaurant (pay at table) where the code could be printed en the pro forma invoice. In that could you would include amount and table number, which will be returned via web hook.

To generate a dynamic QR code you add the parameter dynamic to to the QR code data and add the fields you need.

📘

Example

A restaurant that prints a receipt on table 7 and it is waiter 2 that shall receive the tip.

The QR data will be:

https://qr.hips.com/m/[YOUR_MERCHANT_ID]/[UNIQUE_ID]?dynamic={"table":"7","waiter":"2"}

All data that are passed in dynamic will be reposted in the start_qr_session web hook. See Pay Flow below.

If you want to use hips API to generate the dynamic QR code you could use the following API call where [UNIQUE_ID] is your QR code created via API or in the dashboard:

{
    "dynamic": {"table":7,"waiter":2,"extra":"test"}
}

This will give you a response that looks like this:

{
    "status": "online",
    "code_token": 1,
    "qr_start_webhook_url": "...",
    "allow_tip": true,
    "qr_data": "https://qr.hips.com/m/.../...",
    "qr_code_b64_png": "iVBORw0KGgoAAAANSUhEUgAAAfQAAAH0AQAAAADjreInAAAFc0lEQV.....",
    "mapped_to_sales_channel_id": "VRB6sFNiAWG5RUMBWTGFQtg8",
    "order_timeout_seconds": 120,
    "payment_timeout_seconds": 300,
    "customer_text_preset_type": "general",
    "asynchronous": false
}

To show your QR code for the payer in a web browser, you should embed the QR data in the tag like this:

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAfQAAAH0AQAAAADjreInAAAFc0lEQV.....">

If you want to save the PNG QR code in a file. You should Base64 decode the content in [qr_code_b64_png] before writing the data to a .png file.

Generate static QR codes

Static QR codes are pre-generated codes that you later attach to your account. The QR codes can be created and attached to merchants and sales channels via API.

Generate QR codes via API
Please see the QR API Create Payment QR Code

Self generated QR codes
You may also pre-generate and print codes on your own by following the instructions here.

https://qr.hips.com/m/[YOUR_MERCHANT_ID]/[UNIQUE_ID]?dynamic=

An example would be: https://qr.hips.com/m/ABC123/1 where ABC123 is the Merchant ID and 1 is the unique QR code for this merchant.

🚧

Connect a QR code to a sales location

Before any QR code can be used it must be connected to a sales location via our QR API. This is true for both API generated and self generated QR codes. Connect a Static QR Code

PayFlow

In this flow Hips waits for an order being submitted with the amount before the customer can make any payment. This solution is suitable for POS systems that have a full integration to Hips. In this mode tipping can be enabled and will be added to the pre-sent order amount.

1. Create a QR code
   Use the following API endpoint Create Static QR Code

2. Connect the QR code (now the code is scannable by a customer)
   Use the following API endpoint Connect a Static QR Code

3. Customer scans the QR code
   Hips will post an start QR request to the URL specified when connecting a QR code in param qr_start_webhook_url. The content of this post will be a JSON object of the QR code.

🚧

The webhook will be sent and expect a http code of 200 or 201. If there is a different http code or a http timeout occurs (10 seconds), a new request will be sent (up to 3 requests). The idempotency key will be the same.

The webhook requesting to start the QR session sent to qr_start_webhook_url will look like this:

{
  "request_type": "start_qr_session",
  "session_id": "ac7ed0cb-67f9-497b-bbb5-3339bcbea371",
    "one_time_order_api_key": "eyJhbGciOiJIUzI1NiJ9.eyJkYXRhIjp7InNpZ25faW5fdHlwZSI6ImFwaSIsInNpZ25fc2NvcGUiOiJ0ZW1wX2FwaV9iZWFyZXJfa2V5X3NhbGVzX2NoYW5uZWwiLCJzaWduX2luX2lkIjoiUW00N0Y3Y3ptTkRhaldOeHNWMlppYzdmIn0sImV4cCI6MTYwMTM4NDc0Nn0.BPKHsBl54dZOSfAFO3nZXwaFmS6y0AsYMpueWDuhBR8",
  "idempotency_key": "732ac2b0-232b-41a0-bc37-ca8a46870394",
  "qr_id": "3snn8vUxMTZfHmnDwgPLSuR3",
  "sales_channel_id": "Yo63AdPXo9k9XzWSJjfqrdCV",
  "qr_code": "my-qr-serial-number",
  "allow_tip": false,
  "execute_at": "2019-10-19T18:34:49.898 01:00",
  "order_timeout_seconds": 120,
  "payment_timeout_seconds": 300,
  "dynamic":{"table":"7","waiter":"2"},
  "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJkYXRhIjp7InJlcXVlc3RfdHlwZSI6InN0YXJ0X3FyX3Nlc3Npb24iLCJzZXNzaW9uX2lkIjoiYWM3ZWQwY2ItNjdmOS00OTdiLWJiYjUtMzMzOWJjYmVhMzcxIiwiaWRlbXBvdGVuY3lfa2V5IjoiNzMyYWMyYjAtMjMyYi00MWEwLWJjMzctY2E4YTQ2ODcwMzk0IiwicXJfaWQiOiIzc25uOHZVeE1UWmZIbW5Ed2dQTFN1UjMiLCJzYWxlc19jaGFubmVsX2lkIjoiWW82M0FkUFhvOWs5WHpXU0pqZnFyZENWIiwicXJfY29kZSI6Im15LXFyLXNlcmlhbC1udW1iZXIiLCJhbGxvd190aXAiOmZhbHNlLCJleGVjdXRlX2F0IjoiMjAxOS0xMC0xOSAxODozNDo0OSArMDEwMCIsIm9yZGVyX3RpbWVvdXRfc2Vjb25kcyI6MTIwLCJwYXltZW50X3RpbWVvdXRfc2Vjb25kcyI6MzAwfSwiaXNzIjoiaGlwcy5jb20ifQ.moaAIDJS_2PaKYsV2QQRtqMR5b5DwBfNuyFxFrFJ1vrN6CnSyDUDbxtYkvJ2fpXG8vREPBG0XiyzjO7ODRFMzRtfw4lgTY0ZBk0Wa9AoHrZD4zySG3rEWyD5vIgB7N5-qyr6lBO36e0V4rVb-Add6kD-431w1H7ppR17-Q3QjuwgzO9_GBt4vad65g1_850HoQMD-6vIhRAvERIuwNvE5nBx4VZLA_ytcfoEwfHWYLPsuNky5sfXtKM4MrlcLJReLs72Ua74geRWMMkBV4MuL-vSSxFD3e5hhJxYCEWj_BB_WqPf0r6s1ECB8mdkxaxqOffd8tqnZx1Fs3kfTNxSBw"
}

📘

One Time Order API Key

You can use the API Key of the sales channel (if known) - or if you are an external system vendor, you would use the value in "one_time_order_api_key" as the Authorization Bearer token when creating the order. Example headers: Authorization: Bearer < one_time_order_api_key >

🚧

Vending machine down?

If your vending machine or other device are down and you want to tell the user something, please return HTTP code 412 on the "start_qr_session" event and the JSON string {"down_response_text":"Machine is down!"} to notify the user about this.

👍

Validate the webhook

If you wish to validate the authenticity of the webhook from Hips, please read here: Validating Webhooks

🚧

Vending machines expected behavior

At this point the vending machine should initiate the cashless payment protocol with the credit amount set to -1 (Unspecified amount). Once the customer has chosen a product and the amount is known, then continue to step 4. For vending machines the fulfilled parameter should be set to false when creating an order.

🚧

Taxi expected behavior

When connecting a QR, make sure allow_tip is set to true should you want the user to be prompted about adding tip (Max 20% on top of the original amount). If you get a callback on the qr_start_webhook_url, then you know that this specific taxi mapped to this QR code's customer want to pay by QR payment. When the ride is over, and the amount is known, the taxi system should go to step 4 and create an order. But only in the case when qr_start_webhook_url first has been triggered. For taxi the fulfilled parameter should be set to true when creating an order.

4. Create an Order
   Use the following API endpoint Create Order. Make sure you pass in the code_token retrieved when creating and connecting the QR code. Pass that token in the qr_code_token parameter when you create an order. Don't forget to set the webhook_url when creating an order to get payment events. The qr_start_webhook_url will not be triggered anymore at this stage.

5. Wait for web hook callback
   Now you just have to wait for a callback to the URL specified when creating the order in parameter webhook_url

🚧

Vending machines expected behavior

If there is a successful payment and the product was dispensed, you should call the Fulfill API Fulfill an order to make sure the amount is settled. If for some reason the product could not be dispensed, you should call the Refund API. Not doing anything will result in an automatic refund after 7 days.

🚧

Restaurant behavior

Restaurants should make sure the QR code setting in dashboard (or via API) is set to asynchron. We recommend restaurants to print a dynamic QR code on each pro-forma receipt with the data amount, table, reference, waiter, currency dynamically in the code. Then configure the QR payment code to do a IPN web hook to POS system or POS server when the payment is completed.

If you instead want to send the amount via API, then make sure you have set the timeouts very high (at least 20 minutes) on the QR code (configurable via API or in dashboard).

📘

System Integrator

Let Hips support know if you are a system integrator and want custom fields for each QR code to be entered when adding new QR codes in the merchant dashboard or via API, that is also sent back to you web hook. We currently support 4 custom fields.