Skip to main content

Activation And Health

Activation links a POS system to the OpenApp integration profile of one location. Each location has its own integration profile, served by one POS backend for all of its tills.

The merchant generates a PIN in the merchant panel. The POS operator enters the merchant tax identifier and the PIN into the POS, and the POS calls:

POST /merchant/v1/pos/activate

The request body is ActivatePos and the response is PosActivationResponse.

PIN rules​

  • The PIN has 8 digits and expires 15 minutes after it is generated.
  • A PIN works once. A failed or expired PIN requires a new one.
  • A merchant has one pending PIN at a time. Generating a new PIN invalidates the previous one.

Responses​

Activation failures return HTTP 200 with success: false and a failure reason. OpenApp returns HTTP 429 when a source IP address or tax identifier makes too many attempts.

Re-activation​

Activating again for the same location replaces both credential sets. The previous API key and queue access key stop working immediately, so a reinstalled or moved POS backend must store the new ones.

Health​

After activation, the POS reports health on activation and at regular heartbeat intervals. If OpenApp receives no health check within the timeout configured on the integration profile, it stops sending POS-backed ordering commands and tells customers that the location is unavailable.

This diagram is logical. It omits delivery-mode details; see Architecture for the delivery model.

Message types:

Message typeDirectionPurpose
ActivatePosPOS -> OpenAppSubmit merchant tax identifier and PIN to activate the POS.
PosActivationResponseOpenApp -> POSReturn activation result and, on success, credentials and delivery config.
ReportPosHealthPOS -> OpenAppReport POS health on activation and at regular intervals.