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 a code: 0 error 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.