Terminal Registration

Once the terminals are received by your merchants after onboarding, they are ready to be registered and activated. This simple process links the terminal to the merchant and store, enabling you to accept payments. These steps can be completed through SagaPay APIs or the Merchant Dashboard.

Overview of the Flow

┌─────────────────────────────────────────────────────────────────────────────┐
│                        Terminal Registration Flow                            │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Merchant      │     │    Register     │     │    Terminal     │
│   Receives      │ --> │    Terminal     │ --> │    Ready for    │
│   Terminal      │     │                 │     │    Payments     │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                               │
                               ▼
                    ┌─────────────────────┐
                    │  Registration       │
                    │  Methods:           │
                    │  • API              │
                    │  • Dashboard        │
                    └─────────────────────┘
                               │
                               ▼
                    ┌─────────────────────┐
                    │  Requires:          │
                    │  • 6-digit code     │
                    │  • Store ID         │
                    │                     │
                    │  Returns:           │
                    │  • Terminal ID      │
                    └─────────────────────┘

Pre-requisites

Before registering and configuring terminals via SagaPay APIs or the Merchant Dashboard, ensure:

API Credentials

Valid API-KEY, API-SECRET, and MERCHANT-ID for API registration

Physical Terminal

The merchant’s physical terminal, powered on and connected

Registration ID

6-digit registrationId from terminal display (or serial number for SurfPad)

Store ID

Valid storeId where the terminal will be registered

Register a Terminal Using the API

Power On Terminal

Power on the terminal after receiving it. A 6-digit code (registrationId) will be displayed.

For SurfPad, use the serial number found on the back of the device instead of the 6-digit code.

Send Registration Request

Send a request to the Register Terminal API, including the registrationId and the storeId (the store where the terminal will be registered).

Receive Terminal ID

Upon successful registration, the response will include the terminalId.

For SoftPOS, registration can also be done via inter-app switch if configured on your end. See the CheckoutX Inter-App Guide for details.

Example Request

$ curl -X POST \
>   -d '{
>     "registrationId": "250901",
>     "storeId": "83402f67a06b68040f"
>   }' \
>   -H 'Content-Type: application/json' \
>   -H 'API-KEY: your-api-key' \
>   -H 'API-SECRET: your-api-secret' \
>   -H 'MERCHANT-ID: your-merchant-id' \
>   'https://api.sagapay.no/terminals'

Example Response

1 {
2   "status": "SUCCESS",
3   "data": {
4     "terminalId": "a1b2c3d4e5f6g7h8i9",
5     "storeId": "83402f67a06b68040f",
6     "serialNo": "SN123456789",
7     "status": "ACTIVE"
8   },
9   "message": "Terminal registered successfully"
10 }

Additional Terminal Configurations

After terminal registration, you can customize the terminal’s functionalities and configurations at various hierarchical levels through our APIs and the Merchant Dashboard.

Configuration Hierarchy

The configuration settings follow a hierarchical structure across four levels:

┌─────────────────────────────────────────────────────────────┐
│                    Configuration Hierarchy                   │
└─────────────────────────────────────────────────────────────┘

        Partner Level (Default/Fallback)
                    │
                    ▼
        Merchant Level (Overrides Partner)
                    │
                    ▼
        Store Level (Overrides Merchant)
                    │
                    ▼
        Terminal Level (Highest Priority)

How Configuration Inheritance Works

Configuration Rules

Lower-level configuration overrides higher-level configurations: If a configuration is set at the Terminal level, it will override any settings at the Partner, Merchant, and Store levels.
Configuration fetched from higher levels: If no configuration is set at the Terminal, Store, or Merchant levels, the system will automatically fetch the default setting from the Partner level.
Individual parameter configuration: All parameters can be configured individually, eliminating the need to configure all parameters at once.

Configuration APIs

Terminal configurations can be applied at various levels using the following APIs:

API	Level	Description
Set Merchant Terminal Config API	Merchant	Apply config to all terminals under a merchant
Set Store Terminal Config API	Store	Apply config to all terminals in a store
Set Terminal Config API	Terminal	Apply config to a specific terminal

Configuration Parameters

The following parameters are available for terminal configuration:

Parameter	Description	Supported Terminals
`serialNo`	Serial number of the hardware terminal	SurfPad, SurfTouch, SurfPrint
`wifiSsid`	Name of the WiFi network the terminal connects to	SurfPad
`wifiPassword`	Password for the WiFi network	SurfPad
`autoSleep`	Auto sleep time (in seconds) when terminal sleeps due to transaction inactivity; applies only on battery power	SurfPad
`preferredRestartTime`	Schedules restart time (HH:MM) for the terminal, defaults to 02:00 AM	SurfPad
`preferredNetwork`	Preferred network type: `"WIFI"` or `"GSM"`	SurfPad
`alwaysShowMinorUnits`	If true, minor units are shown (e.g., 29 displayed as 29.00)	SurfPad
`language`	Two-letter ISO code (e.g., `en` for English) for display language	SurfPad, SurfTouch, SurfPrint, SoftPOS
`showStatusBar`	If `TRUE`, displays the status bar	SurfPad
`chipReadDelay`	Delay (in milliseconds) before reading a card	SurfPad
`showReceipt`	Determines if receipts are displayed on the terminal	SurfTouch, SurfPrint, SoftPOS
`preferredGsmOperator`	Numeric code for the preferred GSM operator	SurfPad
`openPosOnReboot`	Configures if POS opens automatically after reboot (`"enabled"` or `"disabled"`)	SurfTouch, SurfPrint
`enableLockScreen`	Enables the lock screen feature on Android terminals	SurfTouch, SurfPrint
`enableRefundLock`	Enables the refund lock screen on Android terminals	SurfTouch, SurfPrint, SoftPOS
`lockScreenPin`	PIN to unlock the lock screen	SurfTouch, SurfPrint
`refundScreenPin`	PIN to authorize refunds	SurfPrint, SurfTouch, SoftPOS
`screenTimeout`	Time (in milliseconds) before screen times out due to inactivity	SurfPrint, SurfTouch, SoftPOS
`autoSleepInterval`	Interval (in milliseconds) before the device auto-sleeps	SurfPad
`receiptScreenTimeout`	Timeout (in milliseconds) for the receipt screen	SurfPrint, SurfTouch, SoftPOS

Example: Set Terminal Configuration

$ curl -X PATCH \
>   -d '{
>     "language": "no",
>     "showReceipt": true,
>     "screenTimeout": 30000,
>     "enableRefundLock": true,
>     "refundScreenPin": "1234"
>   }' \
>   -H 'Content-Type: application/json' \
>   -H 'API-KEY: your-api-key' \
>   -H 'API-SECRET: your-api-secret' \
>   -H 'MERCHANT-ID: your-merchant-id' \
>   'https://api.sagapay.no/terminals/{terminalId}/config'

Example Response

1 {
2   "status": "SUCCESS",
3   "data": {
4     "terminalId": "a1b2c3d4e5f6g7h8i9",
5     "language": "no",
6     "showReceipt": true,
7     "screenTimeout": 30000,
8     "enableRefundLock": true
9   },
10   "message": "Terminal configuration updated successfully"
11 }

Configuration by Terminal Type

SurfPad

SurfTouch / SurfPrint

SoftPOS

Available configurations:

Network settings (wifiSsid, wifiPassword, preferredNetwork, preferredGsmOperator)
Power management (autoSleep, autoSleepInterval, preferredRestartTime)
Display (language, showStatusBar, alwaysShowMinorUnits)
Card reading (chipReadDelay)