Pos Integration - Oolio Developer

POS Integration Guide

The communication from checkout app to POS is done asynchronously. For any information we need from the POS, Oolio will publish the event for requesting data and we expect the POS to post to the endpoint within 60 sec.

Receiving the events from the checkout-app

POS partner has an option to register a webhook URL per location with event types to subscribe or can poll for events from our events engine.

Events

order.requested

Trigger: Whenever a shopper enters the checkout app by scanning the QR code/visiting the URL
Action: POS can use this event to post the order detail to the checkout api Return
- 200 OK
- 503 Service Unavailable when POS doesnt have an order to send on the URL

Sample Order Request Event

{
  "type": "order.requested",
  "timestamp": "2023-11-03T20:30:00.0Z",
  "data": {
    "id": "16216f4d-cf05-4447-b964-614a44c4679c",
    "order_ref": "SP-1234",
    "table_num": "T-1",
    "location_id": "FPYCBCHYMXFK1"
  }
}

tables.requested

Trigger: Whenever the merchant setups the connection to the QR tags app
Action: POS can use this event to post the section & table details to the checkout api Return
- 200 OK
- 503 Service Unavailable when POS post the table data

location.connected

Trigger: Whenever the merchant setups the location linking to POS locatin
Action: POS can use this event to create the mapper Oolio location in the pos db Return
- 200 OK
- 503 Service Unavailable

location.disconnected

Trigger: Whenever the merchant removes the location linking with POS location
Action: POS can use this event to delete the mapper Oolio location in the pos db Return
- 200 OK
- 503 Service Unavailable

checkout.initiated

Trigger: Whenever a shopper clicks on the checkout button after viewing the bill
Action: POS can use this event to lock the table Return
- 200 OK, once received and POS is happy for checkout app to begin the checkout process.
- 503 Service Unavailable when POS is not ready for the checkout app to go ahead.

checkout.abandoned

Trigger: Whenever a shopper abandons the checkout due to inactivity for more than 5 min
Action: POS can use this event to unlock the table Return
- 200 OK
- 503 Service Unavailable

checkout.cancelled

Trigger: Whenever a shopper cancel the checkout
Action: POS can use this event to unlock the table Return
- 200 OK
- 503 Service Unavailable

checkout.completed

Trigger: Whenever a shopper completes the checkout
Action: POS can use this event to close the table Return
- 200 OK
- 503 Service Unavailable

Sample Checkout Event

{
  "type": "checkout.initiated",
  "timestamp": "2023-11-03T20:30:00.0Z",
  "data": {
    "id": "01HVNHMDQMXD7B2568PN9N24BZ",
    "order_ref": "SP-1234",
    "table_num": "T-1",
    "order_total": {
      "value": 4000,
      "currency": "AUD"
    },
    "location_id": "FPYCBCHYMXFK1",
    "expiry": "2023-11-03T21:00:00.0Z"
  }
}

transaction.initiated

Trigger: Whenever a shopper enters the payment info and clicks pay
Action: POS can use this event to add txn on the order Return
- 200 OK
- 503 Service Unavailable

transaction.pending

Trigger: Whenever a shopper waiting for the payment response
Action: POS can use this event to update txn status on the order Return
- 200 OK
- 503 Service Unavailable

transaction.cancelled

Trigger: Whenever a shopper clicks cancel while payment is initiated
Action: POS can use this event to update txn status on the order Return
- 200 OK
- 503 Service Unavailable

transaction.rejected

Trigger: Whenever a shopper receives the payment respone as rejected
Action: POS can use this event to update txn status on the order as rejected Return
- 200 OK
- 503 Service Unavailable

transaction.completed

Trigger: Whenever a shopper receives the payment respone as authorised
Action: POS can use this event to update txn status on the order as completed and update the order total. Return
- 200 OK
- 503 Service Unavailable

Sample Transaction Event

{
  "type": "transaction.initiated",
  "timestamp": "2023-11-03T20:30:00.0Z",
  "data": {
    "id": "11b969ea-2e4d-46ac-b727-3a7528e5306b",
    "method": "visa",
    "amount": 1000,
    "surcharge": 100,
    "tip": 100,
    "rounding": 2,
    "createdAt": "2023-07-21T17:32:28Z",
    "status": "requested",
    "trn": "01HVN1X8SED9J8WPPSAFYKTD09",
    "metadata": {
      "order_ref": "SP-1234",
      "checkout_id:"01HVNHMDQMXD7B2568PN9N24BZ",
      "items": [
        "01HVN1X8SE2HAQ1TNE9FXK6VW1",
        "01HVN1X8SE2HAQ1TNE9FXK6VW1"
      ],
      "consumer": "John Smith"
    }
  }
}

Polling our events engine

We use SVIX and here's the documentation for polling URL (opens in a new tab)

Usecases Catalogue