Quickstart: your first payment (Local API)

This quickstart takes you from an empty terminal to a completed card payment over the Local API using the HTTP transport. It uses the flat JSON message shape and the asynchronous POST-then-poll pattern. For the socket (TCP/IP) transport, the same messages apply with a different envelope, see Transport bindings: TCP/IP vs HTTP.

Import the POS-http light Postman collection attached to this article to run every call below without writing code. Set the collection variables hostAddress, port (8080), and currency (for example 978 for EUR) first.

1. Open a session : Login

Every HTTP session starts with a Login and ends with a Logout. POST /login:

{
  "MessageHeader": {
    "ProtocolVersion": "3.1",
    "MessageClass": "Service",
    "MessageCategory": "Login",
    "MessageType": "Request",
    "ServiceID": "1001",
    "SaleID": "POS_01",
    "POIID": "POI_01"
  },
  "LoginRequest": {
    "DateTime": "2026-07-01T09:00:00.0+02:00",
    "OperatorID": "Cashier_01",
    "OperatorLanguage": "EN",
    "SaleSoftware": [{
      "ApplicationName": "My POS",
      "ProviderIdentification": "MyCompany",
      "SoftwareVersion": "1.0.0"
    }]
  }
}

A Response.Result of Success means the session is open.

2. Take a payment — POST then poll

Send the payment, then poll the same endpoint for the result. POST /payment:

{
  "MessageHeader": {
    "MessageClass": "Service",
    "MessageCategory": "Payment",
    "MessageType": "Request",
    "ServiceID": "1002",
    "SaleID": "POS_01",
    "POIID": "POI_01"
  },
  "PaymentRequest": {
    "PaymentData": { "PaymentType": "Normal" },
    "PaymentTransaction": {
      "AmountsReq": { "Currency": "EUR", "RequestedAmount": 10.00 }
    },
    "SaleData": {
      "OperatorID": "Cashier_01",
      "SaleTransactionID": {
        "TimeStamp": "2026-07-01T09:01:00Z",
        "TransactionID": "ticket-0001"
      }
    }
  }
}

The POST returns 202 Accepted. Now issue GET /payment repeatedly until you get a final result:

On the final 200, check PaymentResponse.Response.Result (Success / Failure) and store POITransactionID — you need it to reverse or refund this payment later.

3. Close the session — Logout

POST /logout ends the session. Re-login after any terminal restart.

Two rules that prevent silent failures

• ServiceID must be unique per message pair within the session — it is how the terminal detects duplicates and protects against double payments. Never send a constant such as 0.
• TransactionID must be 35 characters or fewer. Longer values (for example a raw 36-character UUID) are rejected with response code 90001 and no payment is taken.