Terminal provisioning

Use this runbook to enroll a Peak Android terminal from Terminals in the Support Portal at support.peakpos.co. It covers creation, one-time enrollment, activation evidence, and safe diagnosis. It does not authorize credential extraction, certificate bypasses, forced deprovisioning, or direct database repair.

Service and authorization boundary

The operator never calls the onboarding service directly:

Support Portal
  -> management-api (support/agent Firebase identity + Peak authorization)
  -> terminal-onboarding internal token API (service identity)
  -> Android terminal polls with the one-time PIN
  -> terminal-onboarding issues the device certificate
  -> terminal-api accepts the activated device over mTLS

Support reads require mgmt.terminals.read; terminal creation, update, enrollment, reassignment, and lifecycle actions require mgmt.terminals.write. Payment configuration uses the separate mgmt.payment_configs.write permission. Support PINs use mgmt.support_pins.read/mgmt.support_pins.write.

Agent-accessible routes also enforce portfolio and sale-floor limits. A support or agent login is not interchangeable with a terminal identity.

Before creating a terminal

Confirm:

• the organization and destination store exist and are the intended records;
• the organization's plan tier allows the selected device model;
• the store is operationally ready for POS use;
• terminal name, device model, manufacturer, and serial number are available;
• the selected model's management provider and income source are correct;
• shipping state, carrier, and tracking number are known when applicable;
• the Gateway location and payment-device plan are known when card payments will be enabled;
• the on-site operator has the physical device, network access, and can enter a 12-digit setup PIN immediately.

Managed models that require a serial number cannot be created without it. Scan or copy the physical serial exactly; do not substitute an order number, tracking number, payment-device serial, or a serial from another store.

If this hardware was previously enrolled, stop and inspect its existing terminal/lifecycle state. A replacement terminal gets its own record. A reused device must complete the supported deprovision lifecycle before a new enrollment PIN becomes available.

Device identity and lifecycle

Keep these identities distinct:

Value	Meaning
Organization ID	Merchant boundary
Store ID	Assignment and catalog/payment boundary
Terminal ID	Server-owned POS terminal identity
Lifecycle version	Fences tokens and credentials to the current terminal lifecycle
Device model/manufacturer	Expected hardware identity
Device serial number	Physical-device match used during pairing
Enrollment PIN/token ID	Short-lived bootstrap credential; not a terminal identity
Certificate serial/hash	Activated mTLS credential for terminal-api
Payment-device identity	Separate card-present device/link; never use it as the terminal serial

An onboarding PIN is valid only for the terminal, store, and lifecycle for which it was generated. The onboarding service rejects expired tokens, unconfirmed tokens, lifecycle mismatches, store mismatches, a different device key on replay, an already-certified terminal, and reported device identity that does not match the terminal record.

Create the terminal record

1. Open the client and Terminals.
2. Select Create Terminal.
3. Choose the destination Store.
4. Enter a clear Terminal Name, such as Front Register 1.
5. Select the Device Model. Verify the derived manufacturer and management provider.
6. Enter the device serial when required.
7. Select the correct Income Source:
   • an external terminal for a separate payment device; or
   • Android Tap to Pay when the POS device itself will accept supported contactless payments.
8. Review Tap to Pay provisioning state and shipping fields.
9. Select Create Terminal once.

Expected evidence is one terminal row under the selected store with status Pending Enrollment (pending_onboarding/pending). Correct a wrong store, model, manufacturer, or serial before issuing a PIN.

Creating the terminal does not enroll the device, configure a Gateway payment device, or prove that the Android app is online.

Enroll the Android device

1. Generate the one-time PIN

For the pending terminal, select Enrollment PIN. The Support Portal asks management-api to create the token through the internal terminal-onboarding boundary.

The dialog displays a 12-digit PIN that expires in 15 minutes. Treat it as a credential:

• give it only to the operator holding the intended device;
• do not paste it into tickets, chat transcripts, notes, screenshots, or this documentation;
• do not generate several active PINs for the same terminal;
• close the dialog without approval if the intended device is not ready.

2. Start the device bootstrap

Have the on-site operator enter the PIN on the intended Android terminal. The device polls POST /v1/onboarding/poll. While the token is still pending, the device remains pending and eventually times out.

Confirm with the operator that the device accepted the PIN and started polling before proceeding.

3. Approve terminal setup

Select Approve Terminal Setup in the same dialog. This confirms the token through management-api; it does not issue a certificate in the browser.

After approval, the device creates its own private key and CSR and calls POST /v1/onboarding/certificate with the confirmed token and reported device identity. terminal-onboarding validates the lifecycle/store/device match, signs the CSR with Private CA, activates the certificate through the terminal-api internal boundary, and marks the one-time token used.

Never request or copy the device private key. Never install a certificate from one terminal on another.

Activation evidence

Refresh Terminals and verify all applicable signals:

• terminal status is active, not Pending Enrollment, disabled, revoked, or deprovisioning;
• the terminal is still assigned to the intended organization and store;
• recorded model, manufacturer, management provider, and serial match the physical device;
• certificate serial/expiry is present and expiry is in the future;
• Last Heartbeat advances after the device starts;
• fleet diagnostics report the same terminal/store and show the device online;
• device-reported serial agrees with the managed terminal serial;
• push/app state is healthy when fleet management applies;
• payment configuration and payment-device link are correct for the selected income source;
• the operator can sign in only after the intended merchant user, store membership, and PIN are configured.

Certificate issuance without a later heartbeat is incomplete evidence. A fleet row without matching terminal/store/serial identity is also incomplete.

Payment configuration is a separate handoff

Use Payment Setup only after confirming the merchant's Gateway location, income source, payment runtime, and physical payment device. Enrollment proves the POS terminal identity; it does not prove that the Gateway SDK, external card-present terminal, or Tap to Pay account is provisioned.

If the payment-device link is pending, blocked, mismatched, or revoked, diagnose that lifecycle through the payment configuration/link controls. Do not clear, relink, or replace device identifiers merely to remove a warning.

Troubleshooting

Enrollment PIN is unavailable

The action appears only for an inactive pending terminal whose prior deprovision operation is absent or completed. Verify the selected record and lifecycle. If old hardware is still active or deprovisioning, finish the supported lifecycle or escalate; do not create a duplicate record to bypass the gate.

Device reports an invalid or expired PIN

Confirm the PIN has 12 digits, belongs to the selected terminal, and is still within its 15-minute window. Generate one fresh PIN and repeat the device-poll, then support-approval sequence. Do not approve before the intended device is polling.

Device remains pending after PIN entry

Check that Support selected Approve Terminal Setup, the device has network and correct time, and the PIN has not expired. Preserve the terminal ID, token ID, lifecycle version, and exact onboarding response for escalation. Do not send the PIN itself.

Certificate exchange fails

Compare the terminal's store, lifecycle, expected model, managed serial, and existing certificate state. A serial/model/store mismatch is an identity problem, not a retry problem. Correct the authoritative terminal record only when the physical evidence is clear; otherwise escalate.

Certificate exists but no heartbeat arrives

Confirm the device is using the newly issued certificate, can reach the terminal endpoint, has correct time, and was not assigned to another store. Compare fleet last-seen and device-reported serial. Collect Android logs through the approved diagnostic workflow; do not weaken mTLS.

Terminal was online and stopped

Check power, network, device time, last heartbeat, certificate expiry, fleet last-seen, and push status. One offline terminal points first to device/network state; several terminals at one store suggest a store network or upstream service incident.

Safe escalation

Escalate with:

• organization, store, and terminal IDs;
• terminal lifecycle version and current status;
• model, manufacturer, management provider, and redacted serial evidence;
• token ID and token status, never the 12-digit PIN;
• certificate serial/expiry, never private key material;
• last heartbeat and fleet last-seen timestamps;
• exact onboarding or terminal API error;
• whether Support approval occurred and the last safe action taken.

Do not force deprovision, delete records, clear payment-device links, rotate credentials, edit database rows, or mint certificates outside the supported workflow unless an approved incident procedure explicitly assigns that action.