Device Registration

Overview

Before a terminal can accept payments — or receive a partner POS app — it must be registered to a store under a merchant. Registration links the physical (or software) device to your merchant hierarchy. Once a terminal is registered to a store, it cannot be repurposed by another merchant. You can still move it between stores under the same merchant using the Change Store endpoint.

Surfboard supports several registration methods so you can pick the lowest-friction option for your setup. They are not mutually exclusive — the same terminal can be registered through whichever path the merchant has available.

If you integrate through one of our SDKs (Android SoftPOS, Tap to Pay on iPhone), the SDK handles registration for you and you do not need to call the registration APIs directly. See Android SoftPOS SDK and Tap to Pay on iPhone.

When Is Registration Needed?

Terminal type	Registration required?	Typical method
EMV (countertop, mobile POS, kiosk)	Yes — the terminal must be registered before it can receive a partner POS app or take payments	Rotating code, QR/registration link, or pre-shipped code
SoftPOS (CheckoutX on Android)	Yes	In-app (interapp) registration, or any of the code-based methods
SDK-based (Android SoftPOS SDK, Tap to Pay on iPhone)	Handled by the SDK	N/A — SDK methods cover registration

Registration Methods at a Glance

Method	How the merchant registers	Code validity	Best for
Rotating 6-digit code	Reads a code from the terminal screen and enters it into the Surfboard merchant portal or the partner’s portal/app	~90 seconds (rotates)	Attended setup where someone is in front of both the terminal and a portal
QR / registration link	Taps the QR icon on the terminal’s registration screen and scans a QR generated by the partner or Surfboard merchant portal	Short-lived	Fast, near zero-touch scan-to-register
Pre-shipped code	Enters a code provided ahead of time (e.g. a welcome email or SMS) directly on the terminal registration screen	Longer-lived	Unattended setup, or when the 90-second rotation is impractical
In-app (interapp)	Switches to CheckoutX, which registers the device automatically — no code entry	n/a	SoftPOS / CheckoutX only

---

Method 1 — Rotating 6-Digit Code

When a terminal starts up on its registration screen, it displays a 6-digit code that rotates roughly every 90 seconds. The merchant reads this code and enters it into a registration screen — either the Surfboard merchant portal or the partner’s own portal or app.

Behind the scenes, the portal calls the Register Device API with the code as the registrationIdentifier:

POST /merchants/:merchantId/stores/:storeId/devices

{
  "registrationIdentifier": "250901",
  "terminalName": "Kiosk One"
}

Parameter	Required	Description
registrationIdentifier	Yes	The 6-digit code shown on the terminal. For SurfPad and Printer devices, use the serial number printed on the back instead.
terminalName	No	A human-readable label to identify the terminal.

Response:

{
  "status": "SUCCESS",
  "data": {
    "terminalId": "813ca2cb12ce400405",
    "registrationStatus": "REGISTERED"
  },
  "message": "Terminal registered successfully"
}

registrationStatus is either REGISTERED (new device) or ALREADY_REGISTERED (device was previously linked). Store the returned terminalId — you need it for all subsequent calls on this device.

Because the code rotates every ~90 seconds, complete the entry promptly. If it expires, read the new code from the screen and try again.

See the Register Device API reference for the full request/response and error codes.

---

Method 2 — QR Code / Registration Link

The terminal’s registration screen also shows a QR icon. Tapping it opens the camera so the merchant can scan a QR code provided by the partner or by the Surfboard merchant portal. The QR encodes a registrationLink — a deep link that registers the device automatically, with no manual code entry.

Generate the link with the Get Device Registration Code API:

GET /merchants/:merchantId/stores/:storeId/device-registration

Response:

{
  "status": "SUCCESS",
  "data": {
    "registrationCode": "905788",
    "registrationLink": "checkoutx://com.surfboard.checkoutx/register?data=eyJyZWdpc3RyYXRpb25Db2RlIjoiOTA1Nzg4In0="
  },
  "message": "Registration Code Generated Successfully"
}

Field	Description
registrationCode	A 6-digit code the merchant can enter manually (see Method 3).
registrationLink	A deep link that, encoded as a QR code, registers the device when scanned.

Render registrationLink as a QR code in your partner portal or app, or let the Surfboard merchant portal generate it for you. The merchant scans it from the terminal’s registration screen and the device registers itself.

See the Get Device Registration Code API reference.

---

Method 3 — Pre-Shipped Code

The same Get Device Registration Code API also returns a registrationCode. Unlike the rotating on-screen code, this code has longer validity, which makes it a good fit for setups where the ~90-second rotation is impractical.

A common pattern: a partner generates the code ahead of time and delivers it to the merchant out of band — for example in a welcome email or SMS sent before the terminal ships. When the device arrives, the merchant simply enters the code on the terminal’s registration screen and the device registers.

This supports a near zero-touch onboarding experience: the merchant never has to coordinate a live, time-limited code between the terminal and a portal.

---

Method 4 — In-App (Interapp) Registration for SoftPOS

For SoftPOS running CheckoutX, you can register a device by switching into the CheckoutX app — no code entry needed. Your app opens CheckoutX via a deep link, CheckoutX registers the terminal, and control returns to your app with the resulting terminalId.

This is the smoothest option for SoftPOS and partner POS apps that already integrate with CheckoutX. It is not available for EMV terminals, which must use one of the code- or QR-based methods above.

For the full app-switch flow — generating the interapp code, building the deep link, and handling the callback — see the Inter-App Integration guide.

---

After Registration

Once a terminal is registered:

• Use the returned terminalId to create orders and initiate payments. See Create an Order.
• Apply configuration (network, language, restart schedule, and more) — see Terminal & Device Management.
• Move the terminal between stores under the same merchant with the Change Store endpoint, or reassign across merchants (partner-managed inventory) with Move Terminal — both covered in Terminal & Device Management.

API Quick Reference

Operation	Method	Endpoint
Register a device	POST	/merchants/:merchantId/stores/:storeId/devices
Get registration code & link	GET	/merchants/:merchantId/stores/:storeId/device-registration
Get interapp code (SoftPOS)	GET	/merchants/:merchantId/stores/:storeId/terminals/interapp

Reference

• Register Device API
• Get Device Registration Code API
• Inter-App Integration
• EMV Terminal Integration
• Terminal & Device Management