Ukázková pokladna s integrací plateb

1. Přehled

Mo.one nabízí 3 metody integrace pro příjem plateb: On-Device (Intent) pro Android aplikace běžící přímo na terminálu, LAN (HTTP) pro libovolný POS systém ve stejné síti a Cloud pro vzdálené řízení přes centrální server. Všechny tři používají stejné JSON schéma požadavku i odpovědi.

┌─────────────┐     Intent      ┌──────────────────┐
│  POS / App  │ ──────────────▶ │  Mo.one terminál │
│  (Android)  │     request     │     (PayApp)     │
└─────────────┘                 └──────────────────┘
       │                                 │
       │  HTTP (LAN)                     │  WebSocket
       │  POST :8088/execute-operation   │  (Cloud)
       ▼                                 ▼
┌─────────────┐                 ┌──────────────────┐
│  Libovolný  │                 │   Cloud server   │
│  POS systém │                 │   (centrální)    │
└─────────────┘                 └──────────────────┘

2. Proč je integrace snadná

3. Podporované typy požadavků

{
  "type": "payment",
  "amount": "150.00",
  "currency": "CZK",
  "reference": "ORDER-12345",
  "orderId": "ORD-001",
  "invoiceId": "INV-0099",
  "clerkId": "CLERK-01",
  "tipAmount": "10.00",
  "paymentMethodConstraints": ["MOONE", "EFT"]
}

{
  "type": "refund",
  "amount": "50.00",
  "currency": "CZK",
  "reference": "REF-12345"
}

{ "type": "lastresult" }

4. Struktura odpovědi (TransactionResult)

{
  "type": "payment_result",
  "result": {
    "status": "APPROVED",
    "method": "MOONE",
    "amount": "150.00",
    "approvedAmount": "150.00",
    "currency": "CZK",
    "reference": "ORDER-12345",
    "date": "2026-01-16T13:23:53.778Z",
    "customerMessage": "Transakce schválena",
    "eftResult": {
      "transactionId": "TXN-123456",
      "authorizationCode": "AUTH123",
      "cardBrand": "VISA",
      "truncatedPAN": "****1234"
    }
  }
}

Pole method může nabývat hodnot MOONE, XPAY, SWITCHIO. EFT detaily jsou v eftResult.

5. Metody integrace

A. HTTP integrace (LAN)

Pro POS systémy ve stejné lokální síti. Base URL: http://<device-ip>:8088. Komunikace probíhá přes REST.

• GET/statusOvěření stavu terminálu
• POST/execute-operation/{device_id}Synchronní operace (blokuje do dokončení)
• POST/start-operation/{device_id}/{operationId}Asynchronní start operace
• GET/operation-status/{device_id}/{operationId}Polling stavu asynchronní operace
• POST/stop-operation/{device_id}/{operationId}Hint na zrušení (best-effort)

curl -X POST http://192.168.1.25:8088/execute-operation/LOCAL \
  -H "Content-Type: application/json" \
  -d '{
    "type": "payment",
    "amount": "150.00",
    "currency": "CZK",
    "reference": "ORDER-12345",
    "paymentMethodConstraints": ["MOONE"]
  }'

B. On-Device integrace (Intent)

Pro Android aplikace běžící přímo na stejném zařízení jako Mo.one terminál.

// Kotlin · spuštění platby přes Intent
val intent = Intent().apply {
    setClassName("cz.moone.payapp", "cz.moone.payapp.ui.payment.PaymentActivity")
    putExtra("request", """
      { "type": "payment", "amount": "150.00", "currency": "CZK" }
    """.trimIndent())
}
paymentLauncher.launch(intent)

C. Cloud integrace

Stejné API jako LAN, ale přes centrální cloud server. Použijte skutečné Device ID místo "LOCAL" a nahraďte lokální IP URL cloudu.

6. Příklad implementace

Tato stránka volá vlastní Next.js API route (/api/demo/payment), která signál přeposílá na terminál. V produkci stačí stejný kód směrovat přímo na /execute-operation.

async function processPayment(amount: number, currency: "CZK" | "EUR", method: "MOONE" | "EFT") {
  const res = await fetch("/api/demo/payment", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      type: "payment",
      amount: amount.toFixed(2),
      currency,
      reference: `ORDER-${Date.now()}`,
      paymentMethodConstraints: [method],
    }),
  });
  const data = await res.json();
  return data?.result?.status === "APPROVED";
}

7. Nastavení

Konfigurace cílového terminálu probíhá přes proměnné prostředí na serveru.