Integrating a Sunmi or Nexgo card terminal with your POS

Sunmi and Nexgo Android terminals are common at Zimbabwean counters. This guide takes one from the box to its first payment pushed from your till, using the Revoluno Cloud API.

What you need

• A Sunmi terminal with the Revoluno app, or a Nexgo terminal with the Revoluno switch app.
• A Revoluno Cloud console login, and an API key created under Developers.
• The terminal's serial number. It is printed on the label under the battery or on the back.

Step 1: register the terminal

Terminals are registered by serial number. In the console, open Readers → Register reader, or call the API from your own setup screen:

POST /v0.1/merchants/{merchant_code}/readers
{ "serial_number": "PB0921A5S1234", "name": "Counter 1", "model": "SUNMI_P3" }

The answer contains a device_key such as DX2A2-T9RX2-ES6M6-AMXVY. It is shown once, so keep it until the next step is done.

Step 2: activate it on the terminal

1. Open the Revoluno app on the terminal and go to Cloud terminal → Settings.
2. Set the backend URL to https://cloud.revoluno.online.
3. Enter the device key. Case, dashes and spaces don't matter.
4. Tap Check setup, then Start taking payments.

In the console the reader changes from pending to paired and shows as online. It stays online while the app is in cloud mode.

Lost the key, or replacing a terminal? Issue a new key for the reader. The old one stops working immediately.

Step 3: send a test payment

Before writing any code, use Test payment on the reader in the console. The amount appears on the terminal, and you can watch the checkout go from waiting to approved or declined. Your webhook receives the result too, if you have set one.

Step 4: push payments from your till

Store the reader's id against the till lane or table it serves. When the cashier presses "Card", send a checkout to that reader:

POST /v0.1/merchants/{merchant_code}/readers/{reader_id}/checkout
{ "total_amount": { "currency": "USD", "minor_unit": 2, "value": 1500 },
  "foreign_transaction_id": "SALE-000123" }

Then wait for the webhook. The till integration guide covers the screens and the error cases.

Checking a terminal before a sale

To show the cashier why a terminal is unavailable, read its status first:

GET /v0.1/merchants/{merchant_code}/readers/{reader_id}/status
→ { "data": { "status": "ONLINE", "state": "IDLE" } }

state is IDLE, WAITING_FOR_READER while a payment waits to be picked up, or PROCESSING while the customer pays.

Timeouts to design for

• The terminal has 60 seconds to pick a payment up, or it fails as EXPIRED.
• Once picked up, it has 4 minutes to finish.
• If a terminal reports an approval after the checkout expired, the checkout becomes successful and you get a second webhook, because the card was charged. Always act on the latest event.