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.
\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.
\nInitiate Transactions: Perform various types of financial operations (like sales and refunds) by sending transaction requests to the terminal.
\nRetrieve Transaction Results: Fetch transaction details such as approval status, customer/merchant receipts, and card information.
\nError Handling: Understand and handle terminal states like busy devices, unresponsive terminals, or invalid operations.
\nThis Postman collection is divided into the following two main endpoints:
\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.Key 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\nHow to Use This Collection
\nhttps://cloud.handpoint.comInitially 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.
\nStep 1: Set Up Your API Key
\nAll requests require an ApiKeyCloud header for authentication. Make sure you replace the placeholder value in the collection with your actual API key.
Step 2: Sending a Transaction
\nTo initiate a transaction:
\nGo to the POST /transactions request.
\nModify the request body with your specific operation, amount, currency, and terminal details.
\nSend the request.
You will receive a response containing a transactionResultId that you can use to fetch the transaction result later.
Step 3: Retrieving a Transaction Result
\nTo retrieve the result of a transaction:
\nGo to the GET /transaction-result/{transactionResultId} request.
\nReplace the placeholder in the URL with the actual transactionResultId received from your transaction initiation request.
Send the request to fetch the full transactionResult object.
Next is mapping from the transactionResult object to print customer receipt through the cash register with following data:
Acceptance tests:
\n1. Turn the terminal on and off, and confirm that it is properly connected to the internet and Payment application is running.
\n2. Test transactions with different deductible amounts that are predefined:
\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.
\n4. Start the Sales Transaction and in the middle of it press the Cancel button on the POS terminal.
\n5. Withdraw the card during the Sales Transaction.
\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.
\n7. Generally look at the flow of messages and error handling of the marginal cases.
\n8. The POS terminal should show in case of an authorized transaction, also that the transaction is authorized.
\n9. The POS terminal should display in case of a rejected transaction, also that the transaction has been rejected.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"22972506","collectionId":"330e0d92-b8a8-43fd-9599-b838fe143886","publishedId":"2sAXqwYzuo","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2024-09-25T13:20:39.000Z"},"item":[{"name":"Make a payment","id":"b0a9b150-3258-4e3f-980b-58957a850a9c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"ApiKeyCloud","value":"XXXXX-XXXXX-XXXXXX-XXXXX","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"operation\":\"sale\",\r\n \"amount\":\"20\",\r\n \"currency\":\"EUR\",\r\n \"terminal_type\":\"PAXA920PRO\",\r\n \"serial_number\":\"1850214318\",\r\n \"customerReference\":\"9093380\"\r\n \r\n}","options":{"raw":{"language":"json"}}},"url":"https://cloud.handpoint.com/transactions","description":"POST endpoint used to send a financial operation to the payment terminal. The transaction type to be executed (sale, refund etc.) is defined in the operation field of the request body.
Header: ApiKeyCloud Required
String Api key used to authenticate the merchant.
Request Body: Transaction Request Required
TransactionRequest Object containing the transaction request information.
\nResponse status codes details:
\nResponse body contain property \"transactionResultId\" which is mandatory for retreive transaction status!
\n","urlObject":{"protocol":"https","path":["transactions"],"host":["cloud","handpoint","com"],"query":[],"variable":[]}},"response":[{"id":"4a734f90-9602-4f32-9397-7e60b69673a0","name":"Make a payment","originalRequest":{"method":"POST","header":[{"key":"ApiKeyCloud","value":"XXXXX-XXXXX-XXXXX-XXXX-XXXX","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"operation\":\"sale\",\r\n \"amount\":\"20\",\r\n \"currency\":\"EUR\",\r\n \"terminal_type\":\"PAXA920PRO\",\r\n \"serial_number\":\"1850214318\",\r\n \"customerReference\":\"9093380\"\r\n \r\n}","options":{"raw":{"language":"json"}}},"url":"https://cloud.handpoint.com/transactions"},"status":"Accepted","code":202,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 25 Sep 2024 12:35:15 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"87"},{"key":"Connection","value":"keep-alive"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Origin, X-Requested-With, Content-Type, Accept, CRKeyCloud, ApiKeyCloud, AUTH_TOKEN, AUTH-TOKEN, User-Agent, user-agent"},{"key":"Access-Control-Allow-Credentials","value":"true"},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"},{"key":"X-Content-Type-Options","value":"nosniff"}],"cookie":[],"responseTime":null,"body":"{\n \"statusMessage\": \"Operation Accepted\",\n \"transactionResultId\": \"1850214318-1727267712853\"\n}"}],"_postman_id":"b0a9b150-3258-4e3f-980b-58957a850a9c"},{"name":"Retrieve Transaction","id":"4c0970fe-b3f1-4429-a982-860bbea6e7fd","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"ApiKeyCloud","value":"xxxx-xxxx-xxxx-xxxx","type":"text"}],"url":"https://cloud.handpoint.com/transaction-result/1850349779-1742827317538","description":"GET endpoint used to retrieve transaction results from the payment terminal. In case you do not provide a callbackURL and token in the transaction request, the terminal will post the transaction result to an Handpoint internal API which can be queried in order for your software to fetch the transaction result. If you are running a server to receive results and pass a callback URL and token as part of the transaction request you do not need to query this endpoint.
\nParameters:
\nReturns:
\n","urlObject":{"protocol":"https","path":["transaction-result","1850349779-1742827317538"],"host":["cloud","handpoint","com"],"query":[],"variable":[]}},"response":[{"id":"d1ff4a32-65d2-468e-8a76-b0662ef51445","name":"Retrieve Transaction","originalRequest":{"method":"GET","header":[{"key":"ApiKeyCloud","value":"XXXX-XXXX-XXXXX-XXXXX-XXXXX","type":"text"}],"url":"https://cloud.handpoint.com/transaction-result/1850214318-1726815935367"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 25 Sep 2024 12:51:42 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"1849"},{"key":"Connection","value":"keep-alive"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Origin, X-Requested-With, Content-Type, Accept, CRKeyCloud, ApiKeyCloud, AUTH_TOKEN, AUTH-TOKEN, User-Agent, user-agent"},{"key":"Access-Control-Allow-Credentials","value":"true"},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"},{"key":"X-Content-Type-Options","value":"nosniff"}],"cookie":[],"responseTime":null,"body":"{\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"I00294\",\n \"balance\": null,\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************5723\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"EUR\",\n \"customerReceipt\": \"https://receipts.handpoint.com/receipts/c06b5ac0-771e-11ef-bc98-cf80d94dea6d/customer.html\",\n \"customerReference\": \"9093380\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.5.3\",\n \"batteryCharging\": \"Pražnjenje\",\n \"batteryStatus\": \"58\",\n \"batterymV\": \"3764\",\n \"bluetoothName\": \"PAXA920PRO\",\n \"externalPower\": \"Nepoznato\",\n \"serialNumber\": \"1850214318\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"0330\",\n \"finStatus\": \"AUTHORISED\",\n \"iad\": \"1F42FF32A0000000001003027300000000400000000000000000000000000000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************5723\",\n \"merchantAddress\": \"Kaptol 5 10000 Zagreb\",\n \"merchantName\": \"Konoba Bracera\",\n \"merchantReceipt\": \"https://receipts.handpoint.com/receipts/c06b5ac0-771e-11ef-bc98-cf80d94dea6d/merchant.html\",\n \"metadata\": null,\n \"mid\": \"605000000024230\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 10,\n \"rrn\": \"426407000002\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Uspješno završena\",\n \"tenderType\": \"DEBIT\",\n \"tid\": \"50214318\",\n \"tipAmount\": 0,\n \"totalAmount\": 10,\n \"transactionID\": \"c06b5ac0-771e-11ef-bc98-cf80d94dea6d\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"c3bf5b04-372e-4f30-93d3-92831964c08a\",\n \"tsi\": \"0000\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"MOBILE_PASS_CODE\",\n \"efttimestamp\": 1726815941000,\n \"efttransactionID\": \"c06b5ac0-771e-11ef-bc98-cf80d94dea6d\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false\n}"}],"_postman_id":"4c0970fe-b3f1-4429-a982-860bbea6e7fd"},{"name":"Make a payment with a tip percentage ","id":"7279c05e-38c0-41c3-bff1-ec4776eb880b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"ApiKeyCloud","value":"XXXXX-XXXXX-XXXXXX-XXXXX","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"operation\":\"sale\",\r\n \"amount\":\"20\",\r\n \"currency\":\"EUR\",\r\n \"terminal_type\":\"PAXA920PRO\",\r\n \"serial_number\":\"1850214318\",\r\n \"customerReference\":\"9093380\",\r\n \"tipConfiguration\": {\r\n \"baseAmount\": \"2000\",\r\n \"tipPercentages\": [5,10,15,20,25],\r\n \"enterAmountEnabled\": true,\r\n \"skipEnabled\": false,\r\n \"footer\": \"Thank you!!! ;)\"\r\n }\r\n \r\n}","options":{"raw":{"language":"json"}}},"url":"https://cloud.handpoint.com/transactions","description":"At the time of sale, a tip menu will be shown to the cardholder with the predefined configuration. The tip configuration is optional and can only be used with the sale and saleAndTokenize operations.
\n","urlObject":{"protocol":"https","path":["transactions"],"host":["cloud","handpoint","com"],"query":[],"variable":[]}},"response":[{"id":"8432a6b7-553c-4605-8d0e-359bc1bf9ed9","name":"Make a payment","originalRequest":{"method":"POST","header":[{"key":"ApiKeyCloud","value":"XXXXX-XXXXXX-XXXXX-XXXXX-XXXXXX","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"operation\":\"sale\",\r\n \"amount\":\"20\",\r\n \"currency\":\"EUR\",\r\n \"terminal_type\":\"PAXA920PRO\",\r\n \"serial_number\":\"1850214318\",\r\n \"customerReference\":\"9093380\"\r\n \r\n}","options":{"raw":{"language":"json"}}},"url":"https://cloud.handpoint.com/transactions"},"status":"Accepted","code":202,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 25 Sep 2024 12:35:15 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"87"},{"key":"Connection","value":"keep-alive"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Origin, X-Requested-With, Content-Type, Accept, CRKeyCloud, ApiKeyCloud, AUTH_TOKEN, AUTH-TOKEN, User-Agent, user-agent"},{"key":"Access-Control-Allow-Credentials","value":"true"},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"},{"key":"X-Content-Type-Options","value":"nosniff"}],"cookie":[],"responseTime":null,"body":"{\n \"statusMessage\": \"Operation Accepted\",\n \"transactionResultId\": \"1850214318-1727267712853\"\n}"}],"_postman_id":"7279c05e-38c0-41c3-bff1-ec4776eb880b"},{"name":"Make a sale reversal payment","id":"289577ea-0302-4c47-b43c-2223fa28ba67","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"ApiKeyCloud","value":"XXXXX-XXXXX-XXXXXX-XXXXX","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"operation\":\"saleReversal\",\r\n \"amount\":\"20\",\r\n \"currency\":\"EUR\",\r\n \"terminal_type\":\"PAXA920PRO\",\r\n \"serial_number\":\"1850214318\",\r\n \"customerReference\":\"9093380\",\r\n \"originalTransactionId\": \"2bfde1fc-23b1-4c67-93d9-1d4a557f4d4f\"\r\n \r\n}","options":{"raw":{"language":"json"}}},"url":"https://cloud.handpoint.com/transactions","description":"originalTransactionId
Required to reverse or refund a transaction and for operations linked to a pre-authorisation. REQUIRED for operation saleReversal.
\n","urlObject":{"protocol":"https","path":["transactions"],"host":["cloud","handpoint","com"],"query":[],"variable":[]}},"response":[{"id":"8e70229a-aae0-43e5-be89-ddd07e11310c","name":"Make a sale reversal payment","originalRequest":{"method":"POST","header":[{"key":"ApiKeyCloud","value":"XXXXX-XXXXX-XXXXX-XXXX-XXXX","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"operation\":\"sale\",\r\n \"amount\":\"20\",\r\n \"currency\":\"EUR\",\r\n \"terminal_type\":\"PAXA920PRO\",\r\n \"serial_number\":\"1850214318\",\r\n \"customerReference\":\"9093380\",\r\n \"originalTransactionId\": \"2bfde1fc-23b1-4c67-93d9-1d4a557f4d4f\"\r\n \r\n}","options":{"raw":{"language":"json"}}},"url":"https://cloud.handpoint.com/transactions"},"status":"Accepted","code":202,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 25 Sep 2024 12:35:15 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"87"},{"key":"Connection","value":"keep-alive"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Allow-Headers","value":"Origin, X-Requested-With, Content-Type, Accept, CRKeyCloud, ApiKeyCloud, AUTH_TOKEN, AUTH-TOKEN, User-Agent, user-agent"},{"key":"Access-Control-Allow-Credentials","value":"true"},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"},{"key":"X-Content-Type-Options","value":"nosniff"}],"cookie":[],"responseTime":null,"body":"{\n \"statusMessage\": \"Operation Accepted\",\n \"transactionResultId\": \"1850214318-1727267712853\"\n}"}],"_postman_id":"289577ea-0302-4c47-b43c-2223fa28ba67"}]}