| Tabla de Contenido |
|
|
🚧 Early Release — Beta
This product is in early access. Parameters, response structures, and behaviors are subject to change without prior notice. Do not use this version in production without previous coordination with the Kushki integrations team.
Discover the basic concepts, architecture, and operation modes of our omnichannel in-person payments solution.
Kushki ONE is available exclusively for merchants in 🇲🇽 Mexico, 🇨🇱 Chile, and 🇵🇪 Peru.
1. What is Kushki One?
Kushki One is the Card Present payments solution from Kushki. It enables merchants to accept physical card payments through SmartPOS terminals, both autonomously and integrated with external systems such as POS, ERPs, or proprietary applications.
Its architecture is designed to adapt to different business models: from direct manual use on the terminal to complex technical integrations via API.
2. Main components
2.1 SmartPOS terminals
Kushki One operates on Android terminals from the Sunmi line, specifically:
- Sunmi P3: high-end portable terminal with integrated printer.
- Sunmi P2 SE: compact terminal for lighter operations.
These terminals feature a touchscreen, Wi-Fi and 4G connectivity, ICC chip reader, MCR magnetic stripe, and NFC for contactless payments.
2.2 Kushki One Payment App (Atom)
This is the native application installed on the terminals. From it, you can:
- Process sales, authorizations, and captures directly.
- Manage refunds.
- View transaction history with filters.
- Review closing reports (Sales Summary).
- Configure tips and local terminal settings.
2.3 Kushki One Connect (integration API)
This is the integration layer that allows external systems (POS, ERP, merchant apps) to send instructions to the terminal without the operator having to manually enter amounts. It communicates via HTTP REST requests.
3. Operation modes
The terminal's behavior depends on the mode it is configured in:
| Mode | Description |
|---|---|
| Standalone | The operator uses the terminal like an advanced calculator. They enter amounts manually, select the payment type, and operate completely independently. No integration with external systems is required. |
| Semi-integrated | The terminal screen remains locked on "Waiting for call." An external system (POS or merchant software) sends payment instructions via API. The operator only interacts with the terminal to present the card or confirm the amount. |
4. General architecture
Kushki One relies on two cloud services that work together:
| Service | Function |
|---|---|
| Console TMS | Terminal management system (DMS) accessible by Kushki's internal team. From here, merchants are configured, terminal templates are managed, and device status is monitored. |
| Cloud TMS | Intermediary service that receives requests from the Console TMS and forwards them to the physical terminals. It also exposes the Kushki One Connect API for semi-integrated integrations. |
Merchant information (name, ID, credentials, deferred payment configuration, etc.) originates in the Kushki Console and is replicated to the DMS so that the terminals can operate correctly.
5. Available operations
The Kushki ONE Payment App supports the complete cycle of a Card Present sale transaction:
| Operation | Description |
|---|---|
| Sale | Single-step charge. Supports tip, merchant installments, issuer installments, and cashback. |
| Authorization | Reserves the credit limit on the card for a subsequent charge. |
| Capture | Charges a previously authorized amount. |
| Re-authorization | Modifies the authorized amount or extends the deadline to apply the capture. |
| Refund | Returns the funds from a sale. The system internally executes a void or a refund depending on the timing of execution. |
| Post Tip | Adds a tip amount after the transaction authorization. |
| Bill splitting | Divides a total amount into multiple sequential payments (equal or unequal). Useful in restaurants. |
6. Complete transaction flow
The following flow describes the interaction between all components from the moment a payment intent is initiated until the response is received:
Diagram: Complete transaction flow in Kushki One
- Request generation: The merchant's point-of-sale system (POS) generates the request by sending the amount to be charged via API to the payments ecosystem.
- Decision and routing: Kushki ONE Connect receives the request and makes a routing decision based on the configuration chosen by the merchant; in this way, it routes the request to the physical device, either through the Cloud or via the Local Network.
- Reception at the terminal and data capture: Kushki ONE Connect sends the payment request to the SmartPOS terminal. The terminal receives the request, displays the amount to be paid on screen, and reads the customer's card.
- Transaction processing: Once the data is read, the terminal sends the information to Kushki, which is ultimately responsible for processing the financial transaction.
Frequently asked questions (FAQ)
Does Kushki One replace the online payment methods I already have?
No. Kushki One is a solution exclusively for Card Present payments. If your business operates with online payments (Card Not Present), both solutions coexist independently.
Do I need a technical integration to use Kushki One?
Not necessarily. In Standalone mode, the operator can use the terminal directly without any integration. Technical integration is only required if you want an external system (such as a POS or point-of-sale software) to control the payment flow.
What happens if the terminal loses its internet connection?
It depends on the operation mode. In Standalone mode, the terminal can operate in offline mode with limited capabilities. In Semi-integrated mode, the loss of connection interrupts communication with the external system. For technical connectivity details, see the network architecture article.