Integrators: Identifying static QR transactions

📘

This article is about passing additional data with a STATIC QR code added Via API or via Hips Dashboard.

👍

Using static QR stickers?

Make sure you have received Hips QR stickers from your payment partner. You can also order QR stickers online in Hips webshop

Intro

A payer scans a static QR code sticker in a taxi. Now Hips will send a web hook to the system integrator asking for the amount the payer should pay. But where will Hips send the web hook, and how do the system integrator know from which taxi car the QR code is placed in? The answer: Pre-defined System Integrator

Pre-defined System Integrator

If you are a system integrator (ISV) you can set up a pre-defined custom ruleset and custom fields required by all your merchants. Once a merchant adds a QR payment code; then Hips will ask the user to complete your required fields.

In the above example, the system integrator TDS Norway have chosen to add 3 custom fields Central code, Vehicle number and Owner number. Hips will ask for those additional parameters every time a new QR code is added to the platform under TDS Norway.

What data can be pre-defined by a system integrator?

The following data can be pre-defined by system integrators:

• allow_tip (boolean) - Should we ask the payer for tip?
• asynchronous (boolean) - Should the QR code accept more than one request at the same time?
• order_timeout_seconds (integer) - How long will the QR page wait for callback from the system integrator?
• payment_notification_webhook_url (string) - Where should we send the IPN/Payment Confirmation hooks for this system integrator?
• payment_timeout_seconds (integer) - How long will the QR page wait for the user to complete payment?
• qr_start_webhook_url (string) - Where should we send the start_session hooks for this system integrator?
• token_1_description (string) - A token description/name that will be visible for the merchant. In the above case "Central code"
• token_1_name - A token parameter name that will be sent back to the system integrator Via API for the merchant. In the above case "central_code"
• token_2_description (string) - A token description/name that will be visible for the merchant. In the above case "Vehicle number"
• token_2_name - A token parameter name that will be sent back to the system integrator Via API for the merchant. In the above case "vehicle_number"
• token_3_description (string) - A token description/name that will be visible for the merchant. In the above case "Owner number"
• token_3_name - A token parameter name that will be sent back to the system integrator Via API for the merchant. In the above case "owner_number"
• token_4_description (string) - A token description/name that will be visible for the merchant. In the above case this param is not used
• token_4_name - A token parameter name that will be sent back to the system integrator Via API for the merchant. In the above case this param is not used

In addition to the above, Hips need the following to set you up as a system integrator:

• description (string) - Description of the system integrator, max 255 chars.
• name (string) - Name of the system integrator

📘

How do I add myself as a system integrator?

Send an email with all information in the above section to [email protected] with email topic "New system integrator".

Example callback with system integrator parameters

Here is an example of a json web hook callback with the above example data that Hips will post to the system integrator qr_start_webhook_url. Once you get this web hook from Hips, it means that someone has scanned the QR code and you must reply by calling the Create Order API.

{
    "request_type": "start_qr_session",
    "session_id": "f8e919b9-a739-xxx-xxx-63508db7c2a0",
    "one_time_order_api_key": "xxxxxxx",
    "locale": "nb-no",
    "idempotency_key": "5c25fb44-xxxx-xxxx-xxxx-xxxxf452eb12",
    "qr_id": "Ypyabzzqc8b281igxxxxxxx",
    "sales_channel_id": "B16bBKhEEFMhamcxxxxxx",
    "qr_code": "vYDzcykh",
    "allow_tip": false,
    "execute_at": "2021-01-14T18:10:49.089+00:00",
    "order_timeout_seconds": 120,
    "payment_timeout_seconds": 300,
    "dynamic": {
        "central_code": "123",
        "vehicle_no": "5678",
        "owner_no": "9999"
    }
}