EPOS Communication
The Paynt EPOS API is a RESTful service that runs directly on PAX terminals.
It enables secure communication between your POS system and the terminal over HTTP/HTTPS.
Communication Flow
Step-by-Step
-
Pairing – Your POS system authenticates with the terminal using a pairing code and receives an auth token.
-
Request – Your POS sends a transaction request (sale, refund, etc.) with the auth token in the header.
-
UTI Response – The terminal immediately returns a UTI (Unique Transaction Identifier) to acknowledge the request.
-
Processing – The terminal displays the payment screen and waits for the customer to tap or insert their card.
-
Status Check – Your POS queries the transaction status using the UTI to get full details once the payment completes.
Why Use UTI Patterns?
The UTI (Unique Transaction Identifier) system decouples the transaction request from its result.
A UTI is an alphanumeric string consisting of 1-64 characters. Special characters are not allowed. Each UTI must be a unique value. The UTI can be re-used only when the previous one expires, which currently happens after 3 months, though this is subject to change.
This design is important because:
Asynchronous Processing
Card processing takes time:
- Customer interaction (reading prompts, entering PIN)
- Network calls to the payment processor
- Receipt printing
Your POS doesn't need to wait with an open connection during all of this.
Resilience
- Network interruptions don't lose transactions
- You can check the status at any time
- Multiple systems can query the same transaction
Simplicity
- Fire-and-forget request model
- Poll for results when ready
- No complex callback infrastructure needed
Request Authentication
Every request after pairing must include the auth token in the Authorization header:
Authorization: 7653518633181484
The auth token:
- Is issued during pairing
- Remains valid until re-pairing
- Should be stored securely by your POS
API Architecture
The EPOS API follows REST principles:
| Aspect | Implementation |
|---|---|
| Protocol | HTTPS (self-signed certificate) |
| Format | JSON |
| Base URL | https://{IP}:{PORT}/payntpos/1.0.0 |
| Authentication | Bearer token in header |
Endpoints
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /pair | Authenticate and get token |
| POST | /transaction | Start a transaction |
| GET | /transaction | Get transaction status |
Error Handling
The API uses standard HTTP status codes:
| Code | Meaning |
|---|---|
| 200 | Success |
| 400 | Bad request (check parameters) |
| 401 | Unauthorized (invalid or missing token) |
| 500 | Terminal error |
Always check both the HTTP status and the transApproved field in the response.
Related
- Network Configurations – Local vs external networks