{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"330e0d92-b8a8-43fd-9599-b838fe143886","name":"M2Pay REST API Docs","description":"This collection is designed to help developers easily integrate and manage financial transactions with a payment terminal. It allows you to initiate transactions such as **sales**, **refunds**, and retrieve detailed **transaction results** using a series of HTTPS requests.\n\nThis API is ideal for merchants who want to seamlessly connect their software with a payment terminal, enabling them to process payments and query transaction results in real time.\n\n## Key Features\n\n- **Initiate Transactions**: Perform various types of financial operations (like sales and refunds) by sending transaction requests to the terminal.\n    \n- **Retrieve Transaction Results**: Fetch transaction details such as approval status, customer/merchant receipts, and card information.\n    \n- **Error Handling**: Understand and handle terminal states like busy devices, unresponsive terminals, or invalid operations.\n    \n\n## Collection Structure\n\nThis Postman collection is divided into the following two main endpoints:\n\n1. **Transactions (POST)**:  \n    `/transactions` endpoint allows you to initiate a transaction on the payment terminal by specifying details like the amount, currency, and terminal serial number. Optionally, you can provide a `callbackUrl` to receive transaction results asynchronously.\n    \n\n```\nKey Parameters:\n- **operation** (sale, refund)\n- **amount** (in smallest currency units)\n- **currency** (e.g., USD, EUR)\n- **terminal_type** (e.g., PAXA920)\n- **serial_number** (terminal serial number)\n- Optional: **callbackUrl** & **token** for result notifications.\nInitiate a sale for a specific amount by sending a POST request. If no `callbackUrl` is provided, transaction results can be retrieved manually using the `transactionResultId`.\n\n ```\n\nHow to Use This Collection\n\n## Test Environments\n\n- **Base URL**: `https://cloud.handpoint.com`\n    \n\nInitially for the testing purposes you will be connected to the Sanbox environment, meaning that none of the transactions will be sent to the card schema for the authorisation.\n\n**Step 1**: Set Up Your API Key\n\nAll requests require an `ApiKeyCloud` header for authentication. Make sure you replace the placeholder value in the collection with your actual API key.\n\n**Step 2**: Sending a Transaction\n\nTo initiate a transaction:\n\n1. Go to the **POST /transactions** request.\n    \n2. Modify the request body with your specific operation, amount, currency, and terminal details.\n    \n3. Send the request.  \n    You will receive a response containing a `transactionResultId` that you can use to fetch the transaction result later.\n    \n\n**Step 3**: Retrieving a Transaction Result\n\nTo retrieve the result of a transaction:\n\n1. Go to the **GET /transaction-result/{transactionResultId}** request.\n    \n2. Replace the placeholder in the URL with the actual `transactionResultId` received from your transaction initiation request.\n    \n3. Send the request to fetch the full `transactionResult` object.\n    \n\nNext is mapping from the `transactionResult` object to print customer receipt through the cash register with following data:\n\n| **Field** | **Mapping from response** |\n| --- | --- |\n| Status | finStatus |\n| Tip transakcije | transactionType |\n| Iznos | totalAmount |\n| ID trgovca | mid |\n| ID terminala | tid |\n| Naziv kartice | cardShemeNumber |\n| Maskirani broj kartice | maskedCardNumber |\n| Način unosa | paymentScenario |\n| Način provjere | verificationMethod |\n| Broj odobrenja | authorisationCode |\n| Vrsta kartice | tenderType |\n| GUID | efttransactionID |\n| AID | aid |\n| TVR | tvr |\n| IAD | iad |\n| TSI | tsi |\n| ARC | arc |\n\n**Acceptance tests:**\n\n1\\. Turn the terminal on and off, and confirm that it is properly connected to the internet and **Payment** application is running.\n\n2\\. Test transactions with different deductible amounts that are predefined:\n\n| **Amount** | **Behaviour** |\n| --- | --- |\n| 37.79 | Issuer response code = 01 (Refer to issuer) |\n| 37.84 | Issuer response code = 05 (Not authorized) |\n| 37.93 | Issuer response code = 04 (Pick up card) |\n| 37.57 | Request is partially approved |\n| 37.68 | Request timeout |\n\n3\\. Test and ensure that in case the PC goes into \"sleep\" mode or the application itself runs in the background, that the cloud connection is still established, or that it is re-established when the application is brought to the fore.\n\n4\\. Start the Sales Transaction and in the middle of it press the Cancel button on the POS terminal.\n\n5\\. Withdraw the card during the Sales Transaction.\n\n6\\. Invert the chip card into the terminal three times so that it is not read, after which the fallback should be activated and the card should be requested to be read with MSR - magnetic record and the user should ask for a signature where necessary.\n\n7\\. Generally look at the flow of messages and error handling of the marginal cases.\n\n8\\. The POS terminal should show in case of an authorized transaction, also that the transaction is authorized.\n\n9\\. The POS terminal should display in case of a rejected transaction, also that the transaction has been rejected.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"22972506","team":4779394,"collectionId":"330e0d92-b8a8-43fd-9599-b838fe143886","publishedId":"2sAXqwYzuo","public":true,"publicUrl":"https://documenter-api.postman.tech/view/22972506/2sAXqwYzuo","privateUrl":"https://go.postman.co/documentation/22972506-330e0d92-b8a8-43fd-9599-b838fe143886","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.10.1","publishDate":"2024-09-25T13:20:39.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"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/22a1b4eab3554fb12caae59c004130c264ffd45f214912f3e2b1624b9c3f2717","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"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/2sAXqwYzuo"}