Pairing Code

POST /pos/pairing-code

Generates a 6-character alphanumeric pairing code that is displayed on the POS device screen. The merchant enters this code in the backoffice web portal to claim the device. This is the second step in the POS activation flow.

Purpose

• Generate a short, human-readable code for device-to-portal pairing
• The code is valid for 5 minutes (300 seconds)
• Ambiguous characters (0, O, I, 1) are excluded to avoid confusion
• Only one active pairing code per device at a time

Authentication

POS Activation Auth — device identification headers only.

Header	Required	Format	Description
X-Device-Id	Yes	POS-{8_HEX_CHARS}	Unique identifier for the physical POS device. Must match a pre-provisioned device. Example: POS-8F3A2C91
User-Agent	Yes	Viopay-POS/{version} ({OS}; {model})	POS app version string. Must start with Viopay-POS/. Example: Viopay-POS/1.4.2 (Android 12; PAX-A920)
X-Client-Type	Yes	pos	Client type identifier. Always pos for POS devices.

See the Headers Reference for complete details.

Request

No request body is required.

Response

200 OK

{
  "pairing_code": "K7M3NP",
  "expires_in_sec": 300
}

Field	Type	Description
pairing_code	string	6-character alphanumeric code (uppercase, no ambiguous chars)
expires_in_sec	integer	Seconds until the code expires (always 300)

400 Bad Request

{
  "error": {
    "code": "4000",
    "message": "X-Device-Id header is required",
    "trace_id": "abc123..."
  }
}

500 Internal Server Error

{
  "error": {
    "code": "5000",
    "message": "Failed to create pairing code",
    "trace_id": "abc123..."
  }
}

Code Examples

cURL

curl -X POST https://api.viopay.io/pos/pairing-code \
  -H "X-Device-Id: POS-8F3A2C91" \
  -H "User-Agent: Viopay-POS/1.4.2 (Android 12; PAX-A920)" \
  -H "X-Client-Type: pos" \
  -H "Content-Type: application/json"

Python

import requests

url = "https://api.viopay.io/pos/pairing-code"
headers = {
    "X-Device-Id": "POS-8F3A2C91",
    "User-Agent": "Viopay-POS/1.4.2 (Android 12; PAX-A920)",
    "X-Client-Type": "pos",
    "Content-Type": "application/json",
}

response = requests.post(url, headers=headers)
data = response.json()

print(f"Pairing Code: {data['pairing_code']}")
print(f"Expires in: {data['expires_in_sec']} seconds")

Ruby

require 'net/http'
require 'json'
require 'uri'

uri = URI("https://api.viopay.io/pos/pairing-code")

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["X-Device-Id"] = "POS-8F3A2C91"
request["User-Agent"] = "Viopay-POS/1.4.2 (Android 12; PAX-A920)"
request["X-Client-Type"] = "pos"
request["Content-Type"] = "application/json"

response = http.request(request)
data = JSON.parse(response.body)

puts "Pairing Code: #{data['pairing_code']}"
puts "Expires in: #{data['expires_in_sec']} seconds"

Go

package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

type PairingCodeResponse struct {
    PairingCode  string `json:"pairing_code"`
    ExpiresInSec int    `json:"expires_in_sec"`
}

func main() {
    req, _ := http.NewRequest("POST", "https://api.viopay.io/pos/pairing-code", nil)
    req.Header.Set("X-Device-Id", "POS-8F3A2C91")
    req.Header.Set("User-Agent", "Viopay-POS/1.4.2 (Android 12; PAX-A920)")
    req.Header.Set("X-Client-Type", "pos")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)

    var result PairingCodeResponse
    json.Unmarshal(body, &result)

    fmt.Printf("Pairing Code: %s\n", result.PairingCode)
    fmt.Printf("Expires in: %d seconds\n", result.ExpiresInSec)
}

C#

using System.Net.Http;
using System.Text.Json;

var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://api.viopay.io/pos/pairing-code");
request.Headers.Add("X-Device-Id", "POS-8F3A2C91");
request.Headers.Add("User-Agent", "Viopay-POS/1.4.2 (Android 12; PAX-A920)");
request.Headers.Add("X-Client-Type", "pos");

var response = await client.SendAsync(request);
var body = await response.Content.ReadAsStringAsync();
var data = JsonSerializer.Deserialize<JsonElement>(body);

Console.WriteLine($"Pairing Code: {data.GetProperty("pairing_code")}");
Console.WriteLine($"Expires in: {data.GetProperty("expires_in_sec")} seconds");

PHP

<?php

$ch = curl_init("https://api.viopay.io/pos/pairing-code");

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "X-Device-Id: POS-8F3A2C91",
        "User-Agent: Viopay-POS/1.4.2 (Android 12; PAX-A920)",
        "X-Client-Type: pos",
        "Content-Type: application/json",
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

echo "Pairing Code: " . $data["pairing_code"] . "\n";
echo "Expires in: " . $data["expires_in_sec"] . " seconds\n";

Java

import java.net.http.*;
import java.net.URI;

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.viopay.io/pos/pairing-code"))
    .POST(HttpRequest.BodyPublishers.noBody())
    .header("X-Device-Id", "POS-8F3A2C91")
    .header("User-Agent", "Viopay-POS/1.4.2 (Android 12; PAX-A920)")
    .header("X-Client-Type", "pos")
    .header("Content-Type", "application/json")
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

What's Next?

After displaying the pairing code on the POS screen, the device should poll the status endpoint to check if the merchant has claimed it:

Next step → Check Status