{ "info": { "name": "Handpoint Back-Office API", "description": "Direct-to-gateway back-office operations compatible with **all** Handpoint integration paths (Android SDK, iOS SDK, PAX, Hilite, Cloud API).\n\nNone of these requests require a card reader or cardholder interaction — they go straight to the Handpoint gateway over HTTPS. Use them alongside any existing SDK integration to add reversal, remote charging, tip adjustment, batch management, and reporting capabilities.\n\n**Environment:** set `env` to `com` (production) or `io` (staging). All base URLs resolve as `cloud.handpoint.{{env}}` or `txnfeed.handpoint.{{env}}`.\n\n**GUID / originalGuid:** the transaction identifier returned by your SDK integration (Android: `transactionResult.EFTTransactionID`, iOS: `transactionResult.efttransactionID`, PAX/Cloud API: `efttransactionID` / `transactionID`). Set the `GUID` collection variable to use it across requests.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "variable": [ { "key": "env", "value": "com", "description": "Domain suffix: com (production) or io (staging)" }, { "key": "api_key", "value": "", "description": "ApiKeyCloud — from Handpoint portal" }, { "key": "analytics_key", "value": "", "description": "AnalyticsApiKey — same value as api_key (ApiKeyCloud). Set once to use in Transaction Feed requests." }, { "key": "serial_number", "value": "", "description": "Terminal serial number — from List Devices" }, { "key": "currency", "value": "EUR", "description": "ISO 4217 currency code" }, { "key": "GUID", "value": "", "description": "Transaction GUID from your SDK (efttransactionID / EFTTransactionID). Set this before using Reversal or reporting requests." }, { "key": "CARD_TOKEN", "value": "", "description": "Card token from a saleAndTokenizeCard / tokenizeCard / GET /token operation. Required for Remote Sale." }, { "key": "terminal_type", "value": "", "description": "Terminal model — from List Devices response (e.g. PAXA920)" }, { "key": "TXN_REF_ID", "value": "", "description": "UUID v4 — generated by the pre-request script on Remote Sale; also used by Search Transactions" } ], "item": [ { "name": "Setup", "description": "Verify credentials and retrieve the list of terminals assigned to the merchant account.\n\n**`serial_number`** is used by Batch Close, Batch Summary, and Tip Adjustment. Copy it from the List Devices response and set the `serial_number` collection variable.", "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", "originalRequest": { "method": "GET", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" } ], "url": { "raw": "https://cloud.handpoint.{{env}}/devices", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "devices" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "[\n {\n \"serial_number\": \"1850025030\",\n \"terminal_type\": \"PAXA920PRO\",\n \"merchant_id_alpha\": \"mer20250115075454854\"\n }\n]" }, { "name": "403 Forbidden — invalid API key", "originalRequest": { "method": "GET", "header": [ { "key": "ApiKeyCloud", "value": "INVALID-KEY" } ], "url": { "raw": "https://cloud.handpoint.{{env}}/devices", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "devices" ] } }, "status": "Forbidden", "code": 403, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\"error\":{\"statusCode\":403,\"name\":\"ForbiddenError\",\"message\":\"No valid key found in header\"}}" } ] } ] }, { "name": "Back-Office Operations", "description": "All requests in this folder go directly to the Handpoint gateway — no terminal, no cardholder interaction, no polling. Each returns a synchronous HTTP 200/400 response.\n\n**Amount units vary by endpoint:**\n- Reversal: major units decimal string (`\"10.00\"`) — or omit for full reversal\n- Remote Sale / Refund: major units decimal string (`\"10.00\"` = €10.00)\n- Tip Adjustment: major units **number** (`5` = $5.00, no quotes)\n- Pre-Auth Increase / Decrease / Capture: major units decimal string\n\n**Success check:** HTTP 200 + `httpStatus: 200` + `issuerResponseCode: \"00\"` (or `statusMessage: \"reversed\"` for Reversal). No `finStatus`.", "item": [ { "name": "Reversal", "request": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"originalGuid\": \"{{GUID}}\", // guid from the original transaction (Poll Result / Get by GUID)\n \"amount\": \"10.00\", // MAJOR units decimal string | required for partial reversal only; omit for full reversal\n \"currency\": \"{{currency}}\" // ISO 4217 | required for partial reversal only\n //,\"messageReasonCode\": \"CUSTOMER_CANCELLATION\" // optional — default: CUSTOMER_CANCELLATION\n /*\n messageReasonCode allowed values:\n CUSTOMER_CANCELLATION, UNSPECIFIED_NO_ACTION_TAKEN, SUSPECTED_MALFUNCTION,\n FORMAT_ERROR_NO_ACTION_TAKEN, COMPLETED_PARTIALLY, ORIGINAL_AMOUNT_INCORRECT,\n RESPONSE_RECEIVED_TOO_LATE, CARD_ACCEPTOR_DEVICE_UNABLE_TO_COMPLETE_TRANSACTION,\n DEPOSIT_OUT_OF_BALANCE, NO_CHECK_IN_ENVELOPE, PAYMENT_OUT_OF_BALANCE,\n DEPOSIT_OUT_OF_BALANCE_APPLIED_CONTENTS, PAYMENT_OUT_OF_BALANCE_APPLIED_CONTENTS,\n UNABLE_TO_DELIVER_MESSAGE_TO_POINT_OF_SERVICE, SUSPECTED_MALFUNCTION_CARD_RETAINED,\n SUSPECTED_MALFUNCTION_CARD_RETURNED, SUSPECTED_MALFUNCTION_TRACK_3_NOT_UPDATED,\n SUSPECTED_MALFUNCTION_NO_CASH_DISPENSED, TIMED_OUT_AT_TAKING_MONEY_NO_CASH_DISPENSED,\n TIMED_OUT_AT_TAKING_CARD_CARD_RETAINED_AND_NO_CASH_DISPENSED,\n INVALID_RESPONSE_NO_ACTION_TAKEN, TIMEOUT_WAITING_FOR_RESPONSE,\n PREMATURE_CHIP_CARD_REMOVAL, CHIP_CARD_DECLINES_TRANSACTION, SIGNATURE_TIMEOUT,\n MERCHANT_REVERSAL_SIGNATURE_DECLINED, NO_REVERSAL_REASON_CODE\n */\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/reversal", "protocol": "https", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "reversal" ] }, "description": "Reverses any transaction — sale, refund, or pre-authorization — synchronously, with no terminal or cardholder interaction required.\n\n**`originalGuid`:** the `guid` (or `efttransactionID`) from the original transaction result. Retrieve it from the Poll Result, the Get by GUID endpoint, or the `GUID` collection variable set automatically by the Poll Result test script.\n\n**Full reversal:** provide only `originalGuid`. The entire authorized amount is released.\n\n**Partial reversal:** include `amount` (major units decimal string, e.g. `\"10.00\"`) and `currency` (ISO 4217). Only the specified amount is reversed; the remainder stays settled.\n\n**`messageReasonCode`:** optional. Defaults to `CUSTOMER_CANCELLATION`. See body comments for the full list of allowed values.\n\n**Success:** HTTP 200 + `httpStatus: 200`. No `finStatus` — this is a synchronous operation. Check `statusMessage: \"reversed\"` to confirm.\n\nThis endpoint replaces `/moto/reversal`, `saleReversal`, `refundReversal`, and `preAuthorizationReversal` for all no-reader reversal scenarios." }, "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", "originalRequest": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"originalGuid\": \"{{GUID}}\", // guid from the original transaction (Poll Result / Get by GUID)\n \"amount\": \"10.00\", // MAJOR units decimal string | required for partial reversal only; omit for full reversal\n \"currency\": \"{{currency}}\" // ISO 4217 | required for partial reversal only\n //,\"messageReasonCode\": \"CUSTOMER_CANCELLATION\" // optional — default: CUSTOMER_CANCELLATION\n /*\n messageReasonCode allowed values:\n CUSTOMER_CANCELLATION, UNSPECIFIED_NO_ACTION_TAKEN, SUSPECTED_MALFUNCTION,\n FORMAT_ERROR_NO_ACTION_TAKEN, COMPLETED_PARTIALLY, ORIGINAL_AMOUNT_INCORRECT,\n RESPONSE_RECEIVED_TOO_LATE, CARD_ACCEPTOR_DEVICE_UNABLE_TO_COMPLETE_TRANSACTION,\n DEPOSIT_OUT_OF_BALANCE, NO_CHECK_IN_ENVELOPE, PAYMENT_OUT_OF_BALANCE,\n DEPOSIT_OUT_OF_BALANCE_APPLIED_CONTENTS, PAYMENT_OUT_OF_BALANCE_APPLIED_CONTENTS,\n UNABLE_TO_DELIVER_MESSAGE_TO_POINT_OF_SERVICE, SUSPECTED_MALFUNCTION_CARD_RETAINED,\n SUSPECTED_MALFUNCTION_CARD_RETURNED, SUSPECTED_MALFUNCTION_TRACK_3_NOT_UPDATED,\n SUSPECTED_MALFUNCTION_NO_CASH_DISPENSED, TIMED_OUT_AT_TAKING_MONEY_NO_CASH_DISPENSED,\n TIMED_OUT_AT_TAKING_CARD_CARD_RETAINED_AND_NO_CASH_DISPENSED,\n INVALID_RESPONSE_NO_ACTION_TAKEN, TIMEOUT_WAITING_FOR_RESPONSE,\n PREMATURE_CHIP_CARD_REMOVAL, CHIP_CARD_DECLINES_TRANSACTION, SIGNATURE_TIMEOUT,\n MERCHANT_REVERSAL_SIGNATURE_DECLINED, NO_REVERSAL_REASON_CODE\n */\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/reversal", "protocol": "https", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "reversal" ] }, "description": "Reverses any transaction — sale, refund, or pre-authorization — synchronously, with no terminal or cardholder interaction required.\n\n**`originalGuid`:** the `guid` (or `efttransactionID`) from the original transaction result. Retrieve it from the Poll Result, the Get by GUID endpoint, or the `GUID` collection variable set automatically by the Poll Result test script.\n\n**Full reversal:** provide only `originalGuid`. The entire authorized amount is released.\n\n**Partial reversal:** include `amount` (major units decimal string, e.g. `\"10.00\"`) and `currency` (ISO 4217). Only the specified amount is reversed; the remainder stays settled.\n\n**`messageReasonCode`:** optional. Defaults to `CUSTOMER_CANCELLATION`. See body comments for the full list of allowed values.\n\n**Success:** HTTP 200 + `httpStatus: 200`. No `finStatus` — this is a synchronous operation. Check `statusMessage: \"reversed\"` to confirm.\n\nThis endpoint replaces `/moto/reversal`, `saleReversal`, `refundReversal`, and `preAuthorizationReversal` for all no-reader reversal scenarios." }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"statusCode\": 400,\n \"name\": \"BadRequestError\",\n \"message\": \"Transaction already reversed\"\n }\n}" } ] }, { "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\", // Major units decimal string — \"10.00\" = $10.00 (NOT minor units)\n \"currency\": \"{{currency}}\",\n \"cardToken\": \"{{CARD_TOKEN}}\", // from saleAndTokenizeCard or GET /transactions/{{GUID}}/token\n \"transactionReference\": \"{{TXN_REF_ID}}\", // UUID v4 — generated by pre-request script\n\n // Optional:\n // \"customerReference\": \"ORDER-12345\",\n // \"billing\": {\n // \"zipCode\": \"10001\", // required within billing — cardholder billing ZIP/postal code\n // \"address\": \"123 Main St\" // optional — cardholder billing street address\n // }\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**AVS (Address Verification System):** Include a `billing` object to pass cardholder billing address for AVS. AVS must be enabled on the merchant's acquirer agreement.\n\n| Field | Required | Description |\n|---|---|---|\n| `billing.zipCode` | Yes (within billing) | Cardholder billing ZIP / postal code |\n| `billing.address` | No | Cardholder billing street address |\n\nAVS result is returned in the response as `addressVerification.resultCode` (Android SDK 7.1015.0+, MoTo path only — not present in Cloud API poll responses).\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": "200 — Remote Sale approved", "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": "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` + `guid` present. Note: `issuerResponseCode` is not returned in the remote refund response body (check `issuerResponseText` instead). No `finStatus`." }, "response": [ { "name": "200 — Refund approved", "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": "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": "Adds a tip to a completed sale before the batch closes. EPI merchants only.\n\n**`GUID`:** the `transactionID` from the sale result (the GUID variable in this collection).\n\n**`amount`:** tip in **major currency units** as a number — NOT minor units. `5` = $5.00, `5.25` = $5.25. Do NOT send `500` expecting $5.00.\n\n**Constraints:**\n- Must be called before the day's batch closes (~11 PM EST for most EPI merchants)\n- Not available on HiLite paths or Cordova\n- Not available on EmerchantPay or Paystrax (use `amount` in the original sale request for those acquirers)\n- `transactionID` must come from a SALE — not a reversal or pre-auth\n\n**On success:** HTTP 200, body `{\"statusMessage\": \"tip adjusted\"}`.\n**On failure after batch close:** HTTP 400 with error specific to acquirer." }, "response": [ { "name": "200 — tip adjusted", "originalRequest": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" } ], "url": { "raw": "https://cloud.handpoint.{{env}}/transactions/{{GUID}}/tip-adjustment", "protocol": "https", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions", "{{GUID}}", "tip-adjustment" ] }, "body": { "mode": "raw", "raw": "{\n \"amount\": 8\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"statusMessage\": \"tip adjusted\"\n}" }, { "name": "400 — Batch already closed", "originalRequest": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" }, { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\"amount\": 5}" }, "url": { "raw": "https://cloud.handpoint.{{env}}/transactions/04a25de0-3386-11f1-909c-f50efeae2190/tip-adjustment", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "transactions", "04a25de0-3386-11f1-909c-f50efeae2190", "tip-adjustment" ] } }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": {\n \"statusCode\": 400,\n \"name\": \"BadRequestError\",\n \"message\": \"Tip adjustment not available — batch has closed\"\n }\n}" } ] }, { "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": "**Preferred tokenization method:** retrieving a token via this endpoint is safer than `saleAndTokenizeCard` because it decouples the transaction approval from the tokenization step. If the token provider is unavailable at the time of the sale, `saleAndTokenizeCard` will fail the entire operation. With this endpoint, the sale completes normally and the token can be retrieved later from any approved transaction — no card re-swipe required.\n\nRetrieves a card token for a past `SALE` transaction without re-charging the cardholder. EPI only.\n\n**`GUID`:** must be the `transactionID` of a SALE-type transaction (not a reversal, refund, or pre-auth). The test script in Poll Result sets this automatically.\n\n**After a partial approval → cancel flow:** the polled `transactionID` is the reversal's ID, not the sale. Use `GET /transactions/{txnRef}/status/all` and pick the entry where `type == \"SALE\"` to find the correct GUID.\n\n**Error `3112`:** `transactionID` is not a SALE (e.g. you used a reversal ID).\n**Error `TOKENIZATION_NOT_ENABLED`:** tokenization is not configured for this merchant — contact Handpoint." }, "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": "400 — Transaction not eligible (error 3112)", "originalRequest": { "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": "**Preferred tokenization method:** retrieving a token via this endpoint is safer than `saleAndTokenizeCard` because it decouples the transaction approval from the tokenization step. If the token provider is unavailable at the time of the sale, `saleAndTokenizeCard` will fail the entire operation. With this endpoint, the sale completes normally and the token can be retrieved later from any approved transaction — no card re-swipe required.\n\nRetrieves a card token for a past `SALE` transaction without re-charging the cardholder. EPI only.\n\n**`GUID`:** must be the `transactionID` of a SALE-type transaction (not a reversal, refund, or pre-auth). The test script in Poll Result sets this automatically.\n\n**After a partial approval → cancel flow:** the polled `transactionID` is the reversal's ID, not the sale. Use `GET /transactions/{txnRef}/status/all` and pick the entry where `type == \"SALE\"` to find the correct GUID.\n\n**Error `3112`:** `transactionID` is not a SALE (e.g. you used a reversal ID).\n**Error `TOKENIZATION_NOT_ENABLED`:** tokenization is not configured for this merchant — contact Handpoint." }, "status": "Bad Request", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"error\": {\n \"statusCode\": 400,\n \"name\": \"BadRequestError\",\n \"message\": \"{\\\"errorCode\\\":3112,\\\"message\\\":\\\"Transaction type is not eligible for deferred tokenization\\\"}\",\n \"details\": {\n \"body\": {\n \"error\": {\n \"errorCode\": 3112,\n \"message\": \"Transaction type is not eligible\"\n }\n }\n }\n }\n}" } ] }, { "name": "Pre-Authorization (Back-Office)", "description": "Back-office lifecycle steps for an existing pre-authorization hold.\n\n**Pre-Authorization Create** is a card-present operation handled by your SDK integration (Android SDK, iOS SDK, PAX, or Cloud API). Once the hold is placed, use these endpoints to adjust, capture, or reverse it — no terminal required.\n\n**`originalTransactionId`:** the `efttransactionID` / `EFTTransactionID` from the Pre-Auth Create result. Set this as your `GUID` collection variable.\n\n**Supported acquirers:** EPI, EmerchantPay, Paystrax.", "item": [ { "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 the Pre-Auth Create result\n \"increaseAmount\": \"5.00\", // Major units decimal string — delta to ADD to the hold\n \"tipAmount\": \"0\" // tip component — \"0\" unless adjusting tip\n\n // To DECREASE the hold instead: add \"subtract\": \"1\"\n // \"subtract\": \"1\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "https://cloud.handpoint.{{env}}/preauthorization/increase", "protocol": "https", "host": [ "cloud", "handpoint", "{{env}}" ], "path": [ "preauthorization", "increase" ] }, "description": "Adjust (increase or decrease) a pre-authorization hold amount before capture.\n**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| `increaseAmount` | Amount to adjust the hold by, in **major units** — e.g. `\"5.00\"` = $5.00 |\n| `tipAmount` | Tip component of the adjustment — typically `\"0\"` |\n| `subtract` | `\"1\"` to decrease the hold; increase by setting `increaseAmount` positively |\n\n**Error 3211:** Pre-auth already captured, voided, or not found." }, "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)", "originalRequest": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" } ], "url": { "raw": "https://cloud.handpoint.{{env}}/preauthorization/increase", "protocol": "https", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "preauthorization", "increase" ] }, "body": { "mode": "raw", "raw": "{\n \"originalGuid\": \"{{GUID}}\",\n \"increaseAmount\": \"5.00\",\n \"tipAmount\": \"0\",\n \"subtract\": \"1\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Error", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "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 \"details\": {\n \"errorCode\": \"3211\",\n \"httpStatus\": 403,\n \"reason\": \"Original pre-auth is voided, not approved or already captured\"\n }\n }\n}" } ] }, { "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)", "originalRequest": { "method": "POST", "header": [ { "key": "ApiKeyCloud", "value": "{{api_key}}" } ], "url": { "raw": "https://cloud.handpoint.{{env}}/preauthorization/capture", "protocol": "https", "host": [ "cloud.handpoint.{{env}}" ], "path": [ "preauthorization", "capture" ] }, "body": { "mode": "raw", "raw": "{\n \"originalGuid\": \"{{GUID}}\",\n \"capturedAmount\": \"45.00\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Error", "code": 400, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "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 \"details\": {\n \"errorCode\": \"3211\",\n \"httpStatus\": 403,\n \"reason\": \"Original pre-auth is voided, not approved or already captured\"\n }\n }\n}" } ] } ] }, { "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": "400 — Already Closed (NOT ALLOWED, code 03)", "status": "Bad Request", "code": 400, "body": "{\n \"error\": {\n \"statusCode\": 400,\n \"name\": \"BadRequestError\",\n \"message\": \"Viscus operation failed\",\n \"details\": {\n \"status\": 403,\n \"body\": {\n \"closebatch\": {\n \"httpStatus\": \"403\",\n \"batchNumber\": \"63\",\n \"closeBatchGuid\": \"34645ff0-bcb2-11f1-a903-a92d2c2c7176\",\n \"issuerResponseCode\": \"03\",\n \"issuerResponseText\": \"NOT ALLOWED\",\n \"batchStatus\": \"CLOSED\"\n }\n }\n }\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "400 — Not Found (COULD NOT FIND, code 02)", "status": "Bad Request", "code": 400, "body": "{\n \"error\": {\n \"statusCode\": 400,\n \"name\": \"BadRequestError\",\n \"message\": \"Viscus operation failed\",\n \"details\": {\n \"status\": 403,\n \"body\": {\n \"closebatch\": {\n \"httpStatus\": \"403\",\n \"issuerResponseCode\": \"02\",\n \"issuerResponseText\": \"COULD NOT FIND\",\n \"batchStatus\": \"UNKNOWN\"\n }\n }\n }\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "422 — Missing Required Field", "status": "Unprocessable Entity", "code": 422, "body": "{\n \"error\": {\n \"statusCode\": 422,\n \"name\": \"UnprocessableEntityError\",\n \"code\": \"VALIDATION_FAILED\",\n \"message\": \"The request body is invalid. See error object `details` property for more info.\",\n \"details\": [\n {\n \"code\": \"required\",\n \"info\": {\n \"missingProperty\": \"serialNumber\"\n },\n \"message\": \"must have required property 'serialNumber'\",\n \"path\": \"\"\n }\n ]\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] }, { "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": "400 — Not Found (COULD NOT FIND, code 02)", "status": "Bad Request", "code": 400, "body": "{\n \"error\": {\n \"statusCode\": 400,\n \"name\": \"BadRequestError\",\n \"message\": \"Viscus operation failed\",\n \"details\": {\n \"status\": 403,\n \"body\": {\n \"batchSummary\": {\n \"httpStatus\": \"403\",\n \"batchNumber\": \"63\",\n \"closedAt\": \"20260930093438487\",\n \"issuerResponseCode\": \"02\",\n \"issuerResponseText\": \"COULD NOT FIND\",\n \"batchSummaryGuid\": \"770bf930-bcb2-11f1-a72f-8761c875e91c\",\n \"batchStatus\": \"CLOSED\"\n }\n }\n }\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "422 — Missing Required Field", "status": "Unprocessable Entity", "code": 422, "body": "{\n \"error\": {\n \"statusCode\": 422,\n \"name\": \"UnprocessableEntityError\",\n \"code\": \"VALIDATION_FAILED\",\n \"message\": \"The request body is invalid. See error object `details` property for more info.\",\n \"details\": [\n {\n \"code\": \"required\",\n \"info\": {\n \"missingProperty\": \"serialNumber\"\n },\n \"message\": \"must have required property 'serialNumber'\",\n \"path\": \"\"\n }\n ]\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": "400 — Not Found (COULD NOT FIND, code 02)", "status": "Bad Request", "code": 400, "body": "{\n \"error\": {\n \"statusCode\": 400,\n \"name\": \"BadRequestError\",\n \"message\": \"Viscus operation failed\",\n \"details\": {\n \"status\": 403,\n \"body\": {\n \"batchDetail\": {\n \"httpStatus\": \"403\",\n \"issuerResponseCode\": \"02\",\n \"issuerResponseText\": \"COULD NOT FIND\",\n \"batchDetailGuid\": \"d5206e00-bcb9-11f1-a903-a92d2c2c7176\",\n \"batchStatus\": \"UNKNOWN\"\n }\n }\n }\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} }, { "name": "422 — Missing Required Field", "status": "Unprocessable Entity", "code": 422, "body": "{\n \"error\": {\n \"statusCode\": 422,\n \"name\": \"UnprocessableEntityError\",\n \"code\": \"VALIDATION_FAILED\",\n \"message\": \"The request body is invalid. See error object `details` property for more info.\",\n \"details\": [\n {\n \"code\": \"required\",\n \"info\": {\n \"missingProperty\": \"serialNumber\"\n },\n \"message\": \"must have required property 'serialNumber'\",\n \"path\": \"\"\n }\n ]\n }\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] } ] }, { "name": "Transaction Feed (Reporting)", "description": "Query the Handpoint Transaction Feed to retrieve and search transaction history.\n\n**`AnalyticsApiKey` header:** same value as your `ApiKeyCloud` API key — set the `analytics_key` collection variable to your API key. Do NOT leave it as `{{api_key}}` — the Transaction Feed requires the `AnalyticsApiKey` header, not `ApiKeyCloud`.\n\n**Response format:** Transaction Feed fields differ from Cloud API poll results (e.g. `guid` not `transactionID`, `currCode` not `currency`, `type: \"Sale\"` not `\"SALE\"`). See the Get Transaction by GUID request for the field mapping.\n\n**`GUID`:** set the collection variable to look up a specific transaction by its gateway identifier.", "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": "Retrieves a single transaction record from the Transaction Feed by its `guid` (the GUID variable).\n\n**Note:** The Transaction Feed uses different field names than the Cloud API poll result:\n\n| Transaction Feed field | Cloud API poll result equivalent |\n|---|---|\n| `guid` | `transactionID` |\n| `transactionReference` | `transactionReference` (same) |\n| `currCode` | `currency` |\n| `type` | `type` (different values: `\"Sale\"` vs `\"SALE\"`) |\n| `paymentScenario` | `paymentScenario` (same) |\n| `maskedCardNumber` | `maskedCardNumber` (different mask format — BIN shown here) |\n\n**`AnalyticsApiKey`** — same value as `ApiKeyCloud`; set the `analytics_key` collection variable to your API key.\n\nUseful for UNDEFINED recovery when you have the `guid` and need to confirm settlement status via the feed." }, "response": [ { "name": "200 — Transaction detail", "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": "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": "Searches the transaction feed by time range and optional filters. Primary use case: UNDEFINED recovery when `transactionReference` recovery is unavailable.\n\n**`AnalyticsApiKey`** — same value as `ApiKeyCloud`; set the `analytics_key` collection variable.\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)." }, "response": [ { "name": "200 OK — results", "status": "OK", "code": 200, "body": "{\n \"transactions\": [\n {\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 }\n ],\n \"total\": 1\n}", "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "originalRequest": {} } ] } ] } ] }