{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"b4da3635-b656-4c64-8fbc-725907fbf69b","name":"UIC-CONNECT Gateway Cloud APIs V1","description":"## Overview ##\n(DRAFT)\nThe **UIC-CONNECT Gateway Cloud APIs** provide a comprehensive set of cloud-based interfaces for payment processing, merchant management, device provisioning and transaction reporting. These APIs enable third-party integrators to seamlessly onboard and manage merchants, remotely configure and control UIC payment terminals, initiate and monitor card-present and token-based transactions and generate detailed transactional reports — all through a unified, secure gateway.\n\nUIC-CONNECT Gateway Cloud APIs are running a **cloud control** for payment terminals with an **async session + webhook** model and terminals connected to the cloud via **MQTT**.\n\nThis API is designed for **System Integrators** who want to:\n- Onboard merchants and terminals\n- Provision and manage merchants and terminals\n- Initiate **card-present** transactions asynchronously (SALE / AUTH) on a UIC Payment terminal\n- Execute **cloud-side** transaction actions (CAPTURE / VOID / REFUND / TOKEN operations)\n- Retrieve transaction reports and download report files\n- Receive real-time results via **webhooks** (with signatures + replay protection)\n\n## System Diagram ##\nThe terminal APIs are used by UPE to receive payment-related commands from the MQTT Client, trigger the corresponding processing on the payment terminal and then return the result to the UIC-CONNECT cloud server.  \nThese commands currently include:\n\n- **AUTH/SALE** – Authorization or sale transaction\n- **REFUND** – Full or partial refund transaction\n- **TXN CANCEL** – Cancellation of an in-progress or recently initiated transaction\n\n## The UIC-CONNECT System Diagram\n\nThe UIC-CONNECT system architecture consists of the following main components:\n\n- **UIC-CONNECT Cloud** – Central cloud platform that manages transaction routing, authorization results and integration with acquiring banks or payment services.\n- **UIC Agent** – Middleware service that connects to the UIC-CONNECT Cloud, handling secure communication and protocol translation to UIC terminals.\n- **UIC Terminals (with UPE / MQTT Client)** – Payment terminals running the UPE application and MQTT Client. These devices receive commands from the cloud, interact with cardholders (card reading, PIN entry, etc.) and submit transaction data back to the cloud.\n\n![UIC-CONNECT Architecture](https://content.pstmn.io/1d777cc1-0ff9-4abe-aa78-2d59ed940366/VUlDLUNPTk5FQ1QgRlVMTCBBcmNoLnBuZw==)\n\nIn the system diagram, the posiiton of UIC-CONNECT Gateway Cloud APIs shows as follows:\n\n![UIC-CONNECT Terminal API Scope](https://content.pstmn.io/1dc4c1bf-c2ea-4d36-919b-dba1df280027/VUlDLUNPTk5FQ1QgQ2xvdWQgQVBJLnBuZw==) \n\n\n## Key Concepts\n### 1) Terminal Session\nA **terminal session** represents a short-lived interaction window with a specific terminal (typically one customer checkout).\nThe POS application/server by the system integrator create a session, then issue terminal commands (SALE/AUTH). The terminal UI + card interaction happens on the device.\n\n### 2) Asynchronous Operation\nAll actions that can take time (terminal commands, cloud payment actions, report generation) return:\n- **200 Accepted**\nThe final outcome arrives via webhook events. As a fallback, the POS application/serevr can poll `GET /GetOperations`.\n\n### 3) MQTT Transport (Terminal ↔ Cloud)\nREST requests do not talk to the terminal directly. Instead:\n- REST creates an operation\n- UIC-CONNECT Cloud publishes an MQTT command to the terminal\n- Terminal responds with MQTT events\n- UIC-CONNECT Cloud retruns the response and may convert events upon requests into webhook notifications for POS application/server\n\n### 4) Webhooks (Result Delivery)\nThe POS application/server system registers webhook endpoints (or provides a per-session callback URL). The cloud sends events like:\n- `payment.succeeded`, `payment.authorized`, `payment.failed`\n- `refund.succeeded`, `refund.failed`\n- `terminal.session.updated`, etc.\n\n### 5) Idempotency\n`Idempotency-Key` is required for all state-changing requests to make\nretries safe. \n\n- `Idempotency-Key: <uuid>`\nThis prevents double charges/refunds if you retry due to timeouts.\n\n**Authentication model**\n\n- API key only for gateway APIs: `Authorization: Bearer`\n    \n- System Integrator (SI) onboarding uses UIC-issued **username/password**\none-time to obtain the initial API key.\n     \nSee the **Authentication**, **Idempotency**, and **Webhooks** tag\ndescriptions for detailed guidance and examples.\n\n## Naming convention\n\n- All JSON request/response fields use **PascalCase** (i.e.\n`OldApiKeyExpiresAt`, `GracePeriodSeconds`, `GatewayRequestID`).\n    \n- Query parameters and path parameter names follow the same convention\n(i.e. `GatewayMerchantID`).\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"48004383","team":9796596,"collectionId":"b4da3635-b656-4c64-8fbc-725907fbf69b","publishedId":"2sBXVckCff","public":true,"publicUrl":"https://gateway-cloud-api.uic-connect.com","privateUrl":"https://go.postman.co/documentation/48004383-b4da3635-b656-4c64-8fbc-725907fbf69b","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"4646ff"},"documentationLayout":"classic-single-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":"https://content.pstmn.io/633e7acd-fa5b-4f21-b8b8-1156a522e98b/VUlDLWxvZ28ucG5n","colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"4646ff"}},{"name":"light","logo":"https://content.pstmn.io/633e7acd-fa5b-4f21-b8b8-1156a522e98b/VUlDLWxvZ28ucG5n","colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"4646ff"}}]}},"version":"8.10.1","publishDate":"2026-01-02T06:49:40.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":"https://content.pstmn.io/633e7acd-fa5b-4f21-b8b8-1156a522e98b/VUlDLWxvZ28ucG5n","logoDark":"https://content.pstmn.io/633e7acd-fa5b-4f21-b8b8-1156a522e98b/VUlDLWxvZ28ucG5n"}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/847d00b84c6785c057026030be3f848ce143461f49629597c9ae692aaf03b57c","favicon":"https://uic-connect.com/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://gateway-cloud-api.uic-connect.com/view/metadata/2sBXVckCff"}