The KeyPos Identity Model
In the Getnet Cloud-to-Cloud (C2C) ecosystem, KeyPos is the fundamental identity model used to uniquely address and route commands to a specific physical terminal. This model ensures that requests from your Cashier Software reach the intended hardware device with zero ambiguity, even within large-scale merchant infrastructures.
The Identity Triplet
A KeyPos consists of a specific "triplet" of data points associated with a physical POS device. You must include these three parameters in the request body of every transactional or management API call to identify the target terminal.
| Parameter | Type | Length | Description |
|---|---|---|---|
idTerminal | String | 8 chars | Unique alphanumeric identifier assigned by Getnet to the specific POS. |
idSucursal | Integer | 6-10 chars | The merchant branch or store number assigned to the POS. |
serialNumber | String | 12 chars | The unique physical serial number found on the back label of the device. |
Implementation in API Requests
Pass the KeyPos triplet in the JSON payload when initiating any command, such as a sale, refund, or device parameters request.
Warning: If any element of the triplet is missing or incorrect, the Cloud API returns acode: 0error indicating "KEYPOS NOT FOUND" or "INCORRECT REQUEST FOR MERCHANT ID".
Payload Example
Ensure your JSON structure follows the exact naming conventions defined in the technical specification:
json
{
"idTerminal": "80005000",
"idSucursal": 12983,
"serialNumber": "SNPRUEBA1234",
"command": 100,
"amount": 25000
}json
{
"idTerminal": "80005000",
"idSucursal": 12983,
"serialNumber": "SNPRUEBA1234",
"command": 100,
"amount": 25000
}Discovery and Validation
Synchronize your local terminal database with the Getnet Cloud using the discovery endpoints:
- Fleet Discovery: Call the List All POS (
GET /api/posdata) endpoint to retrieve the complete array of KeyPos triplets associated with your credentials. - Branch Filtering: Use the List POS by Branch (
GET /api/posdata?idsucursal={id}) endpoint to scope discovery to a specific location. - Verification: Use the POLL command (
106) to verify the configuration between Getnet Cloud and the terminal during initial setup.
Important: Do not use the POLL command to validate connectivity before every transaction. The Cloud API performs this validation automatically during transactional requests to optimize latency.
On this page
The KeyPos Identity Model