SEQR Unattended Payments Service introduction

SEQR Unattended Payments Service (UPS) is service that allows your unattended POS to integrate with SEQR.

On this page you will find information how to proceed with UPS integration.

Actors

  • SEQR user - SEQR’s and self-service machine user
  • reseller - your backend maintaining self-service machines
  • SEQR Unattended Payments service - SEQR service that will initiate purchase process on reseller side
  • SEQR - SEQR backend
  • SEQR app - SEQR mobile application

Flow diagram

All starts with user scanning QR code on your unattended POS.

method/service exposed by part of API description
createPurchase reseller SEQR Unattended Payment Service REST service called by SEQR Unattended Payment Service once user scanned QR Code on unattended POS. URL has to be HTTPS and end with “createPurchase” (for example https://yourdomain.name.com/seqr/createPurchase).
sendInvoice SEQR SEQR Payment SOAP method called by reseller backend triggered by createPurchase request. This method creates invoice on SEQR side and returns it’s reference number (invoiceReference). By calling this method reseller provides also notificationUrl to be used for callbacks.
notification callback service reseller SEQR Payment notificationUrl will be called (empty HTTPS POST responded with HTTP 200 OK code) by SEQR once customer confirmed or cancelled payment.
getPaymentStatus SEQR SEQR Payment SOAP method called by reseller backend triggered by notification callback. Returns payment status - RESERVED or CANCELLED.
updateInvoice SEQR SEQR Payment SOAP method called by reseller after user choose products from self-service machine to update rows and totalAmount of final invoice.
commitReservation SEQR SEQR Payment SOAP method called by reseller to finalise payment process.

All above methods/services are mandatory to implement.

Flow description

  1. Customer scanns QRCode placed on sel-service machine using SEQR app.
  2. SEQR Unattended Payments service calls createPurchase exposed by reseller sending JSON with token (machine id).
  3. Reseller calls sendInvoice exposed by SEQR and returns the invoice reference to SEQR Unattended Payments service.
  4. Reservation details are presented to customer.
  5. Customer confirms or cancels reservation with PIN number.
  6. SEQR calls notificationUrl provided in sendInvoice request.
  7. Reseller calls getPaymentStatus and retrieves reservation status. If RESERVED merchants proceeds to next steps.
  8. Reseller unlocks self-service machine allowing user to choose the products.
  9. Customer chooses products from self-service machine.
  10. Reseller calls updateInvoice exposed by SEQR to change details of invoice that user will see in SEQR app.
  11. Reseller calls commitReservation to commit transaction with final amount.

SEQR Unattended Payment Service QR code scheme

Qr code should have scheme:

HTTP://SEQR.SE/000/ups?w=merchantId&t=123456

where:

  • w - merchantId sent in start-up kit (usually the same as resellerId)
  • t - token (machine id) that will be passed in createPurchase request to merchant

SEQR Unattended Payment Service API

At this point our SEQR Unattended Payment Service API is based on one REST method - createPurchase which is required to be exposed by reseller.

createPurchase method

This method will be called by SEQR Unattended Payment Service once customer scanned SEQR QR Code on unattended POS. SEQR Unattended Payment Service service will sent below values to reseller’s backend.

createPurchase request

URL: https://yourdomain.name.com/seqr/createPurchase
HTTP method: POST
Headers: "Accept: application/json;Content-Type: application/json;charset=UTF-8"
Body:
{
    "token": "29834231890234",
    "amount": 20.00,
    "currency": "EUR",
    "msisdn": "483344323423"
}
parameter description
token This is identifier of self-service machine or purchase.
amount Max reservation amount for which invoice should be created by reseller.
currency Currency of reservation amount.
msisdn Customer’s phone number.

createPurchase response

Status Code: 200
Headers: "Content-Type: application/json;charset=UTF-8"
Body:
{
   "invoiceReferenceId":"20170315072260070"
}
parameter description
invoiceReferenceId invoiceReference from sendInvoice response see SEQR Payment API.

Error createPurchase response

Status Code: 200
Headers: "Content-Type: application/json;charset=UTF-8"
Body:
{
   "errorCode":"SYSTEM_ERROR"
}
parameter description
errorCode Error code specifying the error on reseller’s backend.

Possible values of error code

parameter description
INSUFFICIENT_FUNDS amount is to low to start the payment flow on reseller’s side. Eg. reservationAmount is lower than cheapest product in self-service machine.
DEVICE_IN_USE Device is already used by another customer. Someone else scanned qrCode, agreed for purchase but didn’t choose the product yet.
DEVICE_UNAVAILABLE Self-service machine is out of service.
INVOICING_ERROR Error occurred while calling sendInvoice exposed by SEQR (SEQR Payment API).
SYSTEM_ERROR Generic error.