{ "info": { "name": "Handpoint Cloud API", "_postman_id": "handpoint-cloud-api-v2-2026", "description": "# Handpoint Cloud API — Integration Collection\n\nComplete request set for the Handpoint Cloud REST API. Covers card-present transactions, back-office operations, MOTO, and reporting.\n\n## Quick start\n\n1. **Import an environment** — use `Handpoint_Staging.postman_environment.json` (`.io`, no real funds) or `Handpoint_Production.postman_environment.json` (`.com`, live or DEMO merchant).\n2. **Set your credentials** — fill `api_key`, `serial_number`, `terminal_type`, and `currency` in the active environment.\n3. **Run `List Devices`** — confirms your API key is valid and shows assigned terminals.\n4. **Run `Sale — Polling`** — sends a transaction to the terminal. The `TXN_RESULT_ID` variable is auto-populated from the 202 response. Run `Poll Result` until `finStatus` resolves.\n\n## Variable chaining\n\nRequests that produce a result automatically set collection variables for downstream requests:\n\n| Set by | Variable | Used by |\n|---|---|---|\n| Sale, Refund, Pre-Auth | `TXN_RESULT_ID` | Poll Result |\n| Poll Result | `GUID` (`transactionID`) | Tip Adjustment, Reversal, Tokenize, Pre-Auth steps |\n| Poll Result | `TXN_REF_ID` (echoed) | Status by Reference |\n| Sale and Tokenize, Poll Result | `CARD_TOKEN` | MOTO Sale Back-Office |\n\n## Amount units — critical inconsistency\n\n| Endpoint | Amount format | Example |\n|---|---|---|\n| `POST /transactions` (all card-present) | **Minor units** as integer string | `\"1000\"` = €10.00 |\n| `POST /moto/sale`, `/moto/refund`, `/moto/reversal` | **Major units** as decimal string | `\"10.00\"` = €10.00 |\n| `POST /preauthorization/capture` — `capturedAmount` | **Major units** as decimal string | `\"10.00\"` = €10.00 |\n| `POST /preauthorization/increase` — `increaseAmount` | **Major units** as decimal string | `\"5.00\"` = €5.00 |\n| `POST /transactions/{id}/tip-adjustment` — `amount` | **Major units** as number | `5` = $5.00 |\n\n## Docs\n\nhttps://developer.handpoint.com", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "variable": [ { "key": "env", "value": "com", "description": "Domain suffix: 'com' = production (cloud.handpoint.com), 'io' = staging (cloud.handpoint.io). Change this one variable to switch environments." }, { "key": "api_key", "value": "YOUR_API_KEY", "description": "Merchant API key — format XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX. One key per merchant. Set in your environment file." }, { "key": "analytics_key", "value": "YOUR_ANALYTICS_KEY", "description": "Analytics/reporting API key. Required only for Transaction Feed requests. Set in your environment file." }, { "key": "serial_number", "value": "YOUR_SERIAL_NUMBER", "description": "PAX terminal serial number (8–10 digits, printed on device label). Set in your environment file." }, { "key": "terminal_type", "value": "PAXA920", "description": "PAX terminal model string. Common values: PAXA920, PAXA920PRO, PAXA3700, PAXA80. Must match the physical device." }, { "key": "currency", "value": "EUR", "description": "ISO 4217 three-letter currency code (e.g. EUR, USD, GBP, CAD). Must match the merchant account currency." }, { "key": "TXN_RESULT_ID", "value": "", "description": "Auto-populated from the 202 response. Format: {serialNumber}-{unixTimestampMs}. Pass to GET /transaction-result/{id} to poll." }, { "key": "GUID", "value": "", "description": "Auto-populated from the polled TransactionResult as `transactionID`. Use as `originalGuid` for reversals, refunds, tip adjustment, pre-auth steps." }, { "key": "TXN_REF_ID", "value": "", "description": "UUID v4 you generate per original request. Auto-generated by pre-request scripts. Used for GET /status recovery." }, { "key": "CARD_TOKEN", "value": "", "description": "Auto-populated from Sale and Tokenize or get card token. Use in MOTO back-office sale." } ], "item": [ { "name": "Authentication & Setup", "description": "Verify credentials and discover assigned terminals.", "item": [ { "name": "List Devices", "request": { "method": "GET", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}", "description": "Merchant API key." } ], "url": { "raw": "https://cloud.handpoint.{{env}}/devices", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "devices" ] }, "description": "Returns all PAX terminals assigned to this merchant API key.\n\nRun this first to confirm your credentials and discover `serial_number` and `terminal_type` values to use in transaction requests — both fields are required in `POST /transactions` and must exactly match what this endpoint returns.\n\n- HTTP 200 = valid key\n- HTTP 403 = wrong or missing `ApiKeyCloud` header\n- Terminal absent from list = error `1004` on transaction requests" }, "response": [ { "name": "200 OK — devices found", "status": "OK", "code": 200, "body": "[\n {\n \"merchant_id_alpha\": \"mer20260907120000001\",\n \"serial_number\": \"0821249003\",\n \"ssk\": \"62F634352BCFA358F7AEC1F8DB816E9E4FD11E737AD35BD2CFEBC666A88AC047\",\n \"terminal_type\": \"PAXA920\"\n },\n {\n \"merchant_id_alpha\": \"mer20260907120000001\",\n \"serial_number\": \"0821599465\",\n \"ssk\": \"62F634352BCFA358F7AEC1F8DB816E9E4FD11E737AD35BD2CFEBC666A88AC047\",\n \"terminal_type\": \"PAXA920\"\n }\n]", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 OK — no devices", "status": "OK", "code": 200, "body": "[]", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "403 Forbidden — invalid API key", "status": "Forbidden", "code": 403, "body": "{\n \"error\": {\n \"statusCode\": 403,\n \"name\": \"ForbiddenError\",\n \"message\": \"No valid key found in header\"\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "403 Forbidden — no ApiKeyCloud header", "status": "Forbidden", "code": 403, "body": "{\n \"error\": {\n \"statusCode\": 403,\n \"name\": \"ForbiddenError\",\n \"message\": \"ApiKeyCloud/CrKeyCloud header not found.\"\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] } ] }, { "name": "Sale", "description": "All sale operations: card-present (EMV), keyed entry (MOTO), and remote (back-office token).", "item": [ { "name": "Sale — Polling", "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "// Generate a fresh UUID v4 for transactionReference.", "// UUID v4 format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx", "// - position 13 (version digit) must be '4'", "// - position 17 (variant) must be 8, 9, a, or b", "// transactionReference is used for GET /status recovery — persist it to your DB before sending.", "var uuid = require('uuid');", "var uuidv4 = uuid.v4();", "console.log('transactionReference: ' + uuidv4);", "pm.collectionVariables.set('TXN_REF_ID', uuidv4);" ] } }, { "listen": "test", "script": { "type": "text/javascript", "exec": [ "if (pm.response.code === 202) {", " var body = pm.response.json();", " pm.collectionVariables.set('TXN_RESULT_ID', body.transactionResultId);", " console.log('TXN_RESULT_ID set to:', body.transactionResultId);", " console.log('Now run: Poll Result');", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}", "description": "Merchant API key." }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"sale\",\n \"amount\": \"1000\", // Minor units — 1000 = 10.00 | ISO 4217 exponent 2\n \"currency\": \"{{currency}}\", // ISO 4217: EUR, USD, GBP, CAD — wrong value → \"Agreement not found\"\n \"terminal_type\": \"{{terminal_type}}\",\n \"serial_number\": \"{{serial_number}}\",\n \"transactionReference\": \"{{TXN_REF_ID}}\", // UUID v4 — unique per request, store before sending\n\n // ── Optional ───────────────────────────────────────────────────────────────\n // \"callbackUrl\": \"https://your-server.com/webhook\", // POST result here instead of polling\n // \"token\": \"your-webhook-secret\", // auth header for callbackUrl\n // \"customerReference\": \"ORDER-12345\", // echoed in result, forwarded to acquirer (max 50 chars)\n // \"bypassOptions\": {\n // \"signatureBypass\": false, // skip signature screen\n // \"pinBypass\": false // show PIN but allow cardholder to skip; chip-enforced cards ignore this\n // },\n // \"metadata\": {\n // \"metadata1\": \"store-id-42\", // up to 5 free-text fields, max 250 chars each\n // \"metadata2\": \"server-id-7\",\n // \"metadata3\": \"\",\n // \"metadata4\": \"\",\n // \"metadata5\": \"\"\n // },\n // \"duplicate_check\": false, // true = SDK runs duplicate-transaction check before sending\n // \"billing\": { // AVS — must be enabled on acquirer agreement\n // \"zipCode\": \"10001\", // required within billing — cardholder billing ZIP\n // \"address\": \"123 Main St\" // optional — billing street address\n // },\n // \"merchantAuth\": [ // Multi-MID override — see Multi-MID Sale\n // { \"acquirer\": \"TSYS\", \"mid\": \"111111111113\", \"tid\": \"11111111\", \"mcc\": \"5974\" }\n // ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "Initiates a card-present sale on the terminal. The terminal prompts the cardholder to present their card.\n\n**Flow:** `POST /transactions` → 202 ACK with `transactionResultId` → poll `GET /transaction-result/{id}` every 4–6 seconds until 200 (done) or timeout. Use `callbackUrl` to receive the result via webhook instead of polling.\n\n**Amount units:** Minor units as an integer string — `\"1000\"` = €10.00 (ISO 4217 exponent 2 for EUR/USD/GBP/CAD). See the collection header for the full amount units reference.\n\n\n## Optional parameters\n\n| Parameter | Type | Description |\n|---|---|---|\n| `transactionReference` | string (UUID v4) | Idempotency key. Generate once per transaction, store **before** sending. Used for recovery via `GET /transactions/{ref}/status`. Never reuse on retries. |\n| `callbackUrl` | string (URL) | If set, the transaction result is POSTed to this URL instead of requiring polling. See **Sale — Callback URL** for the webhook payload format. |\n| `token` | string | Bearer token sent in the `Authorization` header of the `callbackUrl` POST. Required when `callbackUrl` is set and your webhook needs authentication. |\n| `customerReference` | string (max 50) | Free-text reference forwarded to the acquirer and echoed in the result. Use for order IDs, POS reference numbers, etc. |\n| `bypassOptions.signatureBypass` | boolean | Skip the signature capture step. Both `signatureBypass` and `pinBypass` must be provided together. |\n| `bypassOptions.pinBypass` | boolean | Show PIN screen but allow the cardholder to skip by pressing the green key. Records `verificationMethod: PIN_BYPASS`. Ignored for chip-enforced PIN cards. |\n| `metadata.metadata1`–`metadata5` | string (max 250 each) | Five free-text custom fields. Forwarded to the transaction feed unchanged. |\n| `duplicate_check` | boolean | When `true`, triggers the SDK's duplicate-transaction check flow before sending. |\n| `merchantAuth` | array of Credential | Override the merchant/MID/TID for this transaction. Used for Multi-MID deployments. See the **Multi-MID Sale** request. |\n| `billing.zipCode` | string | Cardholder billing ZIP / postal code. Include the `billing` object to enable AVS. Must be enabled on the merchant's acquirer agreement. |\n| `billing.address` | string | Cardholder billing street address (optional within `billing`). |\n\n\n## `finStatus` values\n\n| Value | Meaning | Next action |\n|---|---|---|\n| `AUTHORISED` | Issuer approved the transaction | Record as complete, print receipt |\n| `DECLINED` | Issuer declined the transaction | Prompt for another payment method |\n| `CANCELLED` | Cardholder or operator cancelled on the terminal | Retry or abandon |\n| `PARTIAL_APPROVAL` | Partial amount approved (prepaid cards) | Collect remainder by another method, or reverse with `originalGuid` |\n| `FAILED` | Technical failure — network, issuer timeout, card error | Do not charge; retry with a new `transactionReference` |\n| `UNDEFINED` | Result unclear — terminal completed but host did not receive confirmation | Call `GET /transactions/{transactionReference}/status` to recover |\n| `IN_PROGRESS` | (204 response) — terminal is still processing | Poll again in 4–6 seconds |" }, "response": [ { "name": "202 Accepted — operation started", "status": "Accepted", "code": 202, "body": "{\n \"statusMessage\": \"Operation Accepted\",\n \"transactionResultId\": \"0821599465-1788984051755\",\n \"transactionReference\": \"{{TXN_REF_ID}}\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "204 — Still Processing (poll again, empty body)", "status": "No Content", "code": 204, "body": "// 204 No Content — transaction is still processing.\n// Poll again in 4–6 seconds.", "_postman_previewlanguage": "text", "header": [], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: AUTHORISED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_IRT_00\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/300866b0-ac89-11f1-82a2-0545c651983f/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Not Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4103\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"AUTHORISED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/300866b0-ac89-11f1-82a2-0545c651983f/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 1,\n \"rrn\": \"0000909387899\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Aprobado o completado con éxito\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 1,\n \"transactionID\": \"300866b0-ac89-11f1-82a2-0545c651983f\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"b47584c2-9761-4fa4-9db2-3f091c0ee7a8\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788984081000,\n \"efttransactionID\": \"300866b0-ac89-11f1-82a2-0545c651983f\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788984051755\",\n \"polls\": 4\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: DECLINED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_IRT_05\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"1000\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/71839ba0-ac8e-11f1-b2f8-e3715f98f995/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4124\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"DECLINED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/71839ba0-ac8e-11f1-b2f8-e3715f98f995/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 3784,\n \"rrn\": \"0000909790476\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"La transacción falló\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 3784,\n \"transactionID\": \"71839ba0-ac8e-11f1-b2f8-e3715f98f995\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"1570d911-6ad0-46ad-959e-d07ecc4508c9\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"PIN\",\n \"efttimestamp\": 1788986337000,\n \"efttransactionID\": \"71839ba0-ac8e-11f1-b2f8-e3715f98f995\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986297378\",\n \"polls\": 7\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: CANCELLED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_CARD_READ_CANCELLED\",\n \"accountType\": \"\",\n \"aid\": \"\",\n \"applicationLabel\": \"\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"UNDEFINED\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"\",\n \"cardSchemeName\": \"\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4126\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"\",\n \"finStatus\": \"CANCELLED\",\n \"iad\": \"\",\n \"issuerResponseCode\": \"\",\n \"maskedCardNumber\": \"\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"UNKNOWN\",\n \"requestedAmount\": 5555,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Transaction canceled\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"NOT_SET\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 5555,\n \"transactionID\": \"\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"c559e3fe-1a21-4bc1-89a9-1f6fa98be365\",\n \"tsi\": \"\",\n \"tvr\": \"\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788986468787,\n \"efttransactionID\": \"\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986446641\",\n \"polls\": 2\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: PARTIAL_APPROVAL", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_IRT_00\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"0002\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/9f9d5da0-ac8e-11f1-b2f8-e3715f98f995/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4126\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 2657,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"PARTIAL_APPROVAL\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/9f9d5da0-ac8e-11f1-b2f8-e3715f98f995/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 3757,\n \"rrn\": \"0000909214185\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Aprobado o completado con éxito\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 1100,\n \"transactionID\": \"9f9d5da0-ac8e-11f1-b2f8-e3715f98f995\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"c5ecae86-352d-4433-b454-d7e1a8830c8e\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"PIN\",\n \"efttimestamp\": 1788986415000,\n \"efttransactionID\": \"9f9d5da0-ac8e-11f1-b2f8-e3715f98f995\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986386633\",\n \"polls\": 5\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: FAILED (issuer timeout)", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"ERROR_CONNECTING_TO_AUTHORIZATION_PROVIDER\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/b05a2fb0-ac8e-11f1-82a2-0545c651983f/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4126\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"ERROR_PROCESANDO_PETICIÓN\",\n \"expiryDateMMYY\": \"\",\n \"finStatus\": \"FAILED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/b05a2fb0-ac8e-11f1-82a2-0545c651983f/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 3768,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Error al conectar con el proveedor de autorización\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"NOT_SET\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 3768,\n \"transactionID\": \"b05a2fb0-ac8e-11f1-82a2-0545c651983f\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"fb4a38ff-f27f-4ca9-8976-98f9911f6772\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"PIN\",\n \"efttimestamp\": 1788986456034,\n \"efttransactionID\": \"b05a2fb0-ac8e-11f1-82a2-0545c651983f\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986413722\",\n \"polls\": 7\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: AUTHORISED (MSR — chip-fail fallback)", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_IRT_00\",\n \"accountType\": \"\",\n \"aid\": \"\",\n \"applicationLabel\": \"\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"MSR\",\n \"cardHolderName\": \"FELICIANA ANGELA VICTORIA\",\n \"cardLanguagePreference\": \"\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/ee716b60-ac8e-11f1-82a2-0545c651983f/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4126\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"AUTHORISED\",\n \"iad\": \"\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/ee716b60-ac8e-11f1-82a2-0545c651983f/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPFAILMAGSTRIPE\",\n \"requestedAmount\": 1500,\n \"rrn\": \"0000909702904\",\n \"signatureUrl\": \"https://receipts.handpoint.io/files/0821599465/1788986536613-ee716b60-ac8e-11f1-82a2-0545c651983f-signature.jpeg\",\n \"statusMessage\": \"Approved or completed successfully\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 1500,\n \"transactionID\": \"ee716b60-ac8e-11f1-82a2-0545c651983f\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"96f09198-ac66-4e2e-8f7e-e8a04e1a81f8\",\n \"tsi\": \"\",\n \"tvr\": \"\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"SIGNATURE\",\n \"efttimestamp\": 1788986547000,\n \"efttransactionID\": \"ee716b60-ac8e-11f1-82a2-0545c651983f\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986504480\",\n \"polls\": 9\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "403 Forbidden — invalid API key", "status": "Forbidden", "code": 403, "body": "{\n \"error\": {\n \"statusCode\": 403,\n \"name\": \"ForbiddenError\",\n \"message\": \"No valid key found in header\"\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "403 Forbidden — no ApiKeyCloud header", "status": "Forbidden", "code": 403, "body": "{\n \"error\": {\n \"statusCode\": 403,\n \"name\": \"ForbiddenError\",\n \"message\": \"ApiKeyCloud/CrKeyCloud header not found.\"\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "Sale — Callback URL", "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "var uuid = require('uuid');", "var uuidv4 = uuid.v4();", "console.log('transactionReference: ' + uuidv4);", "pm.collectionVariables.set('TXN_REF_ID', uuidv4);" ] } }, { "listen": "test", "script": { "type": "text/javascript", "exec": [ "if (pm.response.code === 202) {", " var body = pm.response.json();", " pm.collectionVariables.set('TXN_RESULT_ID', body.transactionResultId);", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"sale\",\n \"amount\": \"1000\", // minor units — 1000 = 10.00 | ISO 4217 exponent 2 for EUR/USD/GBP/CAD\n \"currency\": \"{{currency}}\", // ISO 4217 three-letter code: EUR, USD, GBP, CAD...\n \"terminal_type\": \"{{terminal_type}}\", // from GET /devices — e.g. PAXA920, PAXA920PRO\n \"serial_number\": \"{{serial_number}}\", // from GET /devices — 8-10 digit serial\n \"transactionReference\": \"{{TXN_REF_ID}}\", // UUID v4 — unique per sale — persist BEFORE sending\n \"callbackUrl\": \"https://your-server.com/handpoint/result\", // HTTPS only — CA-signed cert required (no self-signed certs)\n \"token\": \"my-secret-webhook-token\" // echoed as auth-token header in the callback POST — verify before processing\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "Sale with callback delivery. Handpoint POSTs the `TransactionResult` to your `callbackUrl` when the transaction completes — no polling needed.\n\n**Additional fields vs. polling:**\n\n| Field | Type | Notes |\n|---|---|---|\n| `callbackUrl` | string | HTTPS URL your server listens on. Must use a CA-signed TLS cert (Android 5–10 compatible — Let's Encrypt, DigiCert, etc.). Self-signed certs will silently fail. |\n| `token` | string | Arbitrary string echoed as the `auth-token` header in the callback POST. Use to authenticate incoming webhooks — verify this matches before processing the result. |\n\n**Callback delivery:** Your server must respond `2xx` to acknowledge. Handpoint may retry on non-2xx. Make your handler idempotent — deduplicate on `transactionReference`.\n\n**Fallback:** If the callback is not received (network outage, server restart), recover via `GET /transaction-result/{TXN_RESULT_ID}` or `GET /transactions/{TXN_REF_ID}/status`.\n\n**`merchantReceipt` / `customerReceipt`:** returns a URL (`https://receipts.handpoint.io/...`) when the receipt was successfully uploaded to cloud storage, or raw HTML if the upload failed. Integrators must handle both formats.\n\n**transactionReference:** transactionReference must be a UUID v4, unique per request. Do NOT reuse it on retries — send a new UUID each time you retry the same order." }, "response": [ { "name": "202 Accepted — sale", "originalRequest": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"sale\",\n \"amount\": \"1000\", // minor units — 1000 = 10.00 | ISO 4217 exponent 2 for EUR/USD/GBP/CAD\n \"currency\": \"{{currency}}\", // ISO 4217 three-letter code: EUR, USD, GBP, CAD...\n \"terminal_type\": \"{{terminal_type}}\", // from GET /devices — e.g. PAXA920, PAXA920PRO\n \"serial_number\": \"{{serial_number}}\", // from GET /devices — 8-10 digit serial\n \"transactionReference\": \"{{TXN_REF_ID}}\", // UUID v4 — unique per sale — persist BEFORE sending\n \"callbackUrl\": \"https://your-server.com/handpoint/result\", // HTTPS only — CA-signed cert required (no self-signed certs)\n \"token\": \"my-secret-webhook-token\" // echoed as auth-token header in the callback POST — verify before processing\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "Sale with callback delivery. Handpoint POSTs the `TransactionResult` to your `callbackUrl` when the transaction completes — no polling needed.\n\n**Additional fields vs. polling:**\n\n| Field | Type | Notes |\n|---|---|---|\n| `callbackUrl` | string | HTTPS URL your server listens on. Must use a CA-signed TLS cert (Android 5–10 compatible — Let's Encrypt, DigiCert, etc.). Self-signed certs will silently fail. |\n| `token` | string | Arbitrary string echoed as the `auth-token` header in the callback POST. Use to authenticate incoming webhooks — verify this matches before processing the result. |\n\n**Callback delivery:** Your server must respond `2xx` to acknowledge. Handpoint may retry on non-2xx. Make your handler idempotent — deduplicate on `transactionReference`.\n\n**Fallback:** If the callback is not received (network outage, server restart), recover via `GET /transaction-result/{TXN_RESULT_ID}` or `GET /transactions/{TXN_REF_ID}/status`." }, "status": "Accepted", "code": 202, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusMessage\": \"Operation Accepted\",\n \"transactionReference\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\"\n}" }, { "name": "200 — Poll: AUTHORISED (or use callbackUrl)", "originalRequest": { "method": "GET", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" } ], "url": { "raw": "https://cloud.handpoint.{{env}}/transaction-result/{{TXN_RESULT_ID}}", "protocol": "https", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transaction-result", "{{TXN_RESULT_ID}}" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/8032bb10-a967-11f1-ba75-8b4e94e8f7fc/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Not Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4133\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"AC\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"AUTHORISED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/8032bb10-a967-11f1-ba75-8b4e94e8f7fc/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 100,\n \"rrn\": \"0000905723064\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Aprobado o completado con éxito\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 100,\n \"transactionID\": \"8032bb10-a967-11f1-ba75-8b4e94e8f7fc\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"2c08e898-a1b6-4449-a8b7-bfa4f61d3c95\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788639757000,\n \"efttransactionID\": \"8032bb10-a967-11f1-ba75-8b4e94e8f7fc\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false\n}" }, { "name": "200 — Poll: DECLINED", "originalRequest": {}, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"1000\",\n \"authorisationCode\": \"\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/d3e4f5a0-a967-11f1-ba75-8b4e94e8f7fc/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Not Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4133\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"AC\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"DECLINED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/d3e4f5a0-a967-11f1-ba75-8b4e94e8f7fc/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 100,\n \"rrn\": \"0000905723064\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Declined\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 100,\n \"transactionID\": \"d3e4f5a0-a967-11f1-ba75-8b4e94e8f7fc\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"2c08e898-a1b6-4449-a8b7-bfa4f61d3c95\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788639757000,\n \"efttransactionID\": \"d3e4f5a0-a967-11f1-ba75-8b4e94e8f7fc\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false\n}" }, { "name": "200 — Poll: CANCELLED", "originalRequest": {}, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"\",\n \"authorisationCode\": \"\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/e5f6a7b1-a967-11f1-ba75-8b4e94e8f7fc/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Not Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4133\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"AC\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"CANCELLED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/e5f6a7b1-a967-11f1-ba75-8b4e94e8f7fc/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 100,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"CANCELLED\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 100,\n \"transactionID\": \"e5f6a7b1-a967-11f1-ba75-8b4e94e8f7fc\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"2c08e898-a1b6-4449-a8b7-bfa4f61d3c95\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788639757000,\n \"efttransactionID\": \"e5f6a7b1-a967-11f1-ba75-8b4e94e8f7fc\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false\n}" } ] }, { "name": "Sale with Tip Configuration", "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "var uuid = require('uuid');", "var uuidv4 = uuid.v4();", "console.log('transactionReference: ' + uuidv4);", "pm.collectionVariables.set('TXN_REF_ID', uuidv4);" ] } }, { "listen": "test", "script": { "type": "text/javascript", "exec": [ "if (pm.response.code === 202) {", " pm.collectionVariables.set('TXN_RESULT_ID', pm.response.json().transactionResultId);", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"sale\",\n \"amount\": \"1000\",\n \"currency\": \"{{currency}}\",\n \"terminal_type\": \"{{terminal_type}}\",\n \"serial_number\": \"{{serial_number}}\",\n \"transactionReference\": \"{{TXN_REF_ID}}\",\n \"tipConfiguration\": {\n \"baseAmount\": \"1000\", // string, minor units — base for percentage calculations (defaults to amount)\n \"headerName\": \"Add a tip?\", // optional — header text shown on tip screen (default: \"Tip\")\n \"tipPercentages\": [10, 15, 20], // integer[] — percentage buttons shown; required unless tipAmount set\n \"enterAmountEnabled\": true, // optional (default true) — show custom amount entry button\n \"skipEnabled\": true, // optional (default true) — show \"No tip\" / skip button\n \"footer\": \"Thank you!\" // optional — footer note shown on tip screen\n\n // Alternative: fixed tip, skip the selection screen entirely:\n // \"tipAmount\": \"100\" // string, minor units — bypasses tipPercentages\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "Initiates a card-present sale with an optional tipping screen shown to the cardholder.\n\n**`tipConfiguration` fields:**\n\n| Field | Type | Required | Default | Description |\n|---|---|---|---|---|\n| `baseAmount` | string (minor units) | No | Transaction `amount` | Base for percentage tip calculations. Use when the taxable amount differs from the total. |\n| `headerName` | string | No | `\"Tip\"` | Header shown on the tipping screen. |\n| `tipPercentages` | integer[] | Yes* | — | Percentage buttons (e.g. `[15, 18, 20]`). *Required unless `tipAmount` is set. |\n| `enterAmountEnabled` | boolean | No | `true` | Show a custom dollar amount entry button. |\n| `skipEnabled` | boolean | No | `true` | Show a 'No tip' / skip button. |\n| `footer` | string | No | `\"\"` | Footer note on the tipping screen. |\n| `tipAmount` | string (minor units) | No | — | **Fixed tip** — skips the percentage selection and applies this amount directly. Mutually exclusive with `tipPercentages`. |\n\n**Result fields:** `tipAmount` (number, minor units of tip charged), `totalAmount` (base + tip), `requestedAmount` (base only).\n\n**Tip Adjustment:** After the transaction completes, the tip can be changed with `POST /transactions/{guid}/tip-adjustment`. The `amount` field is the new tip value in **major units** (e.g. `5` = $5.00)." }, "response": [ { "name": "202 Accepted — operation started", "status": "Accepted", "code": 202, "body": "{\n \"statusMessage\": \"Operation Accepted\",\n \"transactionResultId\": \"0821599465-1788984051755\",\n \"transactionReference\": \"{{TXN_REF_ID}}\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "204 — Still Processing (poll again, empty body)", "status": "No Content", "code": 204, "body": "// 204 No Content — transaction is still processing.\n// Poll again in 4–6 seconds.", "_postman_previewlanguage": "text", "header": [], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: AUTHORISED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_IRT_00\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/79b75b80-ac8a-11f1-82a2-0545c651983f/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4121\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"AUTHORISED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/79b75b80-ac8a-11f1-82a2-0545c651983f/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 9,\n \"rrn\": \"0000909334725\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Aprobado o completado con éxito\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 1,\n \"totalAmount\": 10,\n \"transactionID\": \"79b75b80-ac8a-11f1-82a2-0545c651983f\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"c76199b5-8105-4d83-b9d2-f75ad75ef5cb\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788984634000,\n \"efttransactionID\": \"79b75b80-ac8a-11f1-82a2-0545c651983f\",\n \"tipPercentage\": 11.11,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788984608690\",\n \"polls\": 4\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: DECLINED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_IRT_05\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"1000\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/71839ba0-ac8e-11f1-b2f8-e3715f98f995/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4124\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"DECLINED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/71839ba0-ac8e-11f1-b2f8-e3715f98f995/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 3784,\n \"rrn\": \"0000909790476\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"La transacción falló\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 3784,\n \"transactionID\": \"71839ba0-ac8e-11f1-b2f8-e3715f98f995\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"1570d911-6ad0-46ad-959e-d07ecc4508c9\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"PIN\",\n \"efttimestamp\": 1788986337000,\n \"efttransactionID\": \"71839ba0-ac8e-11f1-b2f8-e3715f98f995\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986297378\",\n \"polls\": 7\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: CANCELLED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_CARD_READ_CANCELLED\",\n \"accountType\": \"\",\n \"aid\": \"\",\n \"applicationLabel\": \"\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"UNDEFINED\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"\",\n \"cardSchemeName\": \"\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4126\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"\",\n \"finStatus\": \"CANCELLED\",\n \"iad\": \"\",\n \"issuerResponseCode\": \"\",\n \"maskedCardNumber\": \"\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"UNKNOWN\",\n \"requestedAmount\": 5555,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Transaction canceled\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"NOT_SET\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 5555,\n \"transactionID\": \"\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"c559e3fe-1a21-4bc1-89a9-1f6fa98be365\",\n \"tsi\": \"\",\n \"tvr\": \"\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788986468787,\n \"efttransactionID\": \"\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986446641\",\n \"polls\": 2\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: PARTIAL_APPROVAL", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_IRT_00\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"0002\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/9f9d5da0-ac8e-11f1-b2f8-e3715f98f995/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4126\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 2657,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"PARTIAL_APPROVAL\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/9f9d5da0-ac8e-11f1-b2f8-e3715f98f995/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 3757,\n \"rrn\": \"0000909214185\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Aprobado o completado con éxito\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 1100,\n \"transactionID\": \"9f9d5da0-ac8e-11f1-b2f8-e3715f98f995\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"c5ecae86-352d-4433-b454-d7e1a8830c8e\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"PIN\",\n \"efttimestamp\": 1788986415000,\n \"efttransactionID\": \"9f9d5da0-ac8e-11f1-b2f8-e3715f98f995\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986386633\",\n \"polls\": 5\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: FAILED (issuer timeout)", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"ERROR_CONNECTING_TO_AUTHORIZATION_PROVIDER\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/b05a2fb0-ac8e-11f1-82a2-0545c651983f/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4126\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"ERROR_PROCESANDO_PETICIÓN\",\n \"expiryDateMMYY\": \"\",\n \"finStatus\": \"FAILED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/b05a2fb0-ac8e-11f1-82a2-0545c651983f/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 3768,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Error al conectar con el proveedor de autorización\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"NOT_SET\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 3768,\n \"transactionID\": \"b05a2fb0-ac8e-11f1-82a2-0545c651983f\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"fb4a38ff-f27f-4ca9-8976-98f9911f6772\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"PIN\",\n \"efttimestamp\": 1788986456034,\n \"efttransactionID\": \"b05a2fb0-ac8e-11f1-82a2-0545c651983f\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986413722\",\n \"polls\": 7\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "Tip Adjustment", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"amount\": 8\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions/{{GUID}}/tip-adjustment", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions", "{{GUID}}", "tip-adjustment" ] }, "description": "Adjusts (or sets) the tip amount on a completed transaction. Typically used in restaurant workflows where the tip is added after the card is returned.\n\n**`amount`** — the tip value in **major units** as a number (e.g. `5` = $5.00). This is the tip-only amount, not the total.\n\n**`{{GUID}}`** — the `transactionID` from the original sale poll result.\n\n**Constraints:** The batch must still be open. Tip adjustment is not possible after `POST /batch/close`.\n\n**`finStatus` in response:** Returns a simple JSON object — not the full `TransactionResult` schema. `statusMessage: \"tip adjusted\"` indicates success." }, "response": [ { "name": "200 — Tip adjusted", "status": "OK", "code": 200, "body": "{\n \"statusMessage\": \"tip adjusted\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "400 — Batch already closed", "status": "Bad Request", "code": 400, "body": "{\n \"error\": {\n \"statusCode\": 400,\n \"name\": \"BadRequestError\",\n \"message\": \"Batch already closed\"\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "404 — Transaction not found", "status": "Not Found", "code": 404, "body": "{\n \"error\": {\n \"statusCode\": 404,\n \"name\": \"NotFoundError\",\n \"message\": \"Transaction not found\"\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "Multi-MID Sale", "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "var uuid = require('uuid');", "var uuidv4 = uuid.v4();", "pm.collectionVariables.set('TXN_REF_ID', uuidv4);" ] } }, { "listen": "test", "script": { "type": "text/javascript", "exec": [ "if (pm.response.code === 202) {", " var body = pm.response.json();", " pm.collectionVariables.set('TXN_RESULT_ID', body.transactionResultId);", " console.log('TXN_RESULT_ID set to:', body.transactionResultId);", " console.log('Now run: Poll Result');", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}", "description": "Merchant API key." }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"sale\",\n \"amount\": \"1000\",\n \"currency\": \"{{currency}}\",\n \"terminal_type\": \"{{terminal_type}}\",\n \"serial_number\": \"{{serial_number}}\",\n \"transactionReference\": \"{{TXN_REF_ID}}\",\n \"merchantAuth\": [\n {\n \"externalId\": \"dr-smith\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "Routes a card-present sale to a specific sub-MID using `merchantAuth`.\n\n**`merchantAuth`** — pass an array with a single object containing `externalId`. The value must exactly match a sub-MID configured for the merchant in TMS. Omit `merchantAuth` entirely to route to the primary MID.\n\n**Important:** The `externalId` is **not** echoed in the transaction result. Store it alongside the `transactionID` in your own system at request time.\n\n**Invalid `externalId`** returns `finStatus: DECLINED` with `statusMessage: 'Invalid Merchant'` (`arc: '1000'`). The card must be fully presented before the decline is returned — this is a standard 202 + poll flow, not a 4xx error.\n\nSee [Multi-MID guide](/reference/multi-mid) for full routing rules and reconciliation guidance.\n\n**transactionReference:** transactionReference must be a UUID v4, unique per request. Do NOT reuse it on retries — send a new UUID each time you retry the same order." }, "response": [ { "name": "AUTHORISED — sub-MID sale", "originalRequest": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}", "description": "Merchant API key." }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"sale\",\n \"amount\": \"100\",\n \"currency\": \"USD\",\n \"terminal_type\": \"PAXA920\",\n \"serial_number\": \"0821599465\",\n \"transactionReference\": \"43ff824c-c44f-46b6-889d-c835ab5f8cd6\",\n \"merchantAuth\": [\n {\n \"externalId\": \"externalid1\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.io/transactions", "host": [ "cloud.handpoint.io" ], "path": [ "transactions" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/19cad8b0-a9cd-11f1-ba75-8b4e94e8f7fc/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Not Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4133\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"AC\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"AUTHORISED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/19cad8b0-a9cd-11f1-ba75-8b4e94e8f7fc/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 100,\n \"rrn\": \"0000906397715\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Approved or completed successfully\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 100,\n \"transactionID\": \"19cad8b0-a9cd-11f1-ba75-8b4e94e8f7fc\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"43ff824c-c44f-46b6-889d-c835ab5f8cd6\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788683394000,\n \"efttransactionID\": \"19cad8b0-a9cd-11f1-ba75-8b4e94e8f7fc\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false\n}" }, { "name": "DECLINED — invalid externalId", "originalRequest": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}", "description": "Merchant API key." }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"sale\",\n \"amount\": \"100\",\n \"currency\": \"USD\",\n \"terminal_type\": \"PAXA920\",\n \"serial_number\": \"0821599465\",\n \"transactionReference\": \"7243588b-da50-4621-80f0-51378b461596\",\n \"merchantAuth\": [\n {\n \"externalId\": \"INVALID\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.io/transactions", "host": [ "cloud.handpoint.io" ], "path": [ "transactions" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"1000\",\n \"authorisationCode\": \"\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/2d3872e0-a9cd-11f1-9580-bb48a7acbc38/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Not Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4133\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"AC\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"\",\n \"finStatus\": \"DECLINED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/2d3872e0-a9cd-11f1-9580-bb48a7acbc38/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 100,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Invalid Merchant\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"NOT_SET\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 100,\n \"transactionID\": \"2d3872e0-a9cd-11f1-9580-bb48a7acbc38\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"7243588b-da50-4621-80f0-51378b461596\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788683426000,\n \"efttransactionID\": \"2d3872e0-a9cd-11f1-9580-bb48a7acbc38\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false\n}" }, { "name": "200 — Poll: CANCELLED", "originalRequest": {}, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"\",\n \"authorisationCode\": \"\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/b1c2d3e1-a9cd-11f1-ba75-8b4e94e8f7fc/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Not Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4133\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"AC\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"CANCELLED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/b1c2d3e1-a9cd-11f1-ba75-8b4e94e8f7fc/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 100,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"CANCELLED\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 100,\n \"transactionID\": \"b1c2d3e1-a9cd-11f1-ba75-8b4e94e8f7fc\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"43ff824c-c44f-46b6-889d-c835ab5f8cd6\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788683394000,\n \"efttransactionID\": \"b1c2d3e1-a9cd-11f1-ba75-8b4e94e8f7fc\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false\n}" } ] }, { "name": "Sale and Tokenize Card", "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "var uuid = require('uuid');", "var uuidv4 = uuid.v4();", "console.log('transactionReference: ' + uuidv4);", "pm.collectionVariables.set('TXN_REF_ID', uuidv4);" ] } }, { "listen": "test", "script": { "type": "text/javascript", "exec": [ "if (pm.response.code === 202) {", " pm.collectionVariables.set('TXN_RESULT_ID', pm.response.json().transactionResultId);", " console.log('Poll Result — cardToken will be in the TransactionResult');", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"saleAndTokenizeCard\", // charges card AND stores a token for future remote charges\n \"amount\": \"1000\", // minor units — 1000 = 10.00 | ISO 4217 exponent 2 for EUR/USD/GBP/CAD\n \"currency\": \"{{currency}}\", // ISO 4217 three-letter code\n \"terminal_type\": \"{{terminal_type}}\", // from GET /devices\n \"serial_number\": \"{{serial_number}}\", // from GET /devices\n \"transactionReference\": \"{{TXN_REF_ID}}\" // UUID v4 — cardToken returned in result and saved to CARD_TOKEN variable\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "Runs a sale and simultaneously stores a card token in the merchant's configured token provider (ProCharge for EPI, Paysafe vault for PAYSAFE, etc.).\n\n**Requires:** tokenization enabled for the merchant by Handpoint (one-time setup).\n\n**Result:** `cardToken` field is populated in the `TransactionResult`. Store it securely — use it for future MOTO back-office charges without a terminal (`POST /moto/sale`).\n\n**Alternatively:** Use `operation: tokenizeCard` to tokenize without charging, or `GET /transactions/{transactionID}/token` for get card token of a past sale.\n\n**transactionReference:** transactionReference must be a UUID v4, unique per request. Do NOT reuse it on retries — send a new UUID each time you retry the same order." }, "response": [ { "name": "202 Accepted — operation started", "status": "Accepted", "code": 202, "body": "{\n \"statusMessage\": \"Operation Accepted\",\n \"transactionResultId\": \"0821599465-1788984051755\",\n \"transactionReference\": \"{{TXN_REF_ID}}\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "204 — Still Processing (poll again, empty body)", "status": "No Content", "code": 204, "body": "// 204 No Content — transaction is still processing.\n// Poll again in 4–6 seconds.", "_postman_previewlanguage": "text", "header": [], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: AUTHORISED (with cardToken)", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_IRT_00\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"K33f40000000000093\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/6a9107f0-ac8a-11f1-b2f8-e3715f98f995/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4121\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"AUTHORISED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/6a9107f0-ac8a-11f1-b2f8-e3715f98f995/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 5,\n \"rrn\": \"0000909572871\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Aprobado o completado con éxito\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 5,\n \"transactionID\": \"6a9107f0-ac8a-11f1-b2f8-e3715f98f995\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"b49d614e-8cbe-48f0-8763-25955fd5188f\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788984608000,\n \"efttransactionID\": \"6a9107f0-ac8a-11f1-b2f8-e3715f98f995\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788984574404\",\n \"polls\": 6\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: DECLINED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_IRT_05\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"1000\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/71839ba0-ac8e-11f1-b2f8-e3715f98f995/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4124\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"DECLINED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/71839ba0-ac8e-11f1-b2f8-e3715f98f995/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 3784,\n \"rrn\": \"0000909790476\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"La transacción falló\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 3784,\n \"transactionID\": \"71839ba0-ac8e-11f1-b2f8-e3715f98f995\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"1570d911-6ad0-46ad-959e-d07ecc4508c9\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"PIN\",\n \"efttimestamp\": 1788986337000,\n \"efttransactionID\": \"71839ba0-ac8e-11f1-b2f8-e3715f98f995\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986297378\",\n \"polls\": 7\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: CANCELLED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_CARD_READ_CANCELLED\",\n \"accountType\": \"\",\n \"aid\": \"\",\n \"applicationLabel\": \"\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"UNDEFINED\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"\",\n \"cardSchemeName\": \"\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4126\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"\",\n \"finStatus\": \"CANCELLED\",\n \"iad\": \"\",\n \"issuerResponseCode\": \"\",\n \"maskedCardNumber\": \"\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"UNKNOWN\",\n \"requestedAmount\": 5555,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Transaction canceled\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"NOT_SET\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 5555,\n \"transactionID\": \"\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"c559e3fe-1a21-4bc1-89a9-1f6fa98be365\",\n \"tsi\": \"\",\n \"tvr\": \"\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788986468787,\n \"efttransactionID\": \"\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986446641\",\n \"polls\": 2\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "Tokenize Card — No Charge", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}", "description": "Merchant API key." } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"tokenizeCard\",\n \"terminal_type\": \"{{terminal_type}}\",\n \"serial_number\": \"{{serial_number}}\",\n \"transactionReference\": \"{{TXN_REF_ID}}\"\n\n // Optional:\n // \"customerReference\": \"CUSTOMER-ID-123\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "Reads and tokenizes the cardholder's card without charging any amount. The token is returned in the poll result as `cardToken`.\n\n**Use cases:**\n- Store a card for future MOTO/back-office charges\n- Subscription enrollment — tokenize at sign-up, charge via `POST /moto/sale` later\n- Card-on-file update when a stored card expires\n\n**`cardToken` format:** ProCharge format — e.g. `K33f40000000000093`. This is not a UUID; it is a ProCharge/EPI vault token.\n\n**Poll result:** `finStatus=AUTHORISED`, `cardToken` populated. Also retrieve the token after the fact with `GET /transactions/{guid}/token`.\n\n**See also:** `saleAndTokenizeCard` — charges the card and tokenizes in one step." }, "response": [ { "name": "202 Accepted — operation started", "status": "Accepted", "code": 202, "body": "{\n \"statusMessage\": \"Operation Accepted\",\n \"transactionResultId\": \"0821599465-1788984051755\",\n \"transactionReference\": \"{{TXN_REF_ID}}\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "204 — Still Processing (poll again, empty body)", "status": "No Content", "code": 204, "body": "// 204 No Content — transaction is still processing.\n// Poll again in 4–6 seconds.", "_postman_previewlanguage": "text", "header": [], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: AUTHORISED (cardToken populated)", "status": "OK", "code": 200, "body": "{\n \"finStatus\": \"AUTHORISED\",\n \"type\": \"TOKENIZE_CARD\",\n \"cardToken\": \"K33f40000000000093\",\n \"maskedCardNumber\": \"************0936\",\n \"cardSchemeName\": \"Visa\",\n \"expiryDateMMYY\": \"1027\",\n \"cardEntryType\": \"ICC\",\n \"transactionID\": \"8fa7d000-ac8a-11f1-82a2-0545c651983f\",\n \"transactionOrigin\": \"CLOUD\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: CANCELLED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_CARD_READ_CANCELLED\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"\",\n \"batchNumber\": \"\",\n \"cardEntryType\": \"UNDEFINED\",\n \"cardSchemeName\": \"Visa\",\n \"currency\": \"USD\",\n \"errorMessage\": \"\",\n \"finStatus\": \"CANCELLED\",\n \"issuerResponseCode\": \"\",\n \"maskedCardNumber\": \"************0936\",\n \"paymentScenario\": \"UNKNOWN\",\n \"statusMessage\": \"Cancelled\",\n \"transactionOrigin\": \"CLOUD\",\n \"type\": \"TOKENIZE_CARD\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "Keyed Entry Sale", "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "// transactionReference is sent for on-terminal MOTO but is NOT echoed back in the result.", "// Known platform bug (CUS-837): the reference you send is ignored; the result contains", "// a system-generated reference. Do NOT use GET /status for recovery on moToSale —", "// use the transactionResultId from the 202 response instead.", "var uuid = require('uuid');", "var uuidv4 = uuid.v4();", "console.log('transactionReference: ' + uuidv4);", "pm.collectionVariables.set('TXN_REF_ID', uuidv4);" ] } }, { "listen": "test", "script": { "type": "text/javascript", "exec": [ "if (pm.response.code === 202) {", " pm.collectionVariables.set('TXN_RESULT_ID', pm.response.json().transactionResultId);", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"moToSale\",\n \"amount\": \"1000\", // minor units — 1000 = 10.00 GBP/EUR/USD\n \"currency\": \"{{currency}}\", // ISO 4217\n \"terminal_type\": \"{{terminal_type}}\", // from GET /devices\n \"serial_number\": \"{{serial_number}}\", // from GET /devices\n \"transactionReference\": \"{{TXN_REF_ID}}\" // UUID v4\n // optional AVS verification:\n //,\"billing\": {\n // \"zipCode\": \"10001\", // cardholder billing zip/postcode\n // \"address\": \"123 Main St\" // cardholder billing address\n //}\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "Triggers a manual card-entry screen on the PAX terminal. The operator reads card number, expiry, and CVV from the cardholder and types them on the terminal. Supported by EPI, EmerchantPay, and Paystrax.\n\n**Amount:** minor units as integer string — `\"1000\"` = €10.00.\n\n**⚠ Known bug (CUS-837):** The `transactionReference` you send is NOT echoed back in the result. The result contains a system-generated reference. Recovery via `GET /{txnRef}/status` will not work. **Use `transactionResultId` (from the 202 response) to poll for the result.**\n\n**Timeout:** If no operator enters card details, the poll loop exhausts (~120s → UNDEFINED). The terminal remains stuck in the active card-entry screen. Follow-up with `stopCurrentTransaction` to free it.\n\n**Result:** `cardEntryType: \"CNP\"` confirms keyed entry. Receipts are delivered as raw HTML strings (not URLs) — handle both formats.\n\n**transactionReference:** transactionReference must be a UUID v4, unique per request. Do NOT reuse it on retries — send a new UUID each time you retry the same order.\n\n**AVS (Address Verification):** Include `billing.zipCode` (required) and optionally `billing.address` to pass billing address to the acquirer for AVS. Must be enabled on the merchant agreement.\n\n**AVS result (Android SDK 7.1015.0+):** When a `billing` object is included and the acquirer performs AVS, the response contains an `addressVerification` object:\n\n```json\n\"addressVerification\": {\n \"resultCode\": \"FULL_MATCH\"\n}\n```\n\n| `resultCode` | Meaning |\n|---|---|\n| `FULL_MATCH` | Address + ZIP match |\n| `EXACT_MATCH` | Exact 9-digit ZIP + address match |\n| `ADDRESS_MATCH` | Address only matched |\n| `ZIP_MATCH` | ZIP only matched |\n| `ZIP9_MATCH` | 9-digit ZIP matched |\n| `NO_MATCH` | Neither address nor ZIP matched |\n| `UNSUPPORTED` | AVS not supported by acquirer |\n| `INTERNATIONAL` | Non-US card (international) |\n| `RETRY` | Retry requested |\n| `UNAVAILABLE` | AVS unavailable |\n| `UNKNOWN` | Unrecognized code |\n\n> **Note:** `addressVerification` appears in Android SDK 7.1015.0+ for MoTo operations via the direct gateway path. It does **not** appear in Cloud API `GET /transaction-result` responses." }, "response": [ { "name": "202 Accepted — operation started", "status": "Accepted", "code": 202, "body": "{\n \"statusMessage\": \"Operation Accepted\",\n \"transactionResultId\": \"0821599465-1788984051755\",\n \"transactionReference\": \"{{TXN_REF_ID}}\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "204 — Still Processing (poll again, empty body)", "status": "No Content", "code": 204, "body": "// 204 No Content — transaction is still processing.\n// Poll again in 4–6 seconds.", "_postman_previewlanguage": "text", "header": [], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: AUTHORISED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"Successful\",\n \"cardEntryType\": \"CNP\",\n \"cardSchemeName\": \"Visa\",\n \"currency\": \"USD\",\n \"finStatus\": \"AUTHORISED\",\n \"maskedCardNumber\": \"************0936\",\n \"requestedAmount\": 11,\n \"totalAmount\": 11,\n \"type\": \"MOTO_SALE\",\n \"transactionID\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"transactionOrigin\": \"CLOUD\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: DECLINED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"DECLINED\",\n \"cardEntryType\": \"CNP\",\n \"cardSchemeName\": \"Visa\",\n \"currency\": \"USD\",\n \"finStatus\": \"DECLINED\",\n \"maskedCardNumber\": \"************0936\",\n \"requestedAmount\": 11,\n \"totalAmount\": 11,\n \"type\": \"MOTO_SALE\",\n \"transactionID\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"transactionOrigin\": \"CLOUD\",\n \"statusMessage\": \"Declined\",\n \"arc\": \"\",\n \"authorisationCode\": \"\",\n \"batchNumber\": \"\",\n \"issuerResponseCode\": \"05\",\n \"errorMessage\": \"Do not honor\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: CANCELLED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"CANCELLED\",\n \"cardEntryType\": \"CNP\",\n \"cardSchemeName\": \"Visa\",\n \"currency\": \"USD\",\n \"finStatus\": \"CANCELLED\",\n \"maskedCardNumber\": \"************0936\",\n \"requestedAmount\": 11,\n \"totalAmount\": 11,\n \"type\": \"MOTO_SALE\",\n \"transactionID\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"transactionOrigin\": \"CLOUD\",\n \"statusMessage\": \"Cancelled\",\n \"arc\": \"\",\n \"authorisationCode\": \"\",\n \"batchNumber\": \"\",\n \"issuerResponseCode\": \"\",\n \"rrn\": \"\",\n \"errorMessage\": \"Transaction cancelled by cardholder\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "Remote Sale — Back-Office Token (EPI only)", "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "// Back-office remote sale: no terminal required. Charges a stored cardToken directly.", "// EPI only — EmerchantPay and Paystrax do not support back-office card-token remote sale.", "var uuid = require('uuid');", "var uuidv4 = uuid.v4();", "console.log('transactionReference: ' + uuidv4);", "pm.collectionVariables.set('TXN_REF_ID', uuidv4);" ] } }, { "listen": "test", "script": { "type": "text/javascript", "exec": [ "// Back-office sale returns HTTP 200 synchronously (no polling).", "// Success: check httpStatus === 200 (integer field in body).", "// The reversal GUID is in the 'guid' field (NOT 'transactionID').", "if (pm.response.code === 200) {", " var body = pm.response.json();", " if (body.guid) {", " pm.collectionVariables.set('GUID', body.guid);", " console.log('GUID for reversal set to:', body.guid);", " }", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"amount\": \"10.00\",\n \"currency\": \"{{currency}}\",\n \"cardToken\": \"{{card_token}}\",\n \"transactionReference\": \"{{TXN_REF_ID}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/moto/sale", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "moto", "sale" ] }, "description": "Charges a stored card token from your server — no terminal interaction, no cardholder present. EPI only.\n\n**`amount`:** **major units** as a decimal string — `\"10.00\"` = €10.00. NOT minor units. Do NOT send `\"1000\"` expecting €10.00.\n\n**`cardToken`:** obtained from a prior `saleAndTokenizeCard` or `GET /transactions/{id}/token`. Stored in the CARD_TOKEN collection variable.\n\n**`transactionReference`:** UUID v4. Include for idempotency.\n\n**Response:** HTTP 200 synchronous — no 202/polling. Check `httpStatus === 200` (integer field in body) for success. There is no `finStatus` field in this response.\n\n**Reversal GUID:** the `guid` field in the response — NOT `transactionID`. Use in `POST /reversal` with `originalGuid`.\n\n**Error `3107`:** Mandatory CVV is configured for this merchant's CNP — the token endpoint cannot supply CVV. Contact Handpoint to disable mandatory CVV.\n**Error `5252`:** Token provider (ProCharge) is temporarily down — the token is valid, retry later.\n\n**MOTO requirement:** Remote Sale uses the `/moto/sale` endpoint. **MOTO must be enabled for the merchant both in Handpoint and at the acquirer** before this endpoint will process successfully. Contact Handpoint support to enable MOTO.\n\n**transactionReference:** transactionReference must be a UUID v4, unique per request. Do NOT reuse it on retries — send a new UUID each time you retry the same order." }, "response": [ { "name": "200 — Sale authorised", "status": "OK", "code": 200, "body": "{\n \"@type\": \"sale\",\n \"httpStatus\": 200,\n \"acquirerTid\": \"ACQUIRER_TID\",\n \"amount\": \"0.01\",\n \"approvalCode\": \"123456\",\n \"batchNumber\": \"123\",\n \"cardTypeName\": \"Visa\",\n \"currency\": \"USD\",\n \"expiryDateMMYY\": \"1027\",\n \"guid\": \"922d9080-ac8a-11f1-b2f8-e3715f98f995\",\n \"issuerResponseCode\": \"00\",\n \"issuerResponseText\": \"Successful\",\n \"maskedCardNumber\": \"************0936\",\n \"retrievalReferenceNumber\": \"0000909475708\",\n \"serverDateTime\": \"20260909201058312\",\n \"terminalDateTime\": \"20260909201057000\",\n \"transactionReference\": \"ce3069f1-779c-469f-b79f-9baf66efbf8c\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — DECLINED", "status": "OK", "code": 200, "body": "{\n \"@type\": \"sale\",\n \"httpStatus\": 200,\n \"issuerResponseCode\": \"05\",\n \"issuerResponseText\": \"Do not honor\",\n \"maskedCardNumber\": \"************0936\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] } ] }, { "name": "Money Remittance", "description": "Money remittance sale operations (EMP-only — requires acquirer support).", "item": [ { "name": "Money Remittance Sale", "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "var uuid = require('uuid');", "var uuidv4 = uuid.v4();", "console.log('transactionReference: ' + uuidv4);", "pm.collectionVariables.set('TXN_REF_ID', uuidv4);" ] } }, { "listen": "test", "script": { "type": "text/javascript", "exec": [ "if (pm.response.code === 202) {", " var body = pm.response.json();", " pm.collectionVariables.set('TXN_RESULT_ID', body.transactionResultId);", " console.log('TXN_RESULT_ID set to:', body.transactionResultId);", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"sale\",\n \"amount\": \"10000\",\n \"currency\": \"USD\",\n \"terminal_type\": \"{{terminal_type}}\",\n \"serial_number\": \"{{serial_number}}\",\n \"moneyRemittanceOptions\": {\n \"fullName\": \"Peter Parker\",\n \"countryCode\": \"GBR\"\n },\n \"transactionReference\": \"{{TXN_REF_ID}}\"\n\n // Optional AVS:\n // \"billing\": { \"zipCode\": \"10001\", \"address\": \"123 Main St\" }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "protocol": "https", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "Processes a sale flagged as a money transfer (MCC 4829 / MCC 6540). Adds Mastercard MoneySend fields to the transaction for remittance network routing.\n\n**`moneyRemittanceOptions.fullName`:** recipient's full name, max 30 characters.\n\n**`moneyRemittanceOptions.countryCode`:** ISO 3166-1 alpha-3 (e.g. `\"USA\"`, `\"GBR\"`, `\"MEX\"`, `\"DEU\"`).\n\n**Supported operations:** Sale, Sale & Tokenize, Refund, Linked Refund — same endpoint (`POST /transactions`) with `moneyRemittanceOptions` added.\n\n**Acquirer:** EmerchantPay only. Verify support with your acquirer before enabling.\n\n**Flow:** identical to a standard sale — 202 Accepted → poll `transaction-result/{TXN_RESULT_ID}` until `finStatus` resolves.\n\n**transactionReference:** transactionReference must be a UUID v4, unique per request. Do NOT reuse it on retries — send a new UUID each time you retry the same order." }, "response": [ { "name": "202 Accepted — operation started", "status": "Accepted", "code": 202, "body": "{\n \"statusMessage\": \"Operation Accepted\",\n \"transactionResultId\": \"0821599465-1788984051755\",\n \"transactionReference\": \"{{TXN_REF_ID}}\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "204 — Still Processing (poll again, empty body)", "status": "No Content", "code": 204, "body": "// 204 No Content — transaction is still processing.\n// Poll again in 4–6 seconds.", "_postman_previewlanguage": "text", "header": [], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: AUTHORISED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_IRT_00\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/300866b0-ac89-11f1-82a2-0545c651983f/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Not Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4103\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"AUTHORISED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/300866b0-ac89-11f1-82a2-0545c651983f/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": {\n \"referenceNumber\": \"MR-2026-001\",\n \"senderName\": \"John Doe\",\n \"receiverName\": \"Jane Smith\"\n },\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 1,\n \"rrn\": \"0000909387899\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Aprobado o completado con éxito\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 1,\n \"transactionID\": \"300866b0-ac89-11f1-82a2-0545c651983f\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"b47584c2-9761-4fa4-9db2-3f091c0ee7a8\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788984081000,\n \"efttransactionID\": \"300866b0-ac89-11f1-82a2-0545c651983f\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788984051755\",\n \"polls\": 4\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: DECLINED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"DECLINED\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"1000\",\n \"authorisationCode\": \"\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/300866b0-ac89-11f1-82a2-0545c651983f/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Not Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4103\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"Do not honor\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"DECLINED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"05\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/300866b0-ac89-11f1-82a2-0545c651983f/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": {\n \"referenceNumber\": \"MR-2026-001\",\n \"senderName\": \"John Doe\",\n \"receiverName\": \"Jane Smith\"\n },\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 1,\n \"rrn\": \"0000909387899\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Declined\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 1,\n \"transactionID\": \"300866b0-ac89-11f1-82a2-0545c651983f\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"b47584c2-9761-4fa4-9db2-3f091c0ee7a8\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788984081000,\n \"efttransactionID\": \"300866b0-ac89-11f1-82a2-0545c651983f\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788984051755\",\n \"polls\": 4\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: CANCELLED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"CANCELLED\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"\",\n \"authorisationCode\": \"\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/300866b0-ac89-11f1-82a2-0545c651983f/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Not Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4103\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"Transaction cancelled by cardholder\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"CANCELLED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/300866b0-ac89-11f1-82a2-0545c651983f/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": {\n \"referenceNumber\": \"MR-2026-001\",\n \"senderName\": \"John Doe\",\n \"receiverName\": \"Jane Smith\"\n },\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 1,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Cancelled\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 1,\n \"transactionID\": \"300866b0-ac89-11f1-82a2-0545c651983f\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"b47584c2-9761-4fa4-9db2-3f091c0ee7a8\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788984081000,\n \"efttransactionID\": \"300866b0-ac89-11f1-82a2-0545c651983f\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788984051755\",\n \"polls\": 4\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ], "description": "**MasterCard only.** Standard sale with cross-border remittance metadata.\n\n| Field | Type | Description |\n|---|---|---|\n| `fullName` | string | Recipient full name |\n| `countryCode` | string | Recipient country — ISO 3166-1 alpha-3 (e.g. `\"GBR\"`, `\"USA\"`) |\n\n⚠️ An invalid `countryCode` may return `No device listening` instead of a validation error." } ] }, { "name": "Pre-Authorization", "description": "Pre-authorization lifecycle: create hold, increase/decrease, capture, and reversal.", "item": [ { "name": "Pre-Authorization Create", "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "var uuid = require('uuid');", "var uuidv4 = uuid.v4();", "console.log('transactionReference: ' + uuidv4);", "pm.collectionVariables.set('TXN_REF_ID', uuidv4);" ] } }, { "listen": "test", "script": { "type": "text/javascript", "exec": [ "if (pm.response.code === 202) {", " pm.collectionVariables.set('TXN_RESULT_ID', pm.response.json().transactionResultId);", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"preAuthorization\",\n \"amount\": \"1000\", // minor units — 1000 = 10.00 | hold placed for this amount | ISO 4217 exponent 2\n \"currency\": \"{{currency}}\", // ISO 4217 three-letter code\n \"terminal_type\": \"{{terminal_type}}\", // from GET /devices\n \"serial_number\": \"{{serial_number}}\", // from GET /devices\n \"transactionReference\": \"{{TXN_REF_ID}}\" // UUID v4 — unique per pre-auth — persist for recovery\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "Places an authorization hold on the cardholder's account without capturing funds. Common in hospitality (hotels, car rentals).\n\n**Supported acquirers:** EPI, EmerchantPay, Paystrax. Not supported on HiLite paths.\n\n**Flow:** Create → (optional) Increase/Decrease hold amount → Capture (charge the final amount) → or Reversal (release hold without charging).\n\n**Amount:** minor units as integer string. `\"1000\"` = €10.00. The hold is placed for this amount.\n\n**Poll result:** same as a sale. `transactionID` from the result is the GUID for all subsequent pre-auth steps.\n\n**transactionReference:** transactionReference must be a UUID v4, unique per request. Do NOT reuse it on retries — send a new UUID each time you retry the same order." }, "response": [ { "name": "202 Accepted — operation started", "status": "Accepted", "code": 202, "body": "{\n \"statusMessage\": \"Operation Accepted\",\n \"transactionResultId\": \"0821599465-1788984051755\",\n \"transactionReference\": \"{{TXN_REF_ID}}\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "204 — Still Processing (poll again, empty body)", "status": "No Content", "code": 204, "body": "// 204 No Content — transaction is still processing.\n// Poll again in 4–6 seconds.", "_postman_previewlanguage": "text", "header": [], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: AUTHORISED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_IRT_00\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/5d7b1340-ac89-11f1-b2f8-e3715f98f995/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4121\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"AUTHORISED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/5d7b1340-ac89-11f1-b2f8-e3715f98f995/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 7,\n \"rrn\": \"0000909263526\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Aprobado o completado con éxito\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 7,\n \"transactionID\": \"5d7b1340-ac89-11f1-b2f8-e3715f98f995\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"1ebffc69-5d2b-40b2-bbc0-637299ba5d10\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"PRE_AUTHORIZATION\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788984157000,\n \"efttransactionID\": \"5d7b1340-ac89-11f1-b2f8-e3715f98f995\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788984137401\",\n \"polls\": 3\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: DECLINED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_IRT_05\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"1000\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/71839ba0-ac8e-11f1-b2f8-e3715f98f995/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4124\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"DECLINED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/71839ba0-ac8e-11f1-b2f8-e3715f98f995/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 3784,\n \"rrn\": \"0000909790476\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"La transacción falló\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 3784,\n \"transactionID\": \"71839ba0-ac8e-11f1-b2f8-e3715f98f995\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"1570d911-6ad0-46ad-959e-d07ecc4508c9\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"PRE_AUTHORIZATION\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"PIN\",\n \"efttimestamp\": 1788986337000,\n \"efttransactionID\": \"71839ba0-ac8e-11f1-b2f8-e3715f98f995\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986297378\",\n \"polls\": 7\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: CANCELLED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_CARD_READ_CANCELLED\",\n \"accountType\": \"\",\n \"aid\": \"\",\n \"applicationLabel\": \"\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"UNDEFINED\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"\",\n \"cardSchemeName\": \"\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4126\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"\",\n \"finStatus\": \"CANCELLED\",\n \"iad\": \"\",\n \"issuerResponseCode\": \"\",\n \"maskedCardNumber\": \"\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"UNKNOWN\",\n \"requestedAmount\": 5555,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Transaction canceled\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"NOT_SET\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 5555,\n \"transactionID\": \"\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"c559e3fe-1a21-4bc1-89a9-1f6fa98be365\",\n \"tsi\": \"\",\n \"tvr\": \"\",\n \"type\": \"PRE_AUTHORIZATION\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788986468787,\n \"efttransactionID\": \"\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986446641\",\n \"polls\": 2\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: PARTIAL_APPROVAL", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_IRT_00\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"0002\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/9f9d5da0-ac8e-11f1-b2f8-e3715f98f995/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4126\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 2657,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"PARTIAL_APPROVAL\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/9f9d5da0-ac8e-11f1-b2f8-e3715f98f995/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 3757,\n \"rrn\": \"0000909214185\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Aprobado o completado con éxito\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 1100,\n \"transactionID\": \"9f9d5da0-ac8e-11f1-b2f8-e3715f98f995\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"c5ecae86-352d-4433-b454-d7e1a8830c8e\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"PRE_AUTHORIZATION\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"PIN\",\n \"efttimestamp\": 1788986415000,\n \"efttransactionID\": \"9f9d5da0-ac8e-11f1-b2f8-e3715f98f995\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986386633\",\n \"polls\": 5\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: FAILED (issuer timeout)", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"ERROR_CONNECTING_TO_AUTHORIZATION_PROVIDER\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/b05a2fb0-ac8e-11f1-82a2-0545c651983f/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4126\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"ERROR_PROCESANDO_PETICIÓN\",\n \"expiryDateMMYY\": \"\",\n \"finStatus\": \"FAILED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/b05a2fb0-ac8e-11f1-82a2-0545c651983f/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 3768,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Error al conectar con el proveedor de autorización\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"NOT_SET\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 3768,\n \"transactionID\": \"b05a2fb0-ac8e-11f1-82a2-0545c651983f\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"fb4a38ff-f27f-4ca9-8976-98f9911f6772\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"PRE_AUTHORIZATION\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"PIN\",\n \"efttimestamp\": 1788986456034,\n \"efttransactionID\": \"b05a2fb0-ac8e-11f1-82a2-0545c651983f\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986413722\",\n \"polls\": 7\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "Keyed Entry Pre-Authorization", "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "var uuid = require('uuid');", "var uuidv4 = uuid.v4();", "console.log('transactionReference: ' + uuidv4);", "pm.collectionVariables.set('TXN_REF_ID', uuidv4);" ] } }, { "listen": "test", "script": { "type": "text/javascript", "exec": [ "if (pm.response.code === 202) {", " var body = pm.response.json();", " pm.collectionVariables.set('TXN_RESULT_ID', body.transactionResultId);", " console.log('TXN_RESULT_ID set to:', body.transactionResultId);", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"moToPreAuthorization\",\n \"amount\": \"10000\", // minor units — hold amount (e.g. 10000 = £100.00)\n \"currency\": \"{{currency}}\", // ISO 4217\n \"terminal_type\": \"{{terminal_type}}\", // from GET /devices\n \"serial_number\": \"{{serial_number}}\", // from GET /devices\n \"transactionReference\": \"{{TXN_REF_ID}}\" // UUID v4\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "protocol": "https", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "Places a pre-authorization hold where the operator manually keys card details on the PAX terminal. No physical card or chip/tap is required — the operator types the card number, expiry, and CVV.\n\n**When to use:** card-on-file or MOTO scenarios where the cardholder provides card details verbally or by form, and a hold must be placed before the final amount is known.\n\n**Next steps:** use the back-office endpoints (no reader required) to increase/decrease the hold, capture the final amount, or release the hold:\n- **Pre-Auth Increase / Decrease** → adjust the hold\n- **Pre-Auth Capture** → charge the final amount (Increase/Decrease → Capture)\n- **Reversal** → release without charging\n\n**`originalTransactionId`** for subsequent steps: the `transactionID` / `efttransactionID` from this result (`GUID` collection variable, set by the Poll Result test script).\n\n**Flow:** 202 Accepted → poll `transaction-result/{TXN_RESULT_ID}` until `finStatus` resolves. The terminal presents the card-detail entry screen — an operator must be present.\n\n**transactionReference:** transactionReference must be a UUID v4, unique per request. Do NOT reuse it on retries — send a new UUID each time you retry the same order." }, "response": [ { "name": "202 Accepted — operation started", "status": "Accepted", "code": 202, "body": "{\n \"statusMessage\": \"Operation Accepted\",\n \"transactionResultId\": \"0821599465-1788984051755\",\n \"transactionReference\": \"{{TXN_REF_ID}}\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "204 — Still Processing (poll again, empty body)", "status": "No Content", "code": 204, "body": "// 204 No Content — transaction is still processing.\n// Poll again in 4–6 seconds.", "_postman_previewlanguage": "text", "header": [], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: AUTHORISED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"Successful\",\n \"accountType\": \"\",\n \"aid\": \"\",\n \"applicationLabel\": \"\",\n \"arc\": \"\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"CNP\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"\\n\\n \\n \\n
\\n \\n
\\n

Postman Test 3

\\n
\\n
\\n

Test Address 4 10111 London

\\n
\\n
\\n
\\n \\n 22:06\\n
\\n
\\n
\\n
\\n

Successful MOTO_PREAUTHORIZATION

\\n
\\n
\\n

USD 0.13

\\n
\\n
\\n
\\n \\n ********1113\\n
\\n
\\n \\n {$TID}\\n
\\n
\\n \\n ************0936\\n
\\n
\\n \\n MANUAL ENTRY\\n
\\n
\\n \\n NOT REQUIRED\\n
\\n
\\n \\n 123456\\n
\\n
\\n
\\n

GUID

\\n
\\n
\\n

f68c6890-ac89-11f1-b2f8-e3715f98f995

\\n
\\n
\\n
\\n

** CUSTOMER COPY **

\\n
\\n
\\n
\\n

EMV DETAILS

\\n
\\n
\\n \\n {$AID}\\n
\\n
\\n \\n {$TVR}\\n
\\n
\\n \\n {$IAD}\\n
\\n
\\n \\n {$TSI}\\n
\\n
\\n \\n {$ARC}\\n
\\n
\\n
\\n \\n \\n\\n\\n\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"\",\n \"applicationVersion\": \"\",\n \"batteryCharging\": \"\",\n \"batteryStatus\": \"\",\n \"batterymV\": \"\",\n \"bluetoothName\": \"\",\n \"externalPower\": \"\",\n \"serialNumber\": \"\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1232\",\n \"finStatus\": \"AUTHORISED\",\n \"iad\": \"\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"\",\n \"merchantName\": \"\",\n \"merchantReceipt\": \"\\n\\n \\n \\n
\\n \\n
\\n

Postman Test 3

\\n
\\n
\\n

Test Address 4 10111 London

\\n
\\n
\\n
\\n \\n 22:06\\n
\\n
\\n
\\n
\\n

Successful MOTO_PREAUTHORIZATION

\\n
\\n
\\n

USD 0.13

\\n
\\n
\\n
\\n \\n ********1113\\n
\\n
\\n \\n {$TID}\\n
\\n
\\n \\n ************0936\\n
\\n
\\n \\n MANUAL ENTRY\\n
\\n
\\n \\n NOT REQUIRED\\n
\\n
\\n \\n 123456\\n
\\n
\\n
\\n

GUID

\\n
\\n
\\n

f68c6890-ac89-11f1-b2f8-e3715f98f995

\\n
\\n
\\n
\\n

** MERCHANT COPY **

\\n
\\n
\\n
\\n

EMV DETAILS

\\n
\\n
\\n \\n {$AID}\\n
\\n
\\n \\n {$TVR}\\n
\\n
\\n \\n {$IAD}\\n
\\n
\\n \\n {$TSI}\\n
\\n
\\n \\n {$ARC}\\n
\\n
\\n
\\n \\n \\n\\n\\n\",\n \"metadata\": null,\n \"mid\": \"\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"MOTO\",\n \"requestedAmount\": 13,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Successful\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"NOT_SET\",\n \"tid\": \"\",\n \"tipAmount\": 0,\n \"totalAmount\": 13,\n \"transactionID\": \"f68c6890-ac89-11f1-b2f8-e3715f98f995\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"60c09dee-334e-446e-bc27-5abdbf82ed93\",\n \"tsi\": \"\",\n \"tvr\": \"\",\n \"type\": \"MOTO_PREAUTHORIZATION\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788984414000,\n \"efttransactionID\": \"f68c6890-ac89-11f1-b2f8-e3715f98f995\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788984377848\",\n \"polls\": 6\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: DECLINED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_IRT_05\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"1000\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"CNP\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/71839ba0-ac8e-11f1-b2f8-e3715f98f995/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4124\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"DECLINED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/71839ba0-ac8e-11f1-b2f8-e3715f98f995/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"MOTO\",\n \"requestedAmount\": 3784,\n \"rrn\": \"0000909790476\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"La transacción falló\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 3784,\n \"transactionID\": \"71839ba0-ac8e-11f1-b2f8-e3715f98f995\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"1570d911-6ad0-46ad-959e-d07ecc4508c9\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"MOTO_PREAUTHORIZATION\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"PIN\",\n \"efttimestamp\": 1788986337000,\n \"efttransactionID\": \"71839ba0-ac8e-11f1-b2f8-e3715f98f995\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986297378\",\n \"polls\": 7\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: CANCELLED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_CARD_READ_CANCELLED\",\n \"accountType\": \"\",\n \"aid\": \"\",\n \"applicationLabel\": \"\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"CNP\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"\",\n \"cardSchemeName\": \"\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4126\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"\",\n \"finStatus\": \"CANCELLED\",\n \"iad\": \"\",\n \"issuerResponseCode\": \"\",\n \"maskedCardNumber\": \"\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"MOTO\",\n \"requestedAmount\": 5555,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Transaction canceled\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"NOT_SET\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 5555,\n \"transactionID\": \"\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"c559e3fe-1a21-4bc1-89a9-1f6fa98be365\",\n \"tsi\": \"\",\n \"tvr\": \"\",\n \"type\": \"MOTO_PREAUTHORIZATION\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788986468787,\n \"efttransactionID\": \"\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986446641\",\n \"polls\": 2\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "Pre-Auth Increase / Decrease", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"originalGuid\": \"{{GUID}}\", // transactionID from Pre-Authorization Create poll result\n \"increaseAmount\": \"5.00\" // Major units decimal — amount to ADD to the hold\n\n // Optional:\n // \"subtract\": \"1\" // Set to \"1\" to DECREASE the hold instead of increase\n // \"tipAmount\": \"1.00\" // Add a tip to the hold amount (major units)\n // \"customerReference\": \"ORDER-123\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/preauthorization/increase", "protocol": "https", "host": [ "cloud", "handpoint", "{{env}}" ], "path": [ "preauthorization", "increase" ] }, "description": "Increases or decreases an existing pre-authorization hold. Common in hotel/hospitality flows where the hold amount changes before checkout.\n\n**Amount units:** Major units with decimal string — `\"5.00\"` = $5.00.\n\n**`increaseAmount`** — the **delta** to add to the current hold (not the new total).\n\n**To decrease:** Set `subtract: \"1\"` — the `increaseAmount` is then subtracted from the hold.\n\n**`holdAmount`** in the response — the new total hold after the increase/decrease.\n\n| Field | Required | Notes |\n|---|---|---|\n| `originalGuid` | Yes | `transactionID` from the pre-auth poll result |\n| `increaseAmount` | Yes | Delta in major units (decimal string) |\n| `subtract` | No | `\"1\"` to decrease instead of increase |\n| `tipAmount` | No | Add a tip component to the hold (major units) |\n| `customerReference` | No | Forwarded to acquirer |\n\n**Synchronous** — no polling. Response is the final result." }, "response": [ { "name": "200 — Hold increased", "status": "OK", "code": 200, "body": "{\n \"httpStatus\": 200,\n \"customFields\": {\n \"tenderType\": \"Credit\",\n \"issuerResponseCode\": \"00\"\n },\n \"acquirerTid\": \"ACQUIRER_TID\",\n \"actionCode\": \"0000\",\n \"agreementNumber\": \"111111111113\",\n \"approvalCode\": \"123456\",\n \"batchNumber\": \"123\",\n \"cardTypeName\": \"Visa\",\n \"currency\": \"USD\",\n \"expiryDateMMYY\": \"1027\",\n \"holdAmount\": \"9.07\",\n \"issuerResponseCode\": \"00\",\n \"issuerResponseText\": \"Successful\",\n \"maskedCardNumber\": \"************0936\",\n \"nonce\": \"1788984157195\",\n \"originalAmount\": \"0.07\",\n \"preAuthorizationGuid\": \"5d7b1340-ac89-11f1-b2f8-e3715f98f995\",\n \"serverDateTime\": \"20260909201257978\",\n \"terminalDateTime\": \"20260909201257881\",\n \"increaseAmount\": \"9.00\",\n \"preAuthorizationIncreaseGuid\": \"d98125a0-ac8a-11f1-b2f8-e3715f98f995\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "400 — Error 3211 (already captured/voided)", "status": "Bad Request", "code": 400, "body": "{\n \"error\": {\n \"statusCode\": 400,\n \"name\": \"BadRequestError\",\n \"message\": \"Original pre-auth is voided, not approved or already captured\",\n \"code\": \"3211\"\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "Pre-Auth Capture", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"originalGuid\": \"{{GUID}}\",\n \"capturedAmount\": \"45.00\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/preauthorization/capture", "protocol": "https", "host": [ "cloud", "handpoint", "{{env}}" ], "path": [ "preauthorization", "capture" ] }, "description": "Capture a previously authorised pre-authorization hold. **Synchronous back-office operation — no terminal required.** Returns HTTP 200 directly.\n\n| Field | Description |\n|-------|-------------|\n| `originalGuid` | `transactionID` from the Pre-Authorization Create result |\n| `capturedAmount` | Final capture amount in **major units** — e.g. `\"45.00\"` = $45.00. Must be ≤ the pre-auth hold amount. |" }, "response": [ { "name": "200 — Captured", "status": "OK", "code": 200, "body": "{\n \"httpStatus\": 200,\n \"customFields\": {\n \"tenderType\": \"Credit\",\n \"issuerResponseCode\": \"00\"\n },\n \"acquirerTid\": \"ACQUIRER_TID\",\n \"actionCode\": \"0000\",\n \"agreementNumber\": \"111111111113\",\n \"approvalCode\": \"123456\",\n \"batchNumber\": \"123\",\n \"cardTypeName\": \"Visa\",\n \"currency\": \"USD\",\n \"expiryDateMMYY\": \"1027\",\n \"holdAmount\": \"9.07\",\n \"issuerResponseCode\": \"00\",\n \"issuerResponseText\": \"Successful\",\n \"maskedCardNumber\": \"************0936\",\n \"nonce\": \"1788984157195\",\n \"originalAmount\": \"0.07\",\n \"preAuthorizationGuid\": \"5d7b1340-ac89-11f1-b2f8-e3715f98f995\",\n \"serverDateTime\": \"20260909201303022\",\n \"terminalDateTime\": \"20260909201303009\",\n \"capturedAmount\": \"9.00\",\n \"preAuthorizationCaptureGuid\": \"dc82cce0-ac8a-11f1-82a2-0545c651983f\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "400 — Error 3211 (already captured/voided)", "status": "Bad Request", "code": 400, "body": "{\n \"error\": {\n \"statusCode\": 400,\n \"name\": \"BadRequestError\",\n \"message\": \"Original pre-auth is voided, not approved or already captured\",\n \"code\": \"3211\"\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "Pre-Auth Reversal — Release Hold", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}", "description": "Merchant API key." } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"preAuthorizationReversal\",\n \"originalTransactionId\": \"{{GUID}}\", // transactionID from Pre-Authorization Create poll result\n \"terminal_type\": \"{{terminal_type}}\",\n \"serial_number\": \"{{serial_number}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "Releases a pre-authorization hold without capturing funds. Use when a reservation is cancelled or the cardholder checks out with a different payment method.\n\n**`originalTransactionId`** is the `transactionID` from the Pre-Authorization Create poll result.\n\n**Note:** This is the on-terminal reversal flow (goes through Pusher). For a back-office hold release without a terminal, use `POST /reversal` with the pre-auth `originalGuid`.\n\n**After this:** The hold on the card is released. No capture is possible." }, "response": [ { "name": "202 Accepted — operation started", "status": "Accepted", "code": 202, "body": "{\n \"statusMessage\": \"Operation Accepted\",\n \"transactionResultId\": \"0821599465-1788984051755\",\n \"transactionReference\": \"{{TXN_REF_ID}}\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "204 — Still Processing (poll again, empty body)", "status": "No Content", "code": 204, "body": "// 204 No Content — transaction is still processing.\n// Poll again in 4–6 seconds.", "_postman_previewlanguage": "text", "header": [], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: AUTHORISED (hold released)", "status": "OK", "code": 200, "body": "{\n \"finStatus\": \"AUTHORISED\",\n \"type\": \"PREAUTH_VOID\",\n \"maskedCardNumber\": \"************0936\",\n \"cardSchemeName\": \"Visa\",\n \"transactionOrigin\": \"CLOUD\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: CANCELLED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_CARD_READ_CANCELLED\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"\",\n \"batchNumber\": \"\",\n \"cardEntryType\": \"UNDEFINED\",\n \"cardSchemeName\": \"Visa\",\n \"currency\": \"USD\",\n \"errorMessage\": \"\",\n \"finStatus\": \"CANCELLED\",\n \"issuerResponseCode\": \"\",\n \"maskedCardNumber\": \"************0936\",\n \"paymentScenario\": \"UNKNOWN\",\n \"statusMessage\": \"Cancelled\",\n \"transactionOrigin\": \"CLOUD\",\n \"type\": \"PREAUTH_VOID\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] } ] }, { "name": "Refund", "description": "EMV card-present refunds (linked and unlinked), keyed entry (MOTO) refunds, and remote back-office refunds.", "item": [ { "name": "Refund — EMV Linked", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "if (pm.response.code === 202) {", " pm.collectionVariables.set('TXN_RESULT_ID', pm.response.json().transactionResultId);", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"refund\",\n \"amount\": \"1000\", // minor units — must not exceed original sale amount\n \"currency\": \"{{currency}}\", // ISO 4217 — must match original sale currency exactly\n \"terminal_type\": \"{{terminal_type}}\", // from GET /devices\n \"serial_number\": \"{{serial_number}}\", // from GET /devices\n \"originalTransactionId\": \"{{GUID}}\" // transactionID from the original sale result (GUID variable)\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "Card-present refund linked to a previous transaction. The card must be physically present at the terminal — the customer taps, inserts, or swipes.\n\n**`originalTransactionId`:** the `guid` / `efttransactionID` from the original sale. Set it from the `GUID` collection variable (auto-populated by the Poll Result test script).\n\n**When to use:** customer returns with their card and wants a refund against the original sale.\n\n**No-reader alternative:** use **Remote Refund** (Back-Office Operations) to process a linked refund without the card or terminal present.\n\n**Flow:** 202 Accepted → poll `transaction-result/{TXN_RESULT_ID}` until `finStatus` resolves." }, "response": [ { "name": "202 Accepted — operation started", "status": "Accepted", "code": 202, "body": "{\n \"statusMessage\": \"Operation Accepted\",\n \"transactionResultId\": \"0821599465-1788984051755\",\n \"transactionReference\": \"{{TXN_REF_ID}}\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "204 — Still Processing (poll again, empty body)", "status": "No Content", "code": 204, "body": "// 204 No Content — transaction is still processing.\n// Poll again in 4–6 seconds.", "_postman_previewlanguage": "text", "header": [], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: AUTHORISED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"AUTORIZADA\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/77cebad0-ac89-11f1-82a2-0545c651983f/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4121\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"AUTHORISED\",\n \"iad\": \"06011203800000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/77cebad0-ac89-11f1-82a2-0545c651983f/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"300866b0-ac89-11f1-82a2-0545c651983f\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 1,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"AUTORIZADA\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 1,\n \"transactionID\": \"77cebad0-ac89-11f1-82a2-0545c651983f\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"REFUND\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788984201000,\n \"efttransactionID\": \"77cebad0-ac89-11f1-82a2-0545c651983f\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788984181021\",\n \"polls\": 3\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: DECLINED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_IRT_05\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"1000\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/71839ba0-ac8e-11f1-b2f8-e3715f98f995/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4124\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"DECLINED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/71839ba0-ac8e-11f1-b2f8-e3715f98f995/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 3784,\n \"rrn\": \"0000909790476\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"La transacción falló\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 3784,\n \"transactionID\": \"71839ba0-ac8e-11f1-b2f8-e3715f98f995\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"1570d911-6ad0-46ad-959e-d07ecc4508c9\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"REFUND\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"PIN\",\n \"efttimestamp\": 1788986337000,\n \"efttransactionID\": \"71839ba0-ac8e-11f1-b2f8-e3715f98f995\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986297378\",\n \"polls\": 7\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: CANCELLED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_CARD_READ_CANCELLED\",\n \"accountType\": \"\",\n \"aid\": \"\",\n \"applicationLabel\": \"\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"UNDEFINED\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"\",\n \"cardSchemeName\": \"\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4126\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"\",\n \"finStatus\": \"CANCELLED\",\n \"iad\": \"\",\n \"issuerResponseCode\": \"\",\n \"maskedCardNumber\": \"\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"UNKNOWN\",\n \"requestedAmount\": 5555,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Transaction canceled\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"NOT_SET\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 5555,\n \"transactionID\": \"\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"c559e3fe-1a21-4bc1-89a9-1f6fa98be365\",\n \"tsi\": \"\",\n \"tvr\": \"\",\n \"type\": \"REFUND\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788986468787,\n \"efttransactionID\": \"\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986446641\",\n \"polls\": 2\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: PARTIAL_APPROVAL", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_IRT_00\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"0002\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/9f9d5da0-ac8e-11f1-b2f8-e3715f98f995/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4126\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 2657,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"PARTIAL_APPROVAL\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/9f9d5da0-ac8e-11f1-b2f8-e3715f98f995/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 3757,\n \"rrn\": \"0000909214185\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Aprobado o completado con éxito\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 1100,\n \"transactionID\": \"9f9d5da0-ac8e-11f1-b2f8-e3715f98f995\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"c5ecae86-352d-4433-b454-d7e1a8830c8e\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"REFUND\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"PIN\",\n \"efttimestamp\": 1788986415000,\n \"efttransactionID\": \"9f9d5da0-ac8e-11f1-b2f8-e3715f98f995\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986386633\",\n \"polls\": 5\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: FAILED (issuer timeout)", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"ERROR_CONNECTING_TO_AUTHORIZATION_PROVIDER\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/b05a2fb0-ac8e-11f1-82a2-0545c651983f/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4126\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"ERROR_PROCESANDO_PETICIÓN\",\n \"expiryDateMMYY\": \"\",\n \"finStatus\": \"FAILED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/b05a2fb0-ac8e-11f1-82a2-0545c651983f/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 3768,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Error al conectar con el proveedor de autorización\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"NOT_SET\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 3768,\n \"transactionID\": \"b05a2fb0-ac8e-11f1-82a2-0545c651983f\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"fb4a38ff-f27f-4ca9-8976-98f9911f6772\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"REFUND\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"PIN\",\n \"efttimestamp\": 1788986456034,\n \"efttransactionID\": \"b05a2fb0-ac8e-11f1-82a2-0545c651983f\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986413722\",\n \"polls\": 7\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "Refund — EMV Unlinked", "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "// Unlinked refund: no originalTransactionId — cardholder presents any card.", "// Requires acquirer enablement (not all acquirers allow unlinked refunds).", "var uuid = require('uuid');", "var uuidv4 = uuid.v4();", "console.log('transactionReference: ' + uuidv4);", "pm.collectionVariables.set('TXN_REF_ID', uuidv4);" ] } }, { "listen": "test", "script": { "type": "text/javascript", "exec": [ "if (pm.response.code === 202) {", " pm.collectionVariables.set('TXN_RESULT_ID', pm.response.json().transactionResultId);", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"refund\",\n \"amount\": \"1000\", // minor units — standalone refund not linked to a specific sale\n \"currency\": \"{{currency}}\", // ISO 4217 three-letter code\n \"terminal_type\": \"{{terminal_type}}\", // from GET /devices\n \"serial_number\": \"{{serial_number}}\", // from GET /devices\n \"transactionReference\": \"{{TXN_REF_ID}}\" // UUID v4 — unique reference for this refund\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "Card-present refund with no reference to a previous transaction. The card must be physically present at the terminal — the customer taps, inserts, or swipes.\n\n**When to use:** original transaction GUID is unknown, or the refund is from a different system and cannot be linked. The acquirer may apply different interchange rates for unlinked refunds.\n\n**Linked alternative:** if you have the original GUID, use **Refund — EMV Linked** for better dispute protection, or **Remote Refund** (Back-Office Operations) for a no-reader linked refund.\n\n**Flow:** 202 Accepted → poll `transaction-result/{TXN_RESULT_ID}` until `finStatus` resolves.\n\n**transactionReference:** transactionReference must be a UUID v4, unique per request. Do NOT reuse it on retries — send a new UUID each time you retry the same order." }, "response": [ { "name": "202 Accepted — operation started", "status": "Accepted", "code": 202, "body": "{\n \"statusMessage\": \"Operation Accepted\",\n \"transactionResultId\": \"0821599465-1788984051755\",\n \"transactionReference\": \"{{TXN_REF_ID}}\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "204 — Still Processing (poll again, empty body)", "status": "No Content", "code": 204, "body": "// 204 No Content — transaction is still processing.\n// Poll again in 4–6 seconds.", "_postman_previewlanguage": "text", "header": [], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: AUTHORISED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"AUTORIZADA\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/69650080-ac89-11f1-b2f8-e3715f98f995/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4121\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"AUTHORISED\",\n \"iad\": \"06011203800000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/69650080-ac89-11f1-b2f8-e3715f98f995/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 2,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"AUTORIZADA\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 2,\n \"transactionID\": \"69650080-ac89-11f1-b2f8-e3715f98f995\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"92a977e3-a840-478a-845a-9093d855ad60\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"REFUND\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788984177000,\n \"efttransactionID\": \"69650080-ac89-11f1-b2f8-e3715f98f995\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788984157759\",\n \"polls\": 2\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: DECLINED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_IRT_05\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"1000\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/71839ba0-ac8e-11f1-b2f8-e3715f98f995/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4124\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"DECLINED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/71839ba0-ac8e-11f1-b2f8-e3715f98f995/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 3784,\n \"rrn\": \"0000909790476\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"La transacción falló\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 3784,\n \"transactionID\": \"71839ba0-ac8e-11f1-b2f8-e3715f98f995\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"1570d911-6ad0-46ad-959e-d07ecc4508c9\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"REFUND\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"PIN\",\n \"efttimestamp\": 1788986337000,\n \"efttransactionID\": \"71839ba0-ac8e-11f1-b2f8-e3715f98f995\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986297378\",\n \"polls\": 7\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: CANCELLED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_CARD_READ_CANCELLED\",\n \"accountType\": \"\",\n \"aid\": \"\",\n \"applicationLabel\": \"\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"UNDEFINED\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"\",\n \"cardSchemeName\": \"\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4126\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"\",\n \"finStatus\": \"CANCELLED\",\n \"iad\": \"\",\n \"issuerResponseCode\": \"\",\n \"maskedCardNumber\": \"\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"UNKNOWN\",\n \"requestedAmount\": 5555,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Transaction canceled\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"NOT_SET\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 5555,\n \"transactionID\": \"\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"c559e3fe-1a21-4bc1-89a9-1f6fa98be365\",\n \"tsi\": \"\",\n \"tvr\": \"\",\n \"type\": \"REFUND\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788986468787,\n \"efttransactionID\": \"\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986446641\",\n \"polls\": 2\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: PARTIAL_APPROVAL", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_IRT_00\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"0002\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/9f9d5da0-ac8e-11f1-b2f8-e3715f98f995/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4126\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 2657,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"PARTIAL_APPROVAL\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/9f9d5da0-ac8e-11f1-b2f8-e3715f98f995/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 3757,\n \"rrn\": \"0000909214185\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Aprobado o completado con éxito\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 1100,\n \"transactionID\": \"9f9d5da0-ac8e-11f1-b2f8-e3715f98f995\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"c5ecae86-352d-4433-b454-d7e1a8830c8e\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"REFUND\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"PIN\",\n \"efttimestamp\": 1788986415000,\n \"efttransactionID\": \"9f9d5da0-ac8e-11f1-b2f8-e3715f98f995\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986386633\",\n \"polls\": 5\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: FAILED (issuer timeout)", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"ERROR_CONNECTING_TO_AUTHORIZATION_PROVIDER\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/b05a2fb0-ac8e-11f1-82a2-0545c651983f/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4126\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"ERROR_PROCESANDO_PETICIÓN\",\n \"expiryDateMMYY\": \"\",\n \"finStatus\": \"FAILED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/b05a2fb0-ac8e-11f1-82a2-0545c651983f/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 3768,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Error al conectar con el proveedor de autorización\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"NOT_SET\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 3768,\n \"transactionID\": \"b05a2fb0-ac8e-11f1-82a2-0545c651983f\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"fb4a38ff-f27f-4ca9-8976-98f9911f6772\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"REFUND\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"PIN\",\n \"efttimestamp\": 1788986456034,\n \"efttransactionID\": \"b05a2fb0-ac8e-11f1-82a2-0545c651983f\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986413722\",\n \"polls\": 7\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "Keyed Entry Refund — Unlinked", "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "var uuid = require('uuid');", "var uuidv4 = uuid.v4();", "console.log('transactionReference: ' + uuidv4);", "pm.collectionVariables.set('TXN_REF_ID', uuidv4);" ] } }, { "listen": "test", "script": { "type": "text/javascript", "exec": [ "if (pm.response.code === 202) {", " var body = pm.response.json();", " pm.collectionVariables.set('TXN_RESULT_ID', body.transactionResultId);", " console.log('TXN_RESULT_ID set to:', body.transactionResultId);", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"moToRefund\",\n \"amount\": \"1000\", // minor units — 1000 = 10.00 GBP/EUR/USD\n \"currency\": \"{{currency}}\", // ISO 4217\n \"terminal_type\": \"{{terminal_type}}\", // from GET /devices\n \"serial_number\": \"{{serial_number}}\", // from GET /devices\n \"transactionReference\": \"{{TXN_REF_ID}}\" // UUID v4 — required for UNDEFINED recovery\n // no originalTransactionId — unlinked refund\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "protocol": "https", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "Card-not-present refund where the operator manually keys card details on the PAX terminal, with no reference to a previous transaction.\n\n**When to use:** the original transaction GUID is unknown, or the refund is standalone.\n\n**`transactionReference`:** include a UUID v4 for UNDEFINED recovery — unlike linked refunds, there is no GUID to look up if the result is lost.\n\n**Linked alternative:** if you have the original GUID, use **Keyed Entry Refund — Linked** for better dispute protection.\n\n**EMV alternative:** if the cardholder is physically present with their card, use **Refund — EMV Unlinked** (chip/tap, no manual key entry).\n\n**Flow:** 202 Accepted → poll `transaction-result/{TXN_RESULT_ID}` until `finStatus` resolves. The terminal presents the card-detail entry screen — an operator must be present.\n\n**transactionReference:** transactionReference must be a UUID v4, unique per request. Do NOT reuse it on retries — send a new UUID each time you retry the same order.\n\n**`tokenize: true`** — Optional. Tokenizes the card during the keyed-entry operation, returning a `cardToken` in the result for future use." }, "response": [ { "name": "202 Accepted — operation started", "status": "Accepted", "code": 202, "body": "{\n \"statusMessage\": \"Operation Accepted\",\n \"transactionResultId\": \"0821599465-1788984051755\",\n \"transactionReference\": \"{{TXN_REF_ID}}\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "204 — Still Processing (poll again, empty body)", "status": "No Content", "code": 204, "body": "// 204 No Content — transaction is still processing.\n// Poll again in 4–6 seconds.", "_postman_previewlanguage": "text", "header": [], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: AUTHORISED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"Successful\",\n \"accountType\": \"\",\n \"aid\": \"\",\n \"applicationLabel\": \"\",\n \"arc\": \"\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"CNP\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"\\n\\n \\n \\n
\\n \\n
\\n

Postman Test 3

\\n
\\n
\\n

Test Address 4 10111 London

\\n
\\n
\\n
\\n \\n 22:14\\n
\\n
\\n
\\n
\\n

Successful MOTO_REFUND

\\n
\\n
\\n

USD 0.01

\\n
\\n
\\n
\\n \\n ********1113\\n
\\n
\\n \\n {$TID}\\n
\\n
\\n \\n ************0936\\n
\\n
\\n \\n MANUAL ENTRY\\n
\\n
\\n \\n NOT REQUIRED\\n
\\n
\\n \\n 123456\\n
\\n
\\n
\\n

GUID

\\n
\\n
\\n

134e82a0-ac8b-11f1-82a2-0545c651983f

\\n
\\n
\\n
\\n

** CUSTOMER COPY **

\\n
\\n
\\n
\\n

EMV DETAILS

\\n
\\n
\\n \\n {$AID}\\n
\\n
\\n \\n {$TVR}\\n
\\n
\\n \\n {$IAD}\\n
\\n
\\n \\n {$TSI}\\n
\\n
\\n \\n {$ARC}\\n
\\n
\\n
\\n \\n \\n\\n\\n\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"\",\n \"applicationVersion\": \"\",\n \"batteryCharging\": \"\",\n \"batteryStatus\": \"\",\n \"batterymV\": \"\",\n \"bluetoothName\": \"\",\n \"externalPower\": \"\",\n \"serialNumber\": \"\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1132\",\n \"finStatus\": \"AUTHORISED\",\n \"iad\": \"\",\n \"issuerResponseCode\": \"\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"\",\n \"merchantName\": \"\",\n \"merchantReceipt\": \"\\n\\n \\n \\n
\\n \\n
\\n

Postman Test 3

\\n
\\n
\\n

Test Address 4 10111 London

\\n
\\n
\\n
\\n \\n 22:14\\n
\\n
\\n
\\n
\\n

Successful MOTO_REFUND

\\n
\\n
\\n

USD 0.01

\\n
\\n
\\n
\\n \\n ********1113\\n
\\n
\\n \\n {$TID}\\n
\\n
\\n \\n ************0936\\n
\\n
\\n \\n MANUAL ENTRY\\n
\\n
\\n \\n NOT REQUIRED\\n
\\n
\\n \\n 123456\\n
\\n
\\n
\\n

GUID

\\n
\\n
\\n

134e82a0-ac8b-11f1-82a2-0545c651983f

\\n
\\n
\\n
\\n

** MERCHANT COPY **

\\n
\\n
\\n
\\n

EMV DETAILS

\\n
\\n
\\n \\n {$AID}\\n
\\n
\\n \\n {$TVR}\\n
\\n
\\n \\n {$IAD}\\n
\\n
\\n \\n {$TSI}\\n
\\n
\\n \\n {$ARC}\\n
\\n
\\n
\\n \\n \\n\\n\\n\",\n \"metadata\": null,\n \"mid\": \"\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"MOTO\",\n \"requestedAmount\": 1,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Successful\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"NOT_SET\",\n \"tid\": \"\",\n \"tipAmount\": 0,\n \"totalAmount\": 1,\n \"transactionID\": \"134e82a0-ac8b-11f1-82a2-0545c651983f\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"85e7ae2e-262f-42cc-9218-82f2904a3fa9\",\n \"tsi\": \"\",\n \"tvr\": \"\",\n \"type\": \"MOTO_REFUND\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788984892000,\n \"efttransactionID\": \"134e82a0-ac8b-11f1-82a2-0545c651983f\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: DECLINED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_IRT_05\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"1000\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"CNP\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/71839ba0-ac8e-11f1-b2f8-e3715f98f995/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4124\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"DECLINED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/71839ba0-ac8e-11f1-b2f8-e3715f98f995/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"MOTO\",\n \"requestedAmount\": 3784,\n \"rrn\": \"0000909790476\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"La transacción falló\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 3784,\n \"transactionID\": \"71839ba0-ac8e-11f1-b2f8-e3715f98f995\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"1570d911-6ad0-46ad-959e-d07ecc4508c9\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"MOTO_REFUND\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"PIN\",\n \"efttimestamp\": 1788986337000,\n \"efttransactionID\": \"71839ba0-ac8e-11f1-b2f8-e3715f98f995\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986297378\",\n \"polls\": 7\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: CANCELLED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_CARD_READ_CANCELLED\",\n \"accountType\": \"\",\n \"aid\": \"\",\n \"applicationLabel\": \"\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"CNP\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"\",\n \"cardSchemeName\": \"\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4126\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"\",\n \"finStatus\": \"CANCELLED\",\n \"iad\": \"\",\n \"issuerResponseCode\": \"\",\n \"maskedCardNumber\": \"\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"MOTO\",\n \"requestedAmount\": 5555,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Transaction canceled\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"NOT_SET\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 5555,\n \"transactionID\": \"\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"c559e3fe-1a21-4bc1-89a9-1f6fa98be365\",\n \"tsi\": \"\",\n \"tvr\": \"\",\n \"type\": \"MOTO_REFUND\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788986468787,\n \"efttransactionID\": \"\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986446641\",\n \"polls\": 2\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "Keyed Entry Refund — Linked", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "if (pm.response.code === 202) {", " var body = pm.response.json();", " pm.collectionVariables.set('TXN_RESULT_ID', body.transactionResultId);", " console.log('TXN_RESULT_ID set to:', body.transactionResultId);", "}" ] } } ], "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"amount\": \"{{amount}}\",\n \"currency\": \"{{currency}}\",\n \"originalGuid\": \"{{GUID}}\",\n \"transactionReference\": \"{{TXN_REF_ID}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/moto/refund", "protocol": "https", "host": [ "cloud", "handpoint", "{{env}}" ], "path": [ "moto", "refund" ] }, "description": "Card-not-present refund where the operator manually keys card details on the PAX terminal, linked to a previous transaction by its GUID.\n\n**`originalTransactionId`:** the `transactionID` / `efttransactionID` from the original sale. Set from the `GUID` collection variable.\n\n**Do not include `transactionReference`** — subsequent operations do not use it.\n\n**Unlinked alternative:** omit `originalTransactionId` and include `transactionReference` — see **Keyed Entry Refund — Unlinked**.\n\n**EMV alternative:** if the cardholder is physically present with their card, use **Refund — EMV Linked** (chip/tap, no manual key entry).\n\n**Flow:** 202 Accepted → poll `transaction-result/{TXN_RESULT_ID}` until `finStatus` resolves. The terminal presents the card-detail entry screen — an operator must be present.\n\n**transactionReference:** transactionReference must be a UUID v4, unique per request. Do NOT reuse it on retries — send a new UUID each time you retry the same order." }, "response": [ { "name": "200 — OK: AUTHORISED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"Successful\",\n \"accountType\": \"\",\n \"aid\": \"\",\n \"applicationLabel\": \"\",\n \"arc\": \"\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"CNP\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"\\n\\n \\n \\n
\\n \\n
\\n

Postman Test 3

\\n
\\n
\\n

Test Address 4 10111 London

\\n
\\n
\\n
\\n \\n 22:14\\n
\\n
\\n
\\n
\\n

Successful MOTO_REFUND

\\n
\\n
\\n

USD 0.01

\\n
\\n
\\n
\\n \\n ********1113\\n
\\n
\\n \\n {$TID}\\n
\\n
\\n \\n ************0936\\n
\\n
\\n \\n MANUAL ENTRY\\n
\\n
\\n \\n NOT REQUIRED\\n
\\n
\\n \\n 123456\\n
\\n
\\n
\\n

GUID

\\n
\\n
\\n

134e82a0-ac8b-11f1-82a2-0545c651983f

\\n
\\n
\\n
\\n

** CUSTOMER COPY **

\\n
\\n
\\n
\\n

EMV DETAILS

\\n
\\n
\\n \\n {$AID}\\n
\\n
\\n \\n {$TVR}\\n
\\n
\\n \\n {$IAD}\\n
\\n
\\n \\n {$TSI}\\n
\\n
\\n \\n {$ARC}\\n
\\n
\\n
\\n \\n \\n\\n\\n\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"\",\n \"applicationVersion\": \"\",\n \"batteryCharging\": \"\",\n \"batteryStatus\": \"\",\n \"batterymV\": \"\",\n \"bluetoothName\": \"\",\n \"externalPower\": \"\",\n \"serialNumber\": \"\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1132\",\n \"finStatus\": \"AUTHORISED\",\n \"iad\": \"\",\n \"issuerResponseCode\": \"\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"\",\n \"merchantName\": \"\",\n \"merchantReceipt\": \"\\n\\n \\n \\n
\\n \\n
\\n

Postman Test 3

\\n
\\n
\\n

Test Address 4 10111 London

\\n
\\n
\\n
\\n \\n 22:14\\n
\\n
\\n
\\n
\\n

Successful MOTO_REFUND

\\n
\\n
\\n

USD 0.01

\\n
\\n
\\n
\\n \\n ********1113\\n
\\n
\\n \\n {$TID}\\n
\\n
\\n \\n ************0936\\n
\\n
\\n \\n MANUAL ENTRY\\n
\\n
\\n \\n NOT REQUIRED\\n
\\n
\\n \\n 123456\\n
\\n
\\n
\\n

GUID

\\n
\\n
\\n

134e82a0-ac8b-11f1-82a2-0545c651983f

\\n
\\n
\\n
\\n

** MERCHANT COPY **

\\n
\\n
\\n
\\n

EMV DETAILS

\\n
\\n
\\n \\n {$AID}\\n
\\n
\\n \\n {$TVR}\\n
\\n
\\n \\n {$IAD}\\n
\\n
\\n \\n {$TSI}\\n
\\n
\\n \\n {$ARC}\\n
\\n
\\n
\\n \\n \\n\\n\\n\",\n \"metadata\": null,\n \"mid\": \"\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"MOTO\",\n \"requestedAmount\": 1,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Successful\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"NOT_SET\",\n \"tid\": \"\",\n \"tipAmount\": 0,\n \"totalAmount\": 1,\n \"transactionID\": \"134e82a0-ac8b-11f1-82a2-0545c651983f\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"85e7ae2e-262f-42cc-9218-82f2904a3fa9\",\n \"tsi\": \"\",\n \"tvr\": \"\",\n \"type\": \"MOTO_REFUND\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788984892000,\n \"efttransactionID\": \"134e82a0-ac8b-11f1-82a2-0545c651983f\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — DECLINED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"DECLINED\",\n \"accountType\": \"\",\n \"aid\": \"\",\n \"applicationLabel\": \"\",\n \"arc\": \"\",\n \"authorisationCode\": \"\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"CNP\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"\\n\\n \\n \\n
\\n \\n
\\n

Postman Test 3

\\n
\\n
\\n

Test Address 4 10111 London

\\n
\\n
\\n
\\n \\n 22:14\\n
\\n
\\n
\\n
\\n

Successful MOTO_REFUND

\\n
\\n
\\n

USD 0.01

\\n
\\n
\\n
\\n \\n ********1113\\n
\\n
\\n \\n {$TID}\\n
\\n
\\n \\n ************0936\\n
\\n
\\n \\n MANUAL ENTRY\\n
\\n
\\n \\n NOT REQUIRED\\n
\\n
\\n \\n 123456\\n
\\n
\\n
\\n

GUID

\\n
\\n
\\n

134e82a0-ac8b-11f1-82a2-0545c651983f

\\n
\\n
\\n
\\n

** CUSTOMER COPY **

\\n
\\n
\\n
\\n

EMV DETAILS

\\n
\\n
\\n \\n {$AID}\\n
\\n
\\n \\n {$TVR}\\n
\\n
\\n \\n {$IAD}\\n
\\n
\\n \\n {$TSI}\\n
\\n
\\n \\n {$ARC}\\n
\\n
\\n
\\n \\n \\n\\n\\n\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"\",\n \"applicationVersion\": \"\",\n \"batteryCharging\": \"\",\n \"batteryStatus\": \"\",\n \"batterymV\": \"\",\n \"bluetoothName\": \"\",\n \"externalPower\": \"\",\n \"serialNumber\": \"\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"Do not honor\",\n \"expiryDateMMYY\": \"1132\",\n \"finStatus\": \"DECLINED\",\n \"iad\": \"\",\n \"issuerResponseCode\": \"05\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"\",\n \"merchantName\": \"\",\n \"merchantReceipt\": \"\\n\\n \\n \\n
\\n \\n
\\n

Postman Test 3

\\n
\\n
\\n

Test Address 4 10111 London

\\n
\\n
\\n
\\n \\n 22:14\\n
\\n
\\n
\\n
\\n

Successful MOTO_REFUND

\\n
\\n
\\n

USD 0.01

\\n
\\n
\\n
\\n \\n ********1113\\n
\\n
\\n \\n {$TID}\\n
\\n
\\n \\n ************0936\\n
\\n
\\n \\n MANUAL ENTRY\\n
\\n
\\n \\n NOT REQUIRED\\n
\\n
\\n \\n 123456\\n
\\n
\\n
\\n

GUID

\\n
\\n
\\n

134e82a0-ac8b-11f1-82a2-0545c651983f

\\n
\\n
\\n
\\n

** MERCHANT COPY **

\\n
\\n
\\n
\\n

EMV DETAILS

\\n
\\n
\\n \\n {$AID}\\n
\\n
\\n \\n {$TVR}\\n
\\n
\\n \\n {$IAD}\\n
\\n
\\n \\n {$TSI}\\n
\\n
\\n \\n {$ARC}\\n
\\n
\\n
\\n \\n \\n\\n\\n\",\n \"metadata\": null,\n \"mid\": \"\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"MOTO\",\n \"requestedAmount\": 1,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Declined\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"NOT_SET\",\n \"tid\": \"\",\n \"tipAmount\": 0,\n \"totalAmount\": 1,\n \"transactionID\": \"134e82a0-ac8b-11f1-82a2-0545c651983f\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"85e7ae2e-262f-42cc-9218-82f2904a3fa9\",\n \"tsi\": \"\",\n \"tvr\": \"\",\n \"type\": \"MOTO_REFUND\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788984892000,\n \"efttransactionID\": \"134e82a0-ac8b-11f1-82a2-0545c651983f\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ], "description": "Linked refund against a prior Keyed Entry Sale. **Synchronous back-office operation — no terminal required.**\n\nPass the `transactionID` from the original Keyed Entry Sale as `originalGuid`. `amount` is in **major currency units** as a decimal string." }, { "name": "Remote Refund", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"amount\": \"10.00\",\n \"currency\": \"{{currency}}\",\n \"originalGuid\": \"{{GUID}}\",\n \"transactionReference\": \"{{TXN_REF_ID}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/moto/refund", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "moto", "refund" ] }, "description": "Processes a linked refund without requiring the card or terminal to be present. Refunds against an original transaction identified by its GUID.\n\n**Amount:** major units as a decimal string — `\"10.00\"` = €10.00. Different from the minor units used by `POST /transactions`.\n\n**`originalGuid`:** the `guid` / `efttransactionID` from the original sale result (set the `GUID` collection variable from Poll Result).\n\n**MOTO requirement:** Remote Refund uses the `/moto/refund` endpoint. **MOTO must be enabled for the merchant both in Handpoint and at the acquirer** before this endpoint will process successfully. Contact Handpoint support to enable MOTO.\n\n**Card-present alternative:** use **Refund — EMV Linked** (Card-Present) when the cardholder is present at the terminal.\n\n**Success:** HTTP 200 + `httpStatus: 200` + `issuerResponseCode: \"00\"`. No `finStatus`.\n\n**transactionReference:** transactionReference must be a UUID v4, unique per request. Do NOT reuse it on retries — send a new UUID each time you retry the same order." }, "response": [ { "name": "200 — Refund authorised", "status": "OK", "code": 200, "body": "{\n \"@type\": \"refund\",\n \"httpStatus\": 200,\n \"acquirerTid\": \"ACQUIRER_TID\",\n \"amount\": \"0.01\",\n \"approvalCode\": \"123456\",\n \"batchNumber\": \"123\",\n \"cardTypeName\": \"Visa\",\n \"currency\": \"USD\",\n \"expiryDateMMYY\": \"1027\",\n \"guid\": \"0247d650-ac8b-11f1-b2f8-e3715f98f995\",\n \"issuerResponseText\": \"Successful\",\n \"maskedCardNumber\": \"************0936\",\n \"serverDateTime\": \"20260909201406389\",\n \"terminalDateTime\": \"20260909201405000\",\n \"transactionReference\": \"ce3069f1-779c-469f-b79f-9baf66efbf8c\",\n \"originalGuid\": \"922d9080-ac8a-11f1-b2f8-e3715f98f995\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] } ] }, { "name": "Reversal", "description": "Void / reverse a transaction. Use the `originalGuid` from the transaction you want to reverse.", "item": [ { "name": "Sale Reversal — Back-Office", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"originalGuid\": \"{{GUID}}\", // transactionID from the original transaction result\n\n // Optional: for partial reversal only — omit for full reversal\n // \"amount\": \"5.00\", // Major units decimal string (e.g. \"5.00\" = $5.00)\n // \"currency\": \"{{currency}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/reversal", "protocol": "https", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "reversal" ] }, "description": "Reverses (voids) a transaction directly via the payment gateway — **no terminal required**. Use this for same-day voiding of a settled or authorized transaction.\n\n**When to use which reversal endpoint:**\n\n| Endpoint | Terminal required | Use case |\n|---|---|---|\n| `POST /reversal` (this request) | No | Back-office / same-day void, cardholder not present |\n| `POST /transactions` `operation=saleReversal` | Yes | Card-present reversal, cardholder returns to counter |\n\n**`originalGuid`** is the `transactionID` field from the transaction poll result or `GET /transactions/{ref}/status` response.\n\n**Partial reversal:** Include `amount` (major units decimal) to reverse only part of the transaction. Omit `amount` to reverse the full amount.\n\n**Response:** Returns a `reversalGuid` — store this as proof of the void." }, "response": [ { "name": "200 — Reversed", "status": "OK", "code": 200, "body": "{\n \"httpStatus\": 200,\n \"acquirerTid\": \"ACQUIRER_TID\",\n \"agreementNumber\": \"111111111113\",\n \"amount\": \"0.03\",\n \"approvalCode\": \"123456\",\n \"batchNumber\": \"123\",\n \"cardTypeName\": \"Visa\",\n \"currency\": \"USD\",\n \"customFields\": {\n \"entry\": [\n {\n \"key\": \"messageReasonCode\",\n \"value\": \"4000\"\n },\n {\n \"key\": \"tenderType\",\n \"value\": \"Credit\"\n },\n {\n \"key\": \"issuerResponseCode\",\n \"value\": \"00\"\n }\n ]\n },\n \"expiryDateMMYY\": \"1027\",\n \"f25\": \"4000\",\n \"issuerResponseCode\": \"00\",\n \"issuerResponseText\": \"Successful\",\n \"maskedCardNumber\": \"************0936\",\n \"serverDateTime\": \"20260909201030876\",\n \"terminalDateTime\": \"20260909201030769\",\n \"transactionReference\": \"f432cd56-1d2b-437d-8a63-9ebc28e953e2\",\n \"authorizationGuid\": \"429d7b30-ac89-11f1-82a2-0545c651983f\",\n \"originalGuid\": \"429d7b30-ac89-11f1-82a2-0545c651983f\",\n \"reversalGuid\": \"81d329c0-ac8a-11f1-b2f8-e3715f98f995\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "400 — Transaction already reversed", "status": "Bad Request", "code": 400, "body": "{\n \"error\": {\n \"statusCode\": 400,\n \"name\": \"BadRequestError\",\n \"message\": \"Transaction already reversed\",\n \"code\": \"3001\"\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "Refund Reversal — On Terminal", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}", "description": "Merchant API key." } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"refundReversal\",\n \"originalTransactionId\": \"{{GUID}}\", // transactionID of the refund to reverse\n \"terminal_type\": \"{{terminal_type}}\",\n \"serial_number\": \"{{serial_number}}\",\n \"cardPresent\": true // optional — true when cardholder is physically present\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "Reverses a previously completed refund on the terminal (card-present flow). Use when a refund was processed in error and the cardholder is present at the counter.\n\n**`originalTransactionId`** is the `transactionID` from the refund's poll result.\n\n**`cardPresent: true`** marks this as a card-present reversal — include when the cardholder is physically present.\n\nFor a back-office refund reversal without a terminal, use `POST /reversal` with the refund's `originalGuid`." }, "response": [ { "name": "202 Accepted — operation started", "status": "Accepted", "code": 202, "body": "{\n \"statusMessage\": \"Operation Accepted\",\n \"transactionResultId\": \"0821599465-1788984051755\",\n \"transactionReference\": \"{{TXN_REF_ID}}\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "204 — Still Processing (poll again, empty body)", "status": "No Content", "code": 204, "body": "// 204 No Content — transaction is still processing.\n// Poll again in 4–6 seconds.", "_postman_previewlanguage": "text", "header": [], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: AUTHORISED (refund reversed)", "status": "OK", "code": 200, "body": "{\n \"finStatus\": \"AUTHORISED\",\n \"type\": \"VOID_REFUND\",\n \"maskedCardNumber\": \"************0936\",\n \"cardSchemeName\": \"Visa\",\n \"transactionOrigin\": \"CLOUD\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: CANCELLED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_CARD_READ_CANCELLED\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"\",\n \"batchNumber\": \"\",\n \"cardEntryType\": \"UNDEFINED\",\n \"cardSchemeName\": \"Visa\",\n \"currency\": \"USD\",\n \"errorMessage\": \"\",\n \"finStatus\": \"CANCELLED\",\n \"issuerResponseCode\": \"\",\n \"maskedCardNumber\": \"************0936\",\n \"paymentScenario\": \"UNKNOWN\",\n \"statusMessage\": \"Cancelled\",\n \"transactionOrigin\": \"CLOUD\",\n \"type\": \"VOID_REFUND\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "MOTO Reversal — On Terminal", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}", "description": "Merchant API key." } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"moToReversal\",\n \"originalTransactionId\": \"{{GUID}}\", // transactionID of the original MOTO transaction\n \"terminal_type\": \"{{terminal_type}}\",\n \"serial_number\": \"{{serial_number}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "Reverses a previous MOTO (keyed-entry) transaction using on-terminal input. The cashier re-enters the card details on the terminal to complete the reversal.\n\n**`originalTransactionId`** is the `transactionID` from the original MOTO transaction's poll result.\n\nFor a back-office MOTO reversal without terminal input, use `POST /moto/reversal`." }, "response": [ { "name": "202 Accepted — operation started", "status": "Accepted", "code": 202, "body": "{\n \"statusMessage\": \"Operation Accepted\",\n \"transactionResultId\": \"0821599465-1788984051755\",\n \"transactionReference\": \"{{TXN_REF_ID}}\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "204 — Still Processing (poll again, empty body)", "status": "No Content", "code": 204, "body": "// 204 No Content — transaction is still processing.\n// Poll again in 4–6 seconds.", "_postman_previewlanguage": "text", "header": [], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: AUTHORISED", "status": "OK", "code": 200, "body": "{\n \"finStatus\": \"AUTHORISED\",\n \"type\": \"MOTO_REVERSAL\",\n \"cardEntryType\": \"CNP\",\n \"paymentScenario\": \"MOTO\",\n \"transactionOrigin\": \"CLOUD\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: CANCELLED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_CARD_READ_CANCELLED\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"\",\n \"batchNumber\": \"\",\n \"cardEntryType\": \"CNP\",\n \"cardSchemeName\": \"Visa\",\n \"currency\": \"USD\",\n \"errorMessage\": \"\",\n \"finStatus\": \"CANCELLED\",\n \"issuerResponseCode\": \"\",\n \"maskedCardNumber\": \"************0936\",\n \"paymentScenario\": \"UNKNOWN\",\n \"statusMessage\": \"Cancelled\",\n \"transactionOrigin\": \"CLOUD\",\n \"type\": \"MOTO_REVERSAL\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "Remote Reversal — Back-Office (EPI only)", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}", "description": "Merchant API key." } ], "body": { "mode": "raw", "raw": "{\n \"originalGuid\": \"{{GUID}}\", // transactionID of the transaction to reverse\n \"amount\": \"10.00\", // Major units decimal string\n \"currency\": \"{{currency}}\" // optional\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/moto/reversal", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "moto", "reversal" ] }, "description": "Reverses a transaction via the payment gateway without requiring a terminal. Synchronous — the response is the final result (no polling).\n\n**Amount units:** Major units with decimal string — `\"10.00\"` = $10.00. This is different from `POST /transactions` which uses minor units.\n\n**`originalGuid`** is the `transactionID` from the original transaction.\n\n**EPI only** — requires an EPI acquirer integration." }, "response": [ { "name": "200 — Reversed", "status": "OK", "code": 200, "body": "{\n \"@type\": \"reversal\",\n \"httpStatus\": 200,\n \"acquirerTid\": \"ACQUIRER_TID\",\n \"amount\": \"10.00\",\n \"approvalCode\": \"123456\",\n \"cardTypeName\": \"Visa\",\n \"currency\": \"USD\",\n \"maskedCardNumber\": \"************0936\",\n \"originalGuid\": \"300866b0-ac89-11f1-82a2-0545c651983f\",\n \"reversalGuid\": \"81d329c0-ac8a-11f1-b2f8-e3715f98f995\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] } ] }, { "name": "Transaction Results & Operations", "description": "Poll for transaction completion, perform post-transaction operations (tip adjustment, tokenization), and query transaction status.", "item": [ { "name": "Poll Result", "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "if (pm.response.code === 200) {", " var body = pm.response.json();", " // transactionID (also efttransactionID) — use as originalGuid for back-office ops", " pm.collectionVariables.set('GUID', body.efttransactionID || body.transactionID);", " // Echo transactionReference back for status recovery", " if (body.transactionReference) {", " pm.collectionVariables.set('TXN_REF_ID', body.transactionReference);", " }", " // Card token (if saleAndTokenizeCard was used)", " if (body.cardToken) {", " pm.collectionVariables.set('CARD_TOKEN', body.cardToken);", " console.log('CARD_TOKEN set:', body.cardToken);", " }", " console.log('finStatus:', body.finStatus);", " console.log('GUID (transactionID):', body.transactionID);", "} else if (pm.response.code === 204) {", " console.log('Still processing — wait 4s and poll again.');", "}" ] } } ], "request": { "method": "GET", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" } ], "url": { "raw": "https://cloud.handpoint.{{env}}/transaction-result/{{TXN_RESULT_ID}}", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transaction-result", "{{TXN_RESULT_ID}}" ] }, "description": "Polls for the result of any terminal operation. Call every 4–6 seconds until a `200` response is returned.\n\n**`{{TXN_RESULT_ID}}`** — the `transactionResultId` from the 202 ACK. Format: `{serialNumber}-{unixTimestampMs}` — e.g. `0821599465-1788984051755`.\n\n**Responses:**\n\n| HTTP Status | Meaning | Action |\n|---|---|---|\n| `204 No Content` | Transaction still in progress | Wait 4–6 seconds, poll again |\n| `200 OK` | Transaction complete | Read `finStatus` from body |\n\n\n## `finStatus` values\n\n| Value | Meaning | Next action |\n|---|---|---|\n| `AUTHORISED` | Issuer approved the transaction | Record as complete, print receipt |\n| `DECLINED` | Issuer declined the transaction | Prompt for another payment method |\n| `CANCELLED` | Cardholder or operator cancelled on the terminal | Retry or abandon |\n| `PARTIAL_APPROVAL` | Partial amount approved (prepaid cards) | Collect remainder by another method, or reverse with `originalGuid` |\n| `FAILED` | Technical failure — network, issuer timeout, card error | Do not charge; retry with a new `transactionReference` |\n| `UNDEFINED` | Result unclear — terminal completed but host did not receive confirmation | Call `GET /transactions/{transactionReference}/status` to recover |\n| `IN_PROGRESS` | (204 response) — terminal is still processing | Poll again in 4–6 seconds |\n\n**Timeout handling:** If you have polled for >90 seconds without a `200`, send `stopCurrentTransaction` to free the terminal, then call `GET /transactions/{transactionReference}/status` to recover the result.\n\n**Key result fields:**\n\n| Field | Type | Notes |\n|---|---|---|\n| `finStatus` | string | See table above |\n| `transactionID` | string (UUID) | Use as `originalGuid` for reversals, refunds, tip adjustment |\n| `transactionReference` | string (UUID) | The value you set in the request; use for `/status` recovery |\n| `totalAmount` | number | Minor units — includes tip |\n| `requestedAmount` | number | Minor units — base amount before tip |\n| `tipAmount` | number | Minor units — tip portion |\n| `cardToken` | string | Populated for `saleAndTokenizeCard` and `tokenizeCard` only |\n| `customerReceipt` | string | URL to hosted HTML receipt — display to customer |\n| `merchantReceipt` | string | URL to hosted HTML receipt — print for merchant copy |\n| `type` | string | Internal transaction type — see Card Entry Types in Test Cases |\n| `cardEntryType` | string | `ICC` (chip/contactless), `MSR` (swipe), `CNP` (keyed entry) |\n| `paymentScenario` | string | `CHIP`, `CHIPCONTACTLESS`, `CHIPFAILMAGSTRIPE`, `MOTO`, etc. |\n| `verificationMethod` | string | `PIN`, `SIGNATURE`, `PIN_SIGNATURE`, `NOT_REQUIRED`, `PIN_BYPASS` |\n| `_statusMessage` | string | Internal status code — e.g. `TEXT_IRT_00` (approved), `TEXT_IRT_05` (declined) |" }, "response": [ { "name": "204 — Still Processing (poll again, empty body)", "status": "No Content", "code": 204, "body": "// 204 No Content — transaction is still processing.\n// Poll again in 4–6 seconds.", "_postman_previewlanguage": "text", "header": [], "cookie": [], "originalRequest": {} }, { "name": "200 — AUTHORISED (sale)", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_IRT_00\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/300866b0-ac89-11f1-82a2-0545c651983f/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Not Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4103\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"AUTHORISED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/300866b0-ac89-11f1-82a2-0545c651983f/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 1,\n \"rrn\": \"0000909387899\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Aprobado o completado con éxito\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 1,\n \"transactionID\": \"300866b0-ac89-11f1-82a2-0545c651983f\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"b47584c2-9761-4fa4-9db2-3f091c0ee7a8\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788984081000,\n \"efttransactionID\": \"300866b0-ac89-11f1-82a2-0545c651983f\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788984051755\",\n \"polls\": 4\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — DECLINED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_IRT_05\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"1000\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/71839ba0-ac8e-11f1-b2f8-e3715f98f995/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4124\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"DECLINED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/71839ba0-ac8e-11f1-b2f8-e3715f98f995/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 3784,\n \"rrn\": \"0000909790476\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"La transacción falló\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 3784,\n \"transactionID\": \"71839ba0-ac8e-11f1-b2f8-e3715f98f995\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"1570d911-6ad0-46ad-959e-d07ecc4508c9\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"PIN\",\n \"efttimestamp\": 1788986337000,\n \"efttransactionID\": \"71839ba0-ac8e-11f1-b2f8-e3715f98f995\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986297378\",\n \"polls\": 7\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — CANCELLED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_CARD_READ_CANCELLED\",\n \"accountType\": \"\",\n \"aid\": \"\",\n \"applicationLabel\": \"\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"UNDEFINED\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"\",\n \"cardSchemeName\": \"\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4126\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"\",\n \"finStatus\": \"CANCELLED\",\n \"iad\": \"\",\n \"issuerResponseCode\": \"\",\n \"maskedCardNumber\": \"\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"UNKNOWN\",\n \"requestedAmount\": 5555,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Transaction canceled\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"NOT_SET\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 5555,\n \"transactionID\": \"\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"c559e3fe-1a21-4bc1-89a9-1f6fa98be365\",\n \"tsi\": \"\",\n \"tvr\": \"\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788986468787,\n \"efttransactionID\": \"\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986446641\",\n \"polls\": 2\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — PARTIAL_APPROVAL", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_IRT_00\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"0002\",\n \"authorisationCode\": \"123456\",\n \"balance\": null,\n \"batchNumber\": \"123\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"Visa\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"************0936\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/9f9d5da0-ac8e-11f1-b2f8-e3715f98f995/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4126\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 2657,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"1027\",\n \"finStatus\": \"PARTIAL_APPROVAL\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"************0936\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/9f9d5da0-ac8e-11f1-b2f8-e3715f98f995/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 3757,\n \"rrn\": \"0000909214185\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Aprobado o completado con éxito\",\n \"surcharge\": {\n \"amount\": 0,\n \"applied\": false,\n \"reason\": \"\"\n },\n \"taxAmount\": null,\n \"tenderType\": \"CREDIT\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 1100,\n \"transactionID\": \"9f9d5da0-ac8e-11f1-b2f8-e3715f98f995\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"c5ecae86-352d-4433-b454-d7e1a8830c8e\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"PIN\",\n \"efttimestamp\": 1788986415000,\n \"efttransactionID\": \"9f9d5da0-ac8e-11f1-b2f8-e3715f98f995\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986386633\",\n \"polls\": 5\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — FAILED (issuer timeout)", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"ERROR_CONNECTING_TO_AUTHORIZATION_PROVIDER\",\n \"accountType\": \"\",\n \"aid\": \"A0000000031010\",\n \"applicationLabel\": \"VISA CLASICA\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"ICC\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"es_ES\",\n \"cardSchemeName\": \"\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"https://receipts.handpoint.io/receipts/b05a2fb0-ac8e-11f1-82a2-0545c651983f/customer.html\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4126\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"ERROR_PROCESANDO_PETICIÓN\",\n \"expiryDateMMYY\": \"\",\n \"finStatus\": \"FAILED\",\n \"iad\": \"06011203A00000\",\n \"issuerResponseCode\": \"00\",\n \"maskedCardNumber\": \"\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"https://receipts.handpoint.io/receipts/b05a2fb0-ac8e-11f1-82a2-0545c651983f/merchant.html\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"requestedAmount\": 3768,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Error al conectar con el proveedor de autorización\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"NOT_SET\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 3768,\n \"transactionID\": \"b05a2fb0-ac8e-11f1-82a2-0545c651983f\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"fb4a38ff-f27f-4ca9-8976-98f9911f6772\",\n \"tsi\": \"\",\n \"tvr\": \"0000000000\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"PIN\",\n \"efttimestamp\": 1788986456034,\n \"efttransactionID\": \"b05a2fb0-ac8e-11f1-82a2-0545c651983f\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986413722\",\n \"polls\": 7\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "Get Card Token", "request": { "method": "GET", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" } ], "url": { "raw": "https://cloud.handpoint.{{env}}/transactions/{{GUID}}/token", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions", "{{GUID}}", "token" ] }, "description": "Retrieves the card token for a completed `saleAndTokenizeCard` or `tokenizeCard` transaction.\n\n**When to use:** If the poll result for a tokenization transaction was lost (network drop, app restart), call this endpoint with the transaction GUID to recover the `cardToken`.\n\n**`{{GUID}}`** — the `transactionID` from the `saleAndTokenizeCard` poll result.\n\n**`cardToken` format:** ProCharge format — e.g. `K33f40000000000093`. Use this token in `POST /moto/sale` as the `cardToken` field to charge without a terminal.\n\n**Note:** The token is also returned directly in the poll result of `saleAndTokenizeCard` and `tokenizeCard` as `cardToken`. Only call this endpoint when the original poll result is unavailable." }, "response": [ { "name": "200 — Token retrieved", "status": "OK", "code": 200, "body": "{\n \"httpStatus\": \"200\",\n \"cardTokenizationGuid\": \"8fa7d000-ac8a-11f1-82a2-0545c651983f\",\n \"cardToken\": \"K33f40000000000093\",\n \"maskedCardNumber\": \"************0936\",\n \"expiryDateMMYY\": \"1027\",\n \"serverDateTime\": \"20260909201054080\",\n \"agreementNumber\": \"111111111113\",\n \"transactionReference\": \"6a9107f0-ac8a-11f1-b2f8-e3715f98f995\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "Status by Reference", "request": { "method": "GET", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" } ], "url": { "raw": "https://transactions.handpoint.{{env}}/transactions/{{TXN_REF_ID}}/status", "host": [ "transactions.handpoint.{{env}}" ], "path": [ "transactions", "{{TXN_REF_ID}}", "status" ] }, "description": "Recovers the transaction status using the `transactionReference` UUID you provided in the original request.\n\n**Primary use case — UNDEFINED recovery:**\n1. Your app crashed or lost network before the poll completed.\n2. Poll result returned `UNDEFINED` (transaction completed but host didn't confirm).\n3. Call this endpoint with the `transactionReference` you stored before sending.\n\n**Base URL:** `https://transactions.handpoint.{{env}}/` (different subdomain from the main API).\n\n**`{{TXN_REF_ID}}`** — the UUID you generated and set in the original `transactionReference` field. This is why you must store it before sending the transaction.\n\n**`finStatus` values:**\n\n| `finStatus` | Meaning |\n|---|---|\n| `AUTHORISED` | Transaction completed and approved — safe to record |\n| `DECLINED` | Transaction completed and declined |\n| `CANCELLED` | Transaction was cancelled |\n| `FAILED` | Transaction failed (technical error) |\n| `UNDEFINED` | Status still unknown — wait and retry; if persistent, treat as not settled |\n| `IN_PROGRESS` | Terminal still processing — poll the `/transaction-result` endpoint instead |\n\n**Field note:** This endpoint returns `efttimestamp` (epoch ms, lowercase) and `efttransactionID` (lowercase). The polling endpoint (`/transaction-result`) returns `eFTTimestamp` (ISO string, camelCase) — same data, different format." }, "response": [ { "name": "200 — AUTHORISED", "originalRequest": { "method": "GET", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" } ], "url": { "raw": "https://transactions.handpoint.{{env}}/transactions/e0b8ea26-f9b7-4eee-b7a2-a5d9032ea47f/status", "host": [ "transactions.handpoint.{{env}}" ], "path": [ "transactions", "e0b8ea26-f9b7-4eee-b7a2-a5d9032ea47f", "status" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"finStatus\": \"AUTHORISED\",\n \"transactionID\": \"04a25de0-3386-11f1-909c-f50efeae2190\",\n \"transactionReference\": \"e0b8ea26-f9b7-4eee-b7a2-a5d9032ea47f\",\n \"type\": \"SALE\",\n \"amount\": 1000,\n \"currency\": \"EUR\"\n}" }, { "name": "200 — IN_PROGRESS (terminal still processing)", "originalRequest": { "method": "GET", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" } ], "url": { "raw": "https://transactions.handpoint.{{env}}/transactions/e0b8ea26-f9b7-4eee-b7a2-a5d9032ea47f/status", "host": [ "transactions.handpoint.{{env}}" ], "path": [ "transactions", "e0b8ea26-f9b7-4eee-b7a2-a5d9032ea47f", "status" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"finStatus\": \"IN_PROGRESS\",\n \"transactionReference\": \"e0b8ea26-f9b7-4eee-b7a2-a5d9032ea47f\"\n}" }, { "name": "200 — UNDEFINED (no result received)", "originalRequest": { "method": "GET", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" } ], "url": { "raw": "https://transactions.handpoint.{{env}}/transactions/e0b8ea26-f9b7-4eee-b7a2-a5d9032ea47f/status", "host": [ "transactions.handpoint.{{env}}" ], "path": [ "transactions", "e0b8ea26-f9b7-4eee-b7a2-a5d9032ea47f", "status" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"finStatus\": \"UNDEFINED\",\n \"transactionReference\": \"e0b8ea26-f9b7-4eee-b7a2-a5d9032ea47f\"\n}" } ] }, { "name": "Status Chain — All Operations", "request": { "method": "GET", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" } ], "url": { "raw": "https://transactions.handpoint.{{env}}/transactions/{{TXN_REF_ID}}/status/all", "host": [ "transactions.handpoint.{{env}}" ], "path": [ "transactions", "{{TXN_REF_ID}}", "status", "all" ] }, "description": "Returns all operations linked to a `transactionReference` in chronological order.\n\n**Use cases:**\n- Pre-auth lifecycle: see Create → Increase → Capture as a chain\n- Linked refund: see the original Sale followed by its Refund\n- Reversal confirmation: see Sale followed by its Reversal\n\n**Selector options** — append to the URL path:\n\n| Selector | Returns |\n|---|---|\n| `all` (default) | Full array of all linked operations |\n| `first` | First operation in the chain (original transaction) |\n| `last` | Most recent operation |\n| `{index}` | Zero-based index (e.g. `/status/1` = second operation) |\n\n**Note:** Returns raw gateway IRES XML when a numeric selector or `first`/`last` is used. `all` returns a JSON array of `TransactionStatusResult` objects.\n\n**Also useful for card token:** If you did a `saleAndTokenizeCard`, the `cardToken` is in the chain's first entry." }, "response": [ { "name": "200 — Sale + Reversal chain", "originalRequest": { "method": "GET", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" } ], "url": { "raw": "https://transactions.handpoint.{{env}}/transactions/e0b8ea26-f9b7-4eee-b7a2-a5d9032ea47f/status/all", "host": [ "transactions.handpoint.{{env}}" ], "path": [ "transactions", "e0b8ea26-f9b7-4eee-b7a2-a5d9032ea47f", "status", "all" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "[\n {\n \"finStatus\": \"AUTHORISED\",\n \"transactionID\": \"04a25de0-3386-11f1-909c-f50efeae2190\",\n \"type\": \"SALE\",\n \"totalAmount\": 1000,\n \"currency\": \"EUR\"\n },\n {\n \"finStatus\": \"AUTHORISED\",\n \"transactionID\": \"e676b6d0-3386-11f1-909c-f50efeae2190\",\n \"type\": \"VOID_REFUND\",\n \"totalAmount\": 1000,\n \"originalEFTTransactionID\": \"04a25de0-3386-11f1-909c-f50efeae2190\",\n \"currency\": \"EUR\"\n }\n]" } ] } ] }, { "name": "Device Management", "description": "Terminal control commands: ping, print receipt, stop transaction, locale, brightness, reboot.", "item": [ { "name": "Ping Device", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"pingDevice\",\n \"terminal_type\": \"{{terminal_type}}\",\n \"serial_number\": \"{{serial_number}}\"\n\n // Optional: include device info in the 202 ACK response\n // \"returnDeviceInfo\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "protocol": "https", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "Sends a connectivity check to the terminal. Use to confirm the terminal is online and reachable before initiating a payment.\n\n**Note:** `pingDevice` does not go through the normal 202→204→200 poll cycle. The 202 ACK is the final response — there is no `transactionResultId` to poll.\n\n**`returnDeviceInfo: true`** — Include device information (app version, battery, serial) in the 202 ACK. Useful for diagnostics and version checking without running a full transaction." }, "response": [ { "name": "202 Accepted — ping delivered", "status": "Accepted", "code": 202, "body": "{\n \"statusMessage\": \"Operation Accepted\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ], "description": "Sends a ping to verify the terminal is online and reachable. **No polling required** — HTTP 202 with `{\"statusMessage\": \"Operation Accepted\"}` confirms the device is connected. If the device is offline, the request times out." }, { "name": "Stop Current Transaction", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"stopCurrentTransaction\",\n \"terminal_type\": \"{{terminal_type}}\",\n \"serial_number\": \"{{serial_number}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "Cancels the operation currently in progress on the terminal. Use after a polling timeout to free the terminal for the next transaction.\n\n**When to use:**\n- Your poll loop exhausted with `UNDEFINED` or no result and the terminal is stuck showing a processing screen\n- An on-terminal MOTO (`moToSale`) timed out but no operator is present to cancel\n\n**After sending:** poll this request's `TXN_RESULT_ID` until `finStatus: CANCELLED` before sending any new terminal request. Sending a new transaction while stop is in progress returns error `1001 Device is busy`.\n\n**Response codes:**\n- **202 Accepted** — stop request delivered to terminal. Poll `transaction-result/{transactionResultId}` to confirm the in-flight transaction was cancelled (the ongoing transaction's result arrives there).\n- **400 error 1005** — no transaction is currently in progress on this terminal (immediate response, no polling).\n- **400 error 1003** — cancel not allowed; the transaction is already being processed at the acquirer and cannot be interrupted." }, "response": [ { "name": "202 Accepted — operation started", "status": "Accepted", "code": 202, "body": "{\n \"statusMessage\": \"Operation Accepted\",\n \"transactionResultId\": \"0821599465-1788986449748\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: CANCELLED (original sale)", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_CARD_READ_CANCELLED\",\n \"accountType\": \"\",\n \"aid\": \"\",\n \"applicationLabel\": \"\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"\",\n \"balance\": null,\n \"batchNumber\": \"\",\n \"budgetNumber\": \"\",\n \"cardEntryType\": \"UNDEFINED\",\n \"cardHolderName\": \"\",\n \"cardLanguagePreference\": \"\",\n \"cardSchemeName\": \"\",\n \"cardToken\": \"\",\n \"cardTypeId\": \"\",\n \"chipTransactionReport\": \"\",\n \"currency\": \"USD\",\n \"customData\": \"\",\n \"customerReceipt\": \"\",\n \"customerReference\": \"\",\n \"deviceStatus\": {\n \"applicationName\": \"Payments\",\n \"applicationVersion\": \"20.4.14.0-RC.73\",\n \"batteryCharging\": \"Charging\",\n \"batteryStatus\": \"100\",\n \"batterymV\": \"4126\",\n \"bluetoothName\": \"PAXA920\",\n \"externalPower\": \"USB\",\n \"serialNumber\": \"0821599465\",\n \"statusMessage\": \"\"\n },\n \"dueAmount\": 0,\n \"errorMessage\": \"\",\n \"expiryDateMMYY\": \"\",\n \"finStatus\": \"CANCELLED\",\n \"iad\": \"\",\n \"issuerResponseCode\": \"\",\n \"maskedCardNumber\": \"\",\n \"merchantAddress\": \"Test Address 4 10111 London\",\n \"merchantName\": \"Postman Test 3\",\n \"merchantReceipt\": \"\",\n \"metadata\": null,\n \"mid\": \"111111111113\",\n \"moneyRemittanceOptions\": null,\n \"multiLanguageErrorMessages\": {},\n \"multiLanguageStatusMessages\": {},\n \"originalEFTTransactionID\": \"\",\n \"paymentScenario\": \"UNKNOWN\",\n \"requestedAmount\": 5555,\n \"rrn\": \"\",\n \"signatureUrl\": \"\",\n \"statusMessage\": \"Transaction canceled\",\n \"surcharge\": null,\n \"taxAmount\": null,\n \"tenderType\": \"NOT_SET\",\n \"tid\": \"11111111\",\n \"tipAmount\": 0,\n \"totalAmount\": 5555,\n \"transactionID\": \"\",\n \"transactionOrigin\": \"CLOUD\",\n \"transactionReference\": \"c559e3fe-1a21-4bc1-89a9-1f6fa98be365\",\n \"tsi\": \"\",\n \"tvr\": \"\",\n \"type\": \"SALE\",\n \"unMaskedPan\": \"\",\n \"verificationMethod\": \"NOT_REQUIRED\",\n \"efttimestamp\": 1788986468787,\n \"efttransactionID\": \"\",\n \"tipPercentage\": 0,\n \"recoveredTransaction\": false,\n \"_meta\": {\n \"txnResultId\": \"0821599465-1788986446641\",\n \"polls\": 2\n },\n \"_note\": \"Poll the ORIGINAL sale's transactionResultId — not the stop operation's ID\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "400 — No transaction in progress (error 1005)", "status": "Bad Request", "code": 400, "body": "{\n \"error\": {\n \"statusCode\": 400,\n \"name\": \"BadRequestError\",\n \"message\": \"{\\\"error\\\":1005,\\\"message\\\":\\\"No transaction in progress to cancel\\\"}\"\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "400 — Cancel not allowed (error 1003)", "status": "Bad Request", "code": 400, "body": "{\n \"error\": {\n \"statusCode\": 400,\n \"name\": \"BadRequestError\",\n \"message\": \"{\\\"error\\\":1003,\\\"message\\\":\\\"Cancel not allowed, transaction being processed\\\"}\"\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "Print Receipt", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"printReceipt\",\n \"terminal_type\": \"{{terminal_type}}\",\n \"serial_number\": \"{{serial_number}}\",\n \"receipt\": \"https://receipts.handpoint.com/receipts/ecff41c0-3732-11f1-909c-f50efeae2190/customer.html\"\n // receipt accepts:\n // URL — hosted HTML page (e.g. customerReceipt URL from transaction result)\n // HTML — raw HTML string with optional embedded images (see response examples)\n // optional:\n // ,\"callbackUrl\": \"https://your-server.com/webhook\" // POST when print completes\n // ,\"transactionReference\": \"{{TXN_REF_ID}}\" // UUID v4 for deduplication\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "protocol": "https", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "Sends content to the PAX terminal's built-in printer without initiating a payment. Useful for reprinting transaction receipts, printing QR codes, loyalty stamps, or any custom content.\n\n**`receipt` field accepts:**\n- **Hosted URL** — pass the `customerReceipt` URL from a transaction result directly. The Payments App fetches and renders the page. Simplest option when the URL is already available.\n- **Raw HTML string** — inline HTML rendered by the Payments App. Supports CSS classes (`xlarge`, `large`, `bold`, `center`), `` tags with external URLs, and `` for embedded images (QR codes, barcodes, logos).\n\n**Optional fields:**\n- `callbackUrl` — receive a POST notification when the print completes\n- `transactionReference` — UUID v4 for idempotency / deduplication\n\n**Flow:** async — 202 Accepted → poll `transaction-result/{TXN_RESULT_ID}`.\n\n**Requirements:** Handpoint Payments App 4.6.0+ on the terminal.\n\n**transactionReference:** transactionReference must be a UUID v4, unique per request. Do NOT reuse it on retries — send a new UUID each time you retry the same order." }, "response": [ { "name": "202 Accepted — print job queued", "status": "Accepted", "code": 202, "body": "{\n \"statusMessage\": \"Operation Accepted\",\n \"transactionResultId\": \"0821599465-1788984796516\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "204 — Still Processing (poll again, empty body)", "status": "No Content", "code": 204, "body": "// 204 No Content — transaction is still processing.\n// Poll again in 4–6 seconds.", "_postman_previewlanguage": "text", "header": [], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: Receipt printed successfully", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"PROCESSED\",\n \"finStatus\": \"PROCESSED\",\n \"statusMessage\": \"Operation Accepted\",\n \"type\": \"PRINT_RECEIPT\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: Print failed", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"FAILED\",\n \"finStatus\": \"FAILED\",\n \"errorMessage\": \"Unable to print receipt\",\n \"type\": \"PRINT_RECEIPT\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "Set Unattended Mode", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": true // true = enable kiosk/unattended mode | false = disable\n // Hides bottom nav bar; payment screen stays in foreground.\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/devices/{{terminal_type}}/{{serial_number}}/set-unattended-mode", "protocol": "https", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "devices", "{{terminal_type}}", "{{serial_number}}", "set-unattended-mode" ] }, "description": "Enables or disables kiosk (unattended) mode on the terminal. When enabled, the Android navigation bar is hidden and the Payments App stays in the foreground.\n\n**`status`:** `true` to enable, `false` to disable.\n\n**Response:** `202 Accepted` — delivery to the terminal is asynchronous. No poll result." }, "response": [ { "name": "202 Accepted — command delivered to terminal", "originalRequest": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\"status\":true}" }, "url": { "raw": "https://cloud.handpoint.{{env}}/devices/{{terminal_type}}/{{serial_number}}/set-unattended-mode", "protocol": "https", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "devices", "{{terminal_type}}", "{{serial_number}}", "set-unattended-mode" ] } }, "status": "Accepted", "code": 202, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "// 202 Accepted — command accepted for delivery to the terminal.\n// Delivery is asynchronous. There is no poll result." } ] }, { "name": "Set Locale", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"locale\": \"en_US\" // IETF BCP 47 — e.g. en_US, en_GB, fr_FR, es_ES, de_DE, pt_PT\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/devices/{{terminal_type}}/{{serial_number}}/set-locale", "protocol": "https", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "devices", "{{terminal_type}}", "{{serial_number}}", "set-locale" ] }, "description": "Changes the display language on the terminal.\n\n**`locale`:** IETF BCP 47 tag — e.g. `\"en_US\"`, `\"en_GB\"`, `\"fr_FR\"`, `\"es_ES\"`, `\"de_DE\"`, `\"pt_PT\"`.\n\n**Response:** `202 Accepted` — delivery to the terminal is asynchronous. No poll result." }, "response": [ { "name": "202 Accepted — command delivered to terminal", "originalRequest": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\"locale\":\"en_US\"}" }, "url": { "raw": "https://cloud.handpoint.{{env}}/devices/{{terminal_type}}/{{serial_number}}/set-locale", "protocol": "https", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "devices", "{{terminal_type}}", "{{serial_number}}", "set-locale" ] } }, "status": "Accepted", "code": 202, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "// 202 Accepted — command accepted for delivery to the terminal.\n// Delivery is asynchronous. There is no poll result." } ] }, { "name": "Set Screen Brightness", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"minimumBrightnessLevel\": 20, // integer 0-100 | 0 = off, 100 = maximum\n \"maximumBrightnessLevel\": 100 // must be >= minimumBrightnessLevel\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/devices/{{terminal_type}}/{{serial_number}}/set-screen-brightness", "protocol": "https", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "devices", "{{terminal_type}}", "{{serial_number}}", "set-screen-brightness" ] }, "description": "Sets the minimum and maximum brightness range for the terminal display.\n\nBoth values are integers 0–100. Values outside this range return `400 Bad Request`.\n\n**Response:** `202 Accepted` — delivery to the terminal is asynchronous. No poll result." }, "response": [ { "name": "202 Accepted — command delivered to terminal", "originalRequest": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\"minimumBrightnessLevel\":20,\"maximumBrightnessLevel\":100}" }, "url": { "raw": "https://cloud.handpoint.{{env}}/devices/{{terminal_type}}/{{serial_number}}/set-screen-brightness", "protocol": "https", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "devices", "{{terminal_type}}", "{{serial_number}}", "set-screen-brightness" ] } }, "status": "Accepted", "code": 202, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "// 202 Accepted — command accepted for delivery to the terminal.\n// Delivery is asynchronous. There is no poll result." } ] }, { "name": "Set Reboot Time", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"hour\": 2 // 24h clock integer 0-23 — reboot fires at a random minute within this hour\n // staggers fleet reboots to avoid simultaneous restarts\n // Production devices only — no effect on staging/dev\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/devices/{{terminal_type}}/{{serial_number}}/set-reboot-time", "protocol": "https", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "devices", "{{terminal_type}}", "{{serial_number}}", "set-reboot-time" ] }, "description": "Schedules a daily automatic reboot at the specified hour. The reboot fires at a random minute within that hour to stagger restarts across a device fleet.\n\n**`hour`:** integer 0–23. Values outside this range return `400 Bad Request`.\n\n**Production devices only** — has no effect on development or staging devices.\n\n**Response:** `202 Accepted` — delivery to the terminal is asynchronous. No poll result." }, "response": [ { "name": "202 Accepted — command delivered to terminal", "originalRequest": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\"hour\":2}" }, "url": { "raw": "https://cloud.handpoint.{{env}}/devices/{{terminal_type}}/{{serial_number}}/set-reboot-time", "protocol": "https", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "devices", "{{terminal_type}}", "{{serial_number}}", "set-reboot-time" ] } }, "status": "Accepted", "code": 202, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "// 202 Accepted — command accepted for delivery to the terminal.\n// Delivery is asynchronous. There is no poll result." } ] }, { "name": "Reboot", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"force\": false // false = check for active transaction before rebooting (recommended)\n // true = reboot immediately — can interrupt an active transaction\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/devices/{{terminal_type}}/{{serial_number}}/reboot", "protocol": "https", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "devices", "{{terminal_type}}", "{{serial_number}}", "reboot" ] }, "description": "Remotely reboots the terminal.\n\n**`force: false` (recommended):** checks whether a transaction is in progress; defers the reboot until the terminal is idle.\n\n**`force: true`:** reboots immediately regardless of state. Use only when the terminal is unresponsive — can interrupt and potentially lose an active transaction.\n\n**Response:** `202 Accepted` — delivery to the terminal is asynchronous. No poll result." }, "response": [ { "name": "202 Accepted — command delivered to terminal", "originalRequest": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\"force\":false}" }, "url": { "raw": "https://cloud.handpoint.{{env}}/devices/{{terminal_type}}/{{serial_number}}/reboot", "protocol": "https", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "devices", "{{terminal_type}}", "{{serial_number}}", "reboot" ] } }, "status": "Accepted", "code": 202, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "// 202 Accepted — command accepted for delivery to the terminal.\n// Delivery is asynchronous. There is no poll result." } ] }, { "name": "Update Device", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}", "description": "Merchant API key." } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"update\",\n \"terminal_type\": \"{{terminal_type}}\",\n \"serial_number\": \"{{serial_number}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "Triggers a software or configuration update on the terminal. The device downloads and applies the latest update from the TMS.\n\n**Note:** The terminal may reboot during the update process. Do not initiate transactions during an update. The 202 ACK confirms the update was triggered — there is no finStatus result to poll." }, "response": [ { "name": "202 Accepted — operation started", "status": "Accepted", "code": 202, "body": "{\n \"statusMessage\": \"Operation Accepted\",\n \"transactionResultId\": \"0821599465-1788984051755\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "Read Card PAN", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}", "description": "Merchant API key." } ], "body": { "mode": "raw", "raw": "{\n \"operation\": \"cardPan\",\n \"terminal_type\": \"{{terminal_type}}\",\n \"serial_number\": \"{{serial_number}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "Reads the card PAN from the terminal without processing a payment. Used for loyalty programs, card lookup, or non-payment card reads.\n\n**Poll result:** `finStatus=AUTHORISED`, `maskedCardNumber` populated. The `type` in the result will be `CARD_PAN`.\n\n**Privacy note:** The PAN is returned masked in `maskedCardNumber`. Storing unmasked PANs is subject to PCI DSS requirements — consult your compliance team before using.\n\n**Not available for all merchants.** Requires explicit activation in your Handpoint merchant configuration." }, "response": [ { "name": "202 Accepted — operation started", "status": "Accepted", "code": 202, "body": "{\n \"statusMessage\": \"Operation Accepted\",\n \"transactionResultId\": \"0821599465-1788984051755\",\n \"transactionReference\": \"{{TXN_REF_ID}}\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "204 — Still Processing (poll again, empty body)", "status": "No Content", "code": 204, "body": "// 204 No Content — transaction is still processing.\n// Poll again in 4–6 seconds.", "_postman_previewlanguage": "text", "header": [], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: AUTHORISED (card read)", "status": "OK", "code": 200, "body": "{\n \"finStatus\": \"AUTHORISED\",\n \"type\": \"CARD_PAN\",\n \"maskedCardNumber\": \"************0936\",\n \"cardSchemeName\": \"Visa\",\n \"expiryDateMMYY\": \"1027\",\n \"cardEntryType\": \"ICC\",\n \"transactionOrigin\": \"CLOUD\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Poll: CANCELLED", "status": "OK", "code": 200, "body": "{\n \"_statusMessage\": \"TEXT_CARD_READ_CANCELLED\",\n \"arc\": \"0000\",\n \"authorisationCode\": \"\",\n \"batchNumber\": \"\",\n \"cardEntryType\": \"UNDEFINED\",\n \"cardSchemeName\": \"Visa\",\n \"currency\": \"USD\",\n \"errorMessage\": \"\",\n \"finStatus\": \"CANCELLED\",\n \"issuerResponseCode\": \"\",\n \"maskedCardNumber\": \"************0936\",\n \"paymentScenario\": \"UNKNOWN\",\n \"statusMessage\": \"Cancelled\",\n \"transactionOrigin\": \"CLOUD\",\n \"type\": \"CARD_PAN\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] } ] }, { "name": "Reporting", "description": "Transaction feed queries and batch management (EPI only).", "item": [ { "name": "Get Transaction by GUID", "request": { "method": "GET", "header": [ { "key": "AnalyticsApiKey", "value": "{{analytics_key}}" } ], "url": { "raw": "https://txnfeed.handpoint.{{env}}/transactions/{{GUID}}", "host": [ "txnfeed.handpoint.{{env}}" ], "path": [ "transactions", "{{GUID}}" ] }, "description": "Uses `AnalyticsApiKey` header — the value is the **same API key** as `ApiKeyCloud`. Two different header names for two different backend services, same credential.\n\nRetrieves a single transaction record from the feed by its `transactionID` (the GUID variable).\n\nUseful for UNDEFINED recovery when you have the `transactionID` but need to confirm settlement status." }, "response": [ { "name": "200 — Transaction found", "status": "OK", "code": 200, "body": "{\n \"posDataCode\": \"81010180034C\",\n \"approvalCode\": \"123456\",\n \"responseText\": \"Successful\",\n \"softwareVersion\": \"20.4.14.0-RC.73\",\n \"transactionReference\": \"b47584c2-9761-4fa4-9db2-3f091c0ee7a8\",\n \"issuerRequestTimestamp\": \"20260909220121\",\n \"routeName\": \"viscusdummy\",\n \"status\": \"200\",\n \"acquirerMid\": \"111111111113\",\n \"merchantId\": \"mer20260907120000001\",\n \"acquirerId\": \"tsys\",\n \"locationZipCode\": \"10111\",\n \"isSingleEmvMessage\": true,\n \"expiryDateMMYY\": \"1027\",\n \"@timestamp\": \"2026-09-09T20:10:02.475Z\",\n \"batchNum\": \"123\",\n \"cardTypeId\": \"Visa\",\n \"protocolName\": \"ViscusDummy\",\n \"isvId\": \"handpoint\",\n \"serverDateTime\": \"20260909200104\",\n \"issuerResponseTimestamp\": \"20260909220121\",\n \"agreementNumber\": \"111111111113\",\n \"type\": \"Sale\",\n \"issuerRetrievalReferenceNumber\": \"0000909387899\",\n \"transaction_id\": 24835741,\n \"partnerId\": \"alex_test_partner\",\n \"@version\": \"1\",\n \"acquirerName\": \"TSYS\",\n \"terminalLanguage\": \"en\",\n \"locationName\": \"Test Address 4\",\n \"merchantExternalId\": \"mainmid\",\n \"merchantName\": \"Postman Test 3\",\n \"issuerRequestAcquirerTid\": \"ACQUIRER_TID\",\n \"tipAmount\": \"0.00\",\n \"sdkVersion\": \"7.1014.0-RC.73\",\n \"amount\": \"0.01000\",\n \"storeAndForward\": false,\n \"isvName\": \"Handpoint\",\n \"action\": \"AUTHORIZATION_REQUEST\",\n \"locationCity\": \"London\",\n \"messageVersion\": 1,\n \"deviceType\": \"PAXA920\",\n \"issuerResponseCode\": \"00\",\n \"name\": \"EMV Sale\",\n \"country\": \"United Kingdom\",\n \"paymentCode\": \"C\",\n \"mcccode\": \"5974\",\n \"guid\": \"300866b0-ac89-11f1-82a2-0545c651983f\",\n \"timeZone\": \"CUT\",\n \"referenceObject\": {},\n \"currCode\": \"USD\",\n \"terminalSerialNumber\": \"0821599465\",\n \"maskedCardNumber\": \"496663******0936\",\n \"protocolLookupName\": \"DummyProtocol\",\n \"locationCountryA2\": \"GB\",\n \"terminalDateTime\": \"20260909220121\",\n \"locationStreet\": \"Test Address 4\",\n \"paymentScenario\": \"CHIPCONTACTLESS\",\n \"acquirerTid\": \"ACQUIRER_TID\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "404 — Transaction not found", "status": "Not Found", "code": 404, "body": "{\n \"error\": {\n \"statusCode\": 404,\n \"name\": \"NotFoundError\",\n \"message\": \"Transaction not found\"\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "Search Transactions", "request": { "method": "POST", "header": [ { "key": "AnalyticsApiKey", "value": "{{analytics_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"startDate\": \"20260905000000\", // format: YYYYMMDDHHmmss\n \"endDate\": \"20260905235959\", // format: YYYYMMDDHHmmss\n \"time_zone\": \"+00:00\", // UTC offset (+00:00, +01:00...) or IANA name e.g. Europe/London\n \"dummy\": \"INCLUDE\", // DEMO/test txns — values: NO (exclude) | INCLUDE | ONLY (test txns only)\n \"filters\": [ // filters are combined — add as many as needed\n { \"field\": \"transactionReference\", \"value\": \"{{TXN_REF_ID}}\" },\n // { \"field\": \"cardTypeId\", \"value\": \"Diners\" },\n // { \"field\": \"amount\", \"value\": \"26900.00000\" },\n // { \"field\": \"maskedCardNumber\", \"value\": \"379797*****2009\" },\n // { \"field\": \"approvalCode\", \"value\": \"vL491R\" },\n // { \"field\": \"terminalSerialNumber\", \"value\": \"{{serial_number}}\" }\n ],\n \"limit\": 100 // max results per page\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://txnfeed.handpoint.{{env}}/transactions/", "host": [ "txnfeed.handpoint.{{env}}" ], "path": [ "transactions", "" ] }, "description": "Uses `AnalyticsApiKey` header — the value is the **same API key** as `ApiKeyCloud`. Two different header names for two different backend services, same credential.\n\nSearches the transaction feed by time range and optional filters. Primary use case: UNDEFINED recovery when `transactionReference` recovery is unavailable.\n\n**`startDate` / `endDate`:** format `yyyyMMddHHmmss` (e.g. `\"20260905120000\"`).\n\n**`time_zone`:** IANA timezone string (e.g. `\"Europe/London\"`, `\"America/New_York\"`, `\"UTC\"`).\n\n**`dummy`:** controls inclusion of test/simulator transactions:\n- `\"INCLUDE\"` — include both real and dummy transactions\n- `\"ONLY\"` — only dummy/simulator transactions\n- `\"NO\"` — only real transactions\n\n**Available `filters` fields:** `transactionReference`, `amount`, `maskedCardNumber`, `cardTypeId`, `approvalCode`, `terminalSerialNumber`\n\n**UNDEFINED recovery pattern:** filter by `terminalSerialNumber` + narrow time window (±5 min around the original request). Match by `transactionReference` to identify the specific transaction — do NOT match by amount alone (multiple transactions may share the same amount).\n\n**transactionReference:** transactionReference must be a UUID v4, unique per request. Do NOT reuse it on retries — send a new UUID each time you retry the same order." }, "response": [ { "name": "200 OK — results", "originalRequest": { "method": "POST", "header": [ { "key": "AnalyticsApiKey", "value": "{{analytics_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\"startDate\":\"20260905000000\",\"endDate\":\"20260905235959\",\"time_zone\":\"+00:00\",\"dummy\":\"INCLUDE\",\"filters\":[{\"field\":\"transactionReference\",\"value\":\"7a52d8e1-cafe-4b2f-9f3c-1234abcd5678\"}],\"limit\":100}" }, "url": { "raw": "https://txnfeed.handpoint.{{env}}/transactions/", "host": [ "txnfeed.handpoint.{{env}}" ], "path": [ "transactions", "" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"transactions\": [\n {\n \"transactionID\": \"04a25de0-3386-11f1-909c-f50efeae2190\",\n \"transactionReference\": \"e0b8ea26-f9b7-4eee-b7a2-a5d9032ea47f\",\n \"finStatus\": \"AUTHORISED\",\n \"type\": \"SALE\",\n \"totalAmount\": 1000,\n \"currency\": \"EUR\",\n \"cardSchemeName\": \"Visa\",\n \"maskedCardNumber\": \"************0936\",\n \"terminalSerialNumber\": \"1850025030\",\n \"serverDateTime\": \"20260905120000000\"\n }\n ],\n \"total\": 1\n}" } ] }, { "name": "Batch Summary (EPI only)", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"serialNumber\": \"{{serial_number}}\", // required — terminal serial number\n \"deviceType\": \"{{terminal_type}}\" // required — terminal model e.g. PAXA920\n\n // batchNumber is OPTIONAL — gateway resolves the last batch for this terminal.\n // Include only when targeting a specific batch:\n // \"batchNumber\": \"123\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/batch/summary", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "batch", "summary" ] }, "description": "Returns a summary of the current batch for a terminal. EPI only. Same field naming as Batch Close (`deviceType` / `serialNumber`).\n\n**`batchNumber` is optional** — gateway auto-resolves the last batch for the terminal. Include only when targeting a specific historical batch.\n\n**Note:** `transactionCount` and `netAmount` are returned by the staging dummy acquirer but may not be present in all production acquirer responses. Check `batchStatus` and `issuerResponseCode` for success." }, "response": [ { "name": "200 — Batch Summary (OPEN batch)", "status": "OK", "code": 200, "body": "{\n \"httpStatus\": \"200\",\n \"batchNumber\": \"133\",\n \"transactionCount\": \"12\",\n \"netAmount\": \"644397\",\n \"issuerResponseCode\": \"00\",\n \"issuerResponseText\": \"DATA RETRIEVED\",\n \"customFields\": {\n \"entry\": [\n {\n \"key\": \"salesCount\",\n \"value\": \"11\"\n },\n {\n \"key\": \"refundsCount\",\n \"value\": \"1\"\n }\n ]\n },\n \"batchSummaryGuid\": \"1ef0c830-bbe4-11f1-9efa-074a901f9b3c\",\n \"batchStatus\": \"OPEN\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "Batch Close (EPI only)", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"serialNumber\": \"{{serial_number}}\", // required — terminal serial number\n \"deviceType\": \"{{terminal_type}}\" // required — terminal model e.g. PAXA920\n\n // batchNumber is OPTIONAL (GW-350) — gateway auto-resolves the last open batch.\n // Include only when targeting a specific batch:\n // \"batchNumber\": \"123\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/batch/close", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "batch", "close" ] }, "description": "Triggers end-of-day settlement for EPI merchants. **Must be called once per business day.** Missing a batch close causes ERR 005 (batch number mismatch) on all subsequent transactions.\n\n**EPI only** — do NOT call for EmerchantPay or Paystrax merchants (they settle automatically).\n\n**`batchNumber` is optional** (implemented in GW-350). The gateway automatically resolves the last open batch number for the terminal from its internal store. Include `batchNumber` only when you need to target a specific batch.\n\n**Minimum required body:** `serialNumber` + `deviceType` — that's it.\n\n**Field naming:** `deviceType` and `serialNumber` (camelCase) — NOT `terminal_type` / `serial_number` (the snake_case names used by `POST /transactions`). Different naming convention on batch endpoints.\n\n**Timing:** call after the last transaction of the business day. Typical EPI auto-close is ~11 PM EST.\n\n**Error cases:**\n\n| Scenario | Response |\n|---|---|\n| `deviceType` doesn't match the serial number | 400 with `errorCode: 5001` (NullPointerException from Viscus) |\n| `serialNumber` not found for this merchant | 500 Internal Server Error |\n| Terminal has never transacted (no batch in store) | Error similar to wrong batch number |\n\n**Response note:** The `transactionCount` and `netAmount` fields appear on staging (dummy acquirer) but are **not returned by TSYS** in production. Do not rely on them. Use `batchStatus: \"CLOSED\"` and `issuerResponseCode: \"00\"` as success indicators. TSYS production responses include `customFields.entry.key: \"issuerBatchCloseLocalTimestamp\"` with the local close time." }, "response": [ { "name": "200 — Batch Closed (TSYS production)", "status": "OK", "code": 200, "body": "{\n \"httpStatus\": \"200\",\n \"customerReference\": {},\n \"customFields\": {\n \"entry\": {\n \"key\": \"issuerBatchCloseLocalTimestamp\",\n \"value\": \"2026-04-30T10:36:12\"\n }\n },\n \"batchNumber\": \"1\",\n \"closeBatchGuid\": \"68624790-4480-11f1-a352-917acde1c4c2\",\n \"closedAt\": \"20260430103612405\",\n \"issuerResponseCode\": \"00\",\n \"issuerResponseText\": \"ACCEPTED\",\n \"batchStatus\": \"CLOSED\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Batch Closed (staging dummy — extra fields)", "status": "OK", "code": 200, "body": "{\n \"httpStatus\": \"200\",\n \"customerReference\": {},\n \"batchNumber\": \"123\",\n \"transactionCount\": \"10\",\n \"netAmount\": \"1000.00\",\n \"closeBatchGuid\": \"e1986000-ac8a-11f1-b2f8-e3715f98f995\",\n \"closedAt\": \"20260909201311617\",\n \"issuerResponseCode\": \"00\",\n \"issuerResponseText\": \"Batch closed\",\n \"batchStatus\": \"CLOSED\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "400 — deviceType / serialNumber mismatch (error 5001)", "status": "Bad Request", "code": 400, "body": "{\n \"error\": {\n \"statusCode\": 400,\n \"name\": \"BadRequestError\",\n \"message\": \"Viscus operation failed\",\n \"details\": {\n \"status\": 500,\n \"body\": {\n \"error\": {\n \"errorGuid\": \"708636b0-4481-11f1-a352-917acde1c4c2\",\n \"reason\": \"NullPointerException\",\n \"errorCode\": \"5001\",\n \"httpStatus\": \"500\"\n }\n }\n }\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "500 — serialNumber not found for merchant", "status": "Internal Server Error", "code": 500, "body": "{\n \"error\": {\n \"statusCode\": 500,\n \"message\": \"Internal Server Error\"\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "name": "Batch Detail (EPI only)", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}", "description": "Merchant API key." } ], "body": { "mode": "raw", "raw": "{\n \"serialNumber\": \"{{serial_number}}\",\n \"deviceType\": \"{{terminal_type}}\",\n \"batchNumber\": \"123\"\n // \"retrievalReferenceNumber\": \"627121800441\" // optional — pagination cursor: pass the oldest retrievalReferenceNumber from the previous page to fetch the next page\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/batch/detail", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "batch", "detail" ] }, "description": "Returns up to 5 line-item transactions per page for a specific batch, in descending order (newest first). Use `retrievalReferenceNumber` for cursor-based pagination.\n\n**Pagination:** On the first call, omit `retrievalReferenceNumber`. Each response item includes a `retrievalReferenceNumber`. Pass the `retrievalReferenceNumber` of the **last (oldest) item** to get the next page. Stop when `details` is empty.\n\n**EPI only** — requires an EPI acquirer integration.\n\n**Fields:**\n\n| Field | Type | Required | Description |\n|---|---|---|---|\n| `serialNumber` | string | Yes | Terminal serial number |\n| `deviceType` | string | Yes | Terminal model, e.g. `PAXA920` |\n| `batchNumber` | string | Yes | Batch number to retrieve |\n| `retrievalReferenceNumber` | string | No | Pagination cursor — pass the oldest `retrievalReferenceNumber` from the previous page to fetch the next page |" }, "response": [ { "name": "200 — Page 1 (first call, no cursor)", "status": "OK", "code": 200, "body": "{\n \"httpStatus\": \"200\",\n \"batchNumber\": \"132\",\n \"closedAt\": \"20260928214051578\",\n \"issuerResponseCode\": \"00\",\n \"issuerResponseText\": \"DATA RETRIEVED\",\n \"details\": [\n {\n \"transactionType\": \"SALE\",\n \"retrievalReferenceNumber\": \"627121800445\",\n \"amount\": \"1200\"\n },\n {\n \"transactionType\": \"SALE\",\n \"retrievalReferenceNumber\": \"627121800444\",\n \"amount\": \"1002\"\n },\n {\n \"transactionType\": \"SALE\",\n \"retrievalReferenceNumber\": \"627121800443\",\n \"amount\": \"21000\"\n },\n {\n \"transactionType\": \"SALE\",\n \"retrievalReferenceNumber\": \"627121800442\",\n \"amount\": \"27000\"\n },\n {\n \"transactionType\": \"SALE\",\n \"retrievalReferenceNumber\": \"627121800441\",\n \"amount\": \"26000\"\n }\n ],\n \"batchDetailGuid\": \"f02e9130-bbe3-11f1-9efa-074a901f9b3c\",\n \"customFields\": {\n \"entry\": {\n \"key\": \"issuerBatchCloseLocalTimestamp\",\n \"value\": \"2026-09-28T02:40:51\"\n }\n },\n \"batchStatus\": \"CLOSED\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Page 2 (with retrievalReferenceNumber cursor)", "status": "OK", "code": 200, "body": "{\n \"httpStatus\": \"200\",\n \"batchNumber\": \"132\",\n \"closedAt\": \"20260928214051578\",\n \"issuerResponseCode\": \"00\",\n \"issuerResponseText\": \"DATA RETRIEVED\",\n \"details\": [\n {\n \"transactionType\": \"SALE\",\n \"retrievalReferenceNumber\": \"627121800440\",\n \"amount\": \"19001\"\n },\n {\n \"transactionType\": \"REFUND\",\n \"retrievalReferenceNumber\": \"627121800439\",\n \"amount\": \"1857\"\n },\n {\n \"transactionType\": \"SALE\",\n \"retrievalReferenceNumber\": \"627121800438\",\n \"amount\": \"5542\"\n },\n {\n \"transactionType\": \"SALE\",\n \"retrievalReferenceNumber\": \"627120800437\",\n \"amount\": \"1683\"\n },\n {\n \"transactionType\": \"SALE\",\n \"retrievalReferenceNumber\": \"627120800436\",\n \"amount\": \"1347\"\n }\n ],\n \"batchDetailGuid\": \"0b9d45b0-bbe4-11f1-9da8-4ba186f642f0\",\n \"customFields\": {\n \"entry\": {\n \"key\": \"issuerBatchCloseLocalTimestamp\",\n \"value\": \"2026-09-28T02:40:51\"\n }\n },\n \"batchStatus\": \"CLOSED\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "200 — Empty page (stop — no more transactions)", "status": "OK", "code": 200, "body": "{\n \"httpStatus\": \"200\",\n \"batchNumber\": \"132\",\n \"closedAt\": \"20260928214051578\",\n \"issuerResponseCode\": \"00\",\n \"issuerResponseText\": \"DATA RETRIEVED\",\n \"details\": [],\n \"batchDetailGuid\": \"a1b2c3d4-0000-0000-0000-000000000000\",\n \"batchStatus\": \"CLOSED\"\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] } ] }, { "name": "Test Cases", "description": "Trigger amounts and scenarios for validating integration behaviour. These are not real API requests — use them as a reference when running test transactions.", "item": [ { "name": "Magic Amounts — Trigger Specific Outcomes", "request": { "method": "GET", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" } ], "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "Use these amounts (in **minor units** — multiply by 100) to force specific issuer responses on the staging environment.\n\n| Amount (major) | Minor units | Behaviour | Expected `finStatus` | `issuerResponseCode` |\n|---|---|---|---|---|\n| $37.84 | `3784` | Not authorized | `DECLINED` | `05` |\n| $37.79 | `3779` | Refer to issuer | `DECLINED` | `01` |\n| $37.93 | `3793` | Pick up card | `DECLINED` | `04` |\n| $37.57 | `3757` | Partial approval | `PARTIAL_APPROVAL` | `10` |\n| $37.68 | `3768` | Issuer timeout | `UNDEFINED` or `FAILED` | — |\n\n**Example — force a decline:**\n```json\n{\n \"operation\": \"sale\",\n \"amount\": \"3784\",\n \"currency\": \"USD\",\n \"terminal_type\": \"{{terminal_type}}\",\n \"serial_number\": \"{{serial_number}}\",\n \"transactionReference\": \"{{$randomUUID}}\"\n}\n```\n\nAll other amounts process normally on this staging merchant.\n\n**Observed on staging dummy acquirer:** All decline amounts return `issuerResponseCode: \"00\"` with `arc: \"1000\"` (dummy acquirer always echoes 00 — real production acquirers return the correct code). `_statusMessage` values: DECLINED → `TEXT_IRT_05`, FAILED → `ERROR_CONNECTING_TO_AUTHORIZATION_PROVIDER`." }, "response": [] }, { "name": "CANCELLED — Stop a Transaction", "request": { "method": "GET", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" } ], "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "`CANCELLED` appears in two scenarios:\n\n**1. Cardholder presses Cancel on the terminal**\n- No action required from the POS — just poll until `finStatus=CANCELLED` is returned.\n\n**2. POS sends `stopCurrentTransaction`**\n- Use when your poll loop exhausts without a result, or you want to programmatically cancel.\n- See the **Stop Current Transaction** request in Device Management.\n- The *original* transaction's poll returns `CANCELLED`.\n\n**When `stopCurrentTransaction` fails:**\n- `error.code = 1005` — no transaction in progress.\n- `error.code = 1003` — terminal is mid-processing and the cancel was rejected (e.g., card already being read by the chip).\n\n**Important:** Always poll the *original* `transactionResultId` to get the CANCELLED result, not the stop operation's result ID." }, "response": [] }, { "name": "PARTIAL_APPROVAL — Handling Split Payments", "request": { "method": "GET", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" } ], "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "`PARTIAL_APPROVAL` occurs when the issuer approves less than the requested amount (e.g., prepaid card with insufficient balance).\n\n**Fields to check:**\n- `finStatus = \"PARTIAL_APPROVAL\"`\n- `requestedAmount` — what you asked for\n- `totalAmount` — what was actually approved (less than requested)\n\n**Integration requirements (US merchants):**\n1. **Accept**: charge `totalAmount` to the card, collect the remainder via another payment method.\n2. **Reverse**: call `POST /reversal` with `originalGuid` to void the partial approval, then retry with a different card.\n\n**Test trigger:** `amount = \"3757\"` ($37.57 minor units)\n\n**Never** ignore a `PARTIAL_APPROVAL` — failing to handle it means the customer was charged but your order was not fulfilled correctly." }, "response": [] }, { "name": "UNDEFINED — Recovery via Status Endpoint", "request": { "method": "GET", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" } ], "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "`UNDEFINED` appears when the terminal completes a transaction but the result cannot be confirmed by the host (network drop, app crash, timeout).\n\n**Recovery flow:**\n1. Store `transactionReference` (UUID you generate) **before** sending the request.\n2. If polling returns `UNDEFINED`, or your app restarts without a result:\n ```\n GET https://transactions.handpoint.{{env}}/transactions/{{TXN_REF_ID}}/status\n ```\n3. Response will be `AUTHORISED`, `DECLINED`, `CANCELLED`, or `UNDEFINED` (still unknown).\n4. If still `UNDEFINED` after repeated checks, the transaction was not settled — safe to retry with a new `transactionReference`.\n\n**Test trigger:** `amount = \"3768\"` ($37.68) — forces an issuer timeout.\n\n**Simulate full disconnect:** Start a transaction, cut the network at the terminal, restore — the result will poll back as UNDEFINED until the status endpoint resolves it.\n\nSee **Status by Reference** and **Status Chain** requests in Transaction Results & Operations." }, "response": [] }, { "name": "Card Entry Types — paymentScenario Values", "request": { "method": "GET", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" } ], "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "The `cardEntryType` and `paymentScenario` fields in the poll result indicate how the card was read.\n\n| `cardEntryType` | `paymentScenario` | Description |\n|---|---|---|\n| `ICC` | `CHIPCONTACTLESS` | NFC / tap-to-pay (Apple Pay, Google Pay, contactless card) |\n| `ICC` | `CHIP` | EMV chip contact (card inserted) |\n| `MSR` | `MAG_STRIPE` | Magnetic stripe swipe |\n| `CNP` | `MOTO` | Card not present — keyed entry (Handpoint moTo operations) |\n\n**Detecting mobile wallets (NFC):**\n- `paymentScenario = CHIPCONTACTLESS` does not distinguish physical contactless from Apple Pay/Google Pay.\n- To detect a mobile wallet, inspect EMV tag `9F34` (CVM Results): a value of `42` (no CVM performed) usually indicates a digital wallet on NFC, while `1F` indicates consumer device CVM (phone PIN).\n\n**MSR fallback:** Most terminals fall back to MSR if chip fails 3 times. `cardEntryType=MSR` with `paymentScenario=FALLBACK` indicates a chip-failure fallback." }, "response": [] }, { "name": "transactionReference — Idempotency Rules", "request": { "method": "GET", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" } ], "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "The `transactionReference` is a **UUID v4** you generate per transaction request. It is your idempotency key.\n\n**Rules:**\n- Generate a **new UUID for every new request** — never reuse across retries for the same order.\n- Store it **before** sending the request — you need it for recovery via `GET /transactions/{ref}/status`.\n- The API may reject duplicate references within a short time window (duplicate-check protection).\n- It is echoed back in the poll result as `transactionReference`.\n\n**Pre-request script (Postman)** — auto-generates a fresh UUID per request:\n```javascript\npm.collectionVariables.set(\"TXN_REF_ID\", pm.variables.replaceIn(\"{{$randomUUID}}\"));\n```\n\n**Variable chaining:** The `TXN_REF_ID` collection variable is set by the pre-request script on transaction requests, and used by Status by Reference for recovery polling." }, "response": [] }, { "name": "Common Errors — Wrong Currency / Agreement Not Found", "request": { "method": "GET", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" } ], "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "`Agreement not found` is the most common configuration error. It means the currency in your request does not match the acquirer agreement set up for this merchant.\n\n**Trigger:**\n```json\n{\n \"operation\": \"sale\",\n \"amount\": \"1000\",\n \"currency\": \"HUF\",\n ...\n}\n```\n\n**Response (422):**\n```json\n{\n \"error\": {\n \"statusCode\": 422,\n \"name\": \"UnprocessableEntityError\",\n \"message\": \"Agreement not found\"\n }\n}\n```\n\n**Fix:** Use the currency that matches your merchant configuration. Verify with `GET /devices` — the terminal list shows the merchant ID; check the merchant dashboard for the configured currency.\n\n**Other `Agreement not found` causes:**\n- Correct currency but wrong `serial_number` (terminal belongs to a different merchant)\n- Terminal is in test mode but you're hitting production (`cloud.handpoint.com`), or vice versa\n- Merchant account suspended or not yet activated\n\n**Other common 422 errors:**\n\n| Cause | Message |\n|---|---|\n| `terminal_type` doesn't match actual device | `Terminal type mismatch` |\n| `serial_number` not associated with API key | `Terminal not found / error 1004` |\n| Missing required field | `VALIDATION_FAILED` with `details` array |\n| `amount` not a string of integer digits | `VALIDATION_FAILED` |" }, "response": [] }, { "name": "MSR Chip-Fallback — Signature Cancellation Edge Case", "request": { "method": "GET", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" } ], "url": { "raw": "https://cloud.handpoint.{{env}}/transactions", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions" ] }, "description": "When EMV chip fails 3 times, the terminal falls back to magnetic stripe (`paymentScenario = CHIPFAILMAGSTRIPE`). After a successful MSR authorization, the terminal displays a **signature screen** for the cardholder to sign.\n\n**The risk:** The cardholder (or cashier) can cancel at the signature step *after* the payment has been authorized by the issuer.\n\n**What each endpoint shows during this window:**\n\n| Endpoint | Value | Meaning |\n|---|---|---|\n| `GET /transactions/{ref}/status` | `AUTHORISED` | Issuer approved — money is reserved |\n| `GET /transaction-result/{id}` (poll) | `204` (still processing) | Terminal hasn't delivered final result yet |\n\nThe `/status` endpoint reflects the *issuer* authorization state. The transaction result reflects the *terminal's* confirmed completion (including signature acceptance).\n\n**ISV rule:** Do not record an MSR transaction as final until:\n1. The poll (`GET /transaction-result/{id}`) returns a `200` with `finStatus`, **or**\n2. At least **60 seconds** have passed since the authorization — then query `/status` again to confirm.\n\nIf the signature is cancelled, the final poll result will arrive with `finStatus = CANCELLED` even though `/status` reported `AUTHORISED`.\n\n**Why this matters:** Recording the order as paid when the transaction is still pending the signature step means you may charge the customer for an order they declined to sign for, requiring a manual refund.\n\n**Detection:** `cardEntryType = MSR` with `paymentScenario = CHIPFAILMAGSTRIPE` — treat all MSR transactions with extra caution. Always wait for the poll result." }, "response": [] } ] } ] }