Terminal API

Our terminal API is designed to integrate with Payment Terminals, which are capable of rendering QR Codes, and that integrate to some form of internal middleware/service.

Flow

PartPay / Terminal Integration Flow

  1. PartPay tender type is selected on payment terminal
  2. Payment terminal middleware makes request to create terminal order endpoint.
  3. This operation returns either a base64-encoded JPEG or a URL to retrive image for QR Code to render on device.
  4. Payment terminal displays QR
  5. Customer, using the PartPay mobile application, scans the QR code
  6. PartPay confirmation process is completed by customer
  7. PartPay API calls back to Payment terminal middleware, advising of payment outcome
  8. Payment terminal middleware instructs successful payment taken.

Order State

Belwow is a diagram describing the various state changes for the order.

Terminal Order State Transition

Terminal State

The red statuses indicate a terminal state for a given order

When an order reaches a terminal state, PartPay will initiate a callback to the payment gateway service.

Authentication

Authentication for terminal API integration is only considered for machine-to-machine request contexts between PartPay and the terminal payment service. Any customer app-level security is out of scope for this API.

The PartPay API’s are secured by our standard OAuth2 security schema.

Merchant Ids

PartPay assigns a ‘Merchant Id’ to each retailer when they join PartPay. For clarity, the scope of a retailer is generally associated with the trading brand, and it it not associated with any one physical store. Typically credentials are issued to each merchant, and these are paired to a given Merchant Id.

When requests are made to the Terminal API, they are done under a heightened-privilege context. That is, the Payment terminal service makes requests on behalf of merchants. This means the Payment terminal service must keep a store of the merchant id’s that are associated to a given retailer, and pass these as an custom header when making a request to the PartPay Terminal API.