{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"7941e245-3dfa-4dd3-9253-efc3bdd391ac","name":"Kowri WebPOS Merchant APIs","description":"> This Application Programming Interface (API) describes how to integrate with the Kowri Point of Sale (POS)engine for order generation and payment collection as a Merchant (Biller). The Kowri POS API flow [diagram](https://drive.google.com/file/d/1p3p-sixJYoy_NyPdq4p7zvHodLua539g/view?usp=sharing) demonstrates the use of the APIs in preparing orders and processing payments. \n  \n> To Access the Kowri POS services the following are required: \n  \n\n- Web-Service URL\n    \n- Merchant Access Credentials\n    \n    - App Reference\n        \n    - Secret\n        \n    - App ID\n        \n\n---\n\n### Access Details\n\n---\n\n| Access type | Detail |\n| --- | --- |\n| Webservice Base URL (Live) | [https://posapi.kowri.app/](https://posapi.kowri.app/) |\n| Webservice Base URL (UAT) | [https://kbposapi.mykowri.com/](https://kbposapi.mykowri.com/) |\n| Test Account | Contact Kowri Merchant Acquiring rep for a test account |\n| App Reference | Contact Kowri integration team for app reference to access web-service |\n| Secret | Contact Kowri integration team for secret to access web-service |\n| App ID | Contact Kowri integration team for your App ID |\n\n---\n\n---\n\n### Callback Response\n\n---\n\nKowri POS is able to send a callback response to the merchant with details of the transaction, provided a callback URL has been set on the Kowri device. Visit our [knowledgebase](https://support.dreamoval.com) for more information on how to create devices.\n\n> **Callback Response Format** \n  \n\n| Parameter | Description |\n| --- | --- |\n| status | the status of the payment. |\n| _0_ | _Successful_ |\n| _\\-1_ | _Technical Error_ |\n| _\\-2_ | _Customer cancelled payment_ |\n| cust_ref | the merchantOrderId |\n| pay_token | the invoice number generated for the order |\n| transaction_id | the transaction Id generated for the successful payment |\n\n### Server-to-Server Callbacks\n\nOur API also supports server-to-server callbacks to notify merchants when payment transactions are completed. Callbacks are sent asynchronously after payment processing is finalized, allowing merchants to receive real-time updates about transaction status without polling.\n\n### Callback Configuration\n\nCallbacks can be configured in two ways:\n\n1\\. **Pre-configured Server Callback URL**: Your preferred callback URL can be sent to our operations team to configure on our backend for you. This URL will then be used for all transactions processed for that service.\n\n2\\. **Per-Request Webhook URL**: Include a \\`webhookUrl\\` in the payment request metadata. This allows you to specify a different callback URL for individual transactions, overriding the collection's default callback URL.\n\njson\n\n{\n\n``` json\n \"metadata\": \\[\n   {\n     \"key\": \"webhookUrl\",\n     \"value\": \"https://your-server.com/payment-callback\"\n   }\n \\]\n\n ```\n\n}\n\n**Priority:** If a \\`webhookUrl\\` is provided in the payment request metadata, it takes precedence over the pre-configured callback URL.\n\n### When Callbacks Are Sent\n\nCallbacks are triggered after payment processing is complete, specifically:\n\n\\- **Successful Payments:** When the service has been rendered successfully, you will receive a status of \\`FULFILLED\\`\n\n\\- **Failed Payments:** When the service could not be rendered for some reason, you will receive a status of \\`UNFULFILLED_ERROR\\`. Further details of the error will be provided in the \\`comment\\` field.\n\nCallbacks are sent asynchronously, so they do not block the payment processing flow.\n\n### Callback Payload Structure\n\nThe callback payload is sent as a JSON object via HTTP POST to your configured callback URL. The structure includes the following fields:\n\n``` json\n{\n\"amount\": \"5.50\",                    // Invoice amount (formatted to 2 decimal places)  \n\"currency\": \"GHS\",                   // Currency code    \n\"transactionId\": \"ZmLabWiwsX\",       // Initiator's transaction ID    \n\"serviceCode\": \"1512\",               // Merchant service code    \n\"status\": \"FULFILLED\",        // Transaction status: FULFILLED | UNFULFILLED_ERROR    \n\"success\": true,                     // Successful execution flag (boolean)    \n\"receiptNo\": \"513775030897\",         // Merchant's transaction receipt number    \n\"orderId\": \"22fb7509-eacf-4efa-bc8a-aa1a464d2691\",  // Merchant's order ID    \n\"comment\": \"Payment of GHS5.00 to Your collection\", // Payment narration/status message  \n\"callbackUrl\": null,                 // Web redirect URL (if configured)    \n\"customerReference\": null,          // Customer payment reference (e.g., ticket number)  \n\"paymentChannel\": \"MTN Mobile Money\", // Mode of payment    \n\"paymentChannelReference\": \"3711335187\",  // Transaction ID from payment processor    \n\"transactionDate\": \"2025-11-12T10:16:55\"  // Date of processing (ISO format)\n}\n\n ```\n\n### Additional Fields\n\nDepending on the transaction context, the following additional fields may be included:\n\n\\- **app_id:** The application id passed with the original payment request if applicable (included when the order has an associated app reference)\n\n\\- **payerName:** Name of the payer\n\n\\- **payerNumber:** Phone number of the payer\n\n\\- **paymentAccount:** Payment channel account number (phone number for mobile money payments)\n\n### Transaction Status Values\n\nThe \\`status\\` field in the callback payload can have the following values:\n\n\\- **FULFILLED:** Payment was successfully processed and completed\n\n\\- **UNFULFILLED_ERROR:** Payment processing failed or encountered an error\n\nThe \\`success\\` field is a boolean that directly indicates whether the transaction was successful (\\`true\\` for \\`FULFILLED\\`, \\`false\\` for \\`UNFULFILLED_ERROR\\`).\n\n### Callback URL (Redirect)\n\nThe \\`callbackUrl\\` field in the payload contains the web redirect URL that can be used to redirect users back to the merchant's website after payment. This URL is constructed from the \\`callbackUrl\\` provided in the original payment request and includes query parameters:\n\n\\- **Success:** \\`status=0&transac_id={transactionId}&cust_ref={orderId}&pay_token={invoiceNum}\\`\n\n\\- **Failure:** \\`status=-1&cust_ref={orderId}&pay_token={invoiceNum}\\`\n\n\\- **Cancelled:** \\`status=-2&cust_ref={orderId}&pay_token={invoiceNum}\\`\n\n### Implementation Notes\n\n\\- Callbacks are sent asynchronously using HTTP POST requests\n\n\\- Your callback endpoint should respond promptly (within a reasonable timeout)\n\n\\- It is recommended to implement idempotency checks in your callback handler to handle duplicate callbacks\n\n\\- Always verify the transaction status using the \\`transactionId\\` or \\`orderId\\` before processing the callback\n\n\\- The callback payload may include additional fields beyond those documented above, depending on the payment channel and transaction context\n\n---\n\n## API Methods\n\n---\n\nKowri POS endpoint calls will be made in the format of **JSON** requests over **HTTP POST**. The URLs provided in the rest of this documentation are relative to the web service base URL supplied in the **access details provided above**.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"8139575","team":436351,"collectionId":"7941e245-3dfa-4dd3-9253-efc3bdd391ac","publishedId":"TVYJ6HHZ","public":true,"publicUrl":"https://documenter-api.postman.tech/view/8139575/TVYJ6HHZ","privateUrl":"https://go.postman.co/documentation/8139575-7941e245-3dfa-4dd3-9253-efc3bdd391ac","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.10.1","publishDate":"2020-10-28T17:02:59.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[{"name":"Billbox POS","id":"cbcc0628-c717-408c-871c-29bf531f64ef","owner":"8139575","values":[{"key":"baseUrl","value":"","enabled":true},{"key":"transaId","value":"123456","enabled":false},{"key":"transId","value":"","enabled":true}],"published":true}],"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/9c59af4cdd760b0c8f0c4fe44f749dd1924e1f52675200c46ab24eb51347c615","favicon":""},"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"},{"label":"Billbox POS","value":"8139575-cbcc0628-c717-408c-871c-29bf531f64ef"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/TVYJ6HHZ"}