Skip to main content

PAYSAFE

Integration Capabilities

CapabilityCloud APINative PAXHiLiteBack Office
Sale✓✓✓—
Refund✓✓✓—
Reversal✓✓✓✓
Tip Adjustment✓✓✓✓
Pre-Authorization✓✓—✓
MOTO✓✓——
Tokenization✓✓✓—
Void✓✓✓—
Interac✓✓——

✓ Supported  — Not available on this path

Sale​

EMV Sale​

On-device · chip, contactless, or magstripeCloud APIAndroid (PAX)Android (HiLite)iOS (HiLite)CordovaJavaScript SDKWindows (.NET)

Standard chip or contactless card-present payment — the cardholder taps, inserts, or swipes their card at the terminal. The terminal handles card entry mode automatically.

When to use it​

Use for standard retail and hospitality transactions where the cardholder is physically present and the amount is fixed before checkout. For a final amount that may change after authorisation (e.g. restaurant tab), use Pre-Authorization instead.

Code​

POST https://cloud.handpoint.com/transactions
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "operation": "sale",
  "amount": "1000",
  "currency": "USD",
  "terminal_type": "PAXA920",
  "serial_number": "082104578",
  "customerReference": "order-5248",
  "transactionReference": "2bfde1fc-23b1-4c67-93d9-1d4a557f4d4f"
}

Amount is in the smallest currency unit — "1000" = $10.00 USD. The 202 response returns a transactionResultId — poll GET /transaction-result/{transactionResultId} on cloud.handpoint.com for the outcome. Your transactionReference UUID v4 can also be used to query the full operation chain via GET /transactions/{transactionReference}/status/all on transactions.handpoint.com.

Parameters​

NameTypeRequiredDescription
operationstringYesMust be "sale"
amountstringYesSmallest currency unit as a string — "1000" = $10.00
currencystringYesISO 4217 code, e.g. "USD", "EUR", "CAD"
terminal_typestringYesTerminal model, e.g. "PAXA920"
serial_numberstringYesTarget terminal serial number
transactionReferencestringNoUUID v4 — send on original transactions only; omit on reversals and linked refunds
customerReferencestringNoMerchant reference forwarded to the acquirer
callbackUrlstringNoURL to receive the result via POST; if omitted, poll GET /transaction-result/{id}
tokenstringNoOpaque value included with the push notification. Only used when callbackUrl is set
taxInformationobjectNoLevel 2 tax data: taxAmount (string, minor units) and taxExempt (boolean). taxAmount is required: "0" when taxExempt is true, greater than "0" otherwise, and never above amount. Must be sent with purchaseOrderNumber
purchaseOrderNumberstringNoLevel 2 purchase order number. Must be sent with taxInformation. Alphanumeric, max 25 characters

Errors​

CodeMeaningRecovery
DECLINEDIssuer declinedAsk cardholder to try another card
CANCELLEDCardholder cancelled at terminalNo action required
TIMEOUTTerminal did not respondCheck connection; retry
COMMUNICATION_ERRORNetwork failureVerify connectivity; retry
PARTIAL_APPROVALIssuer approved a lesser amountAccept partial amount or reverse; see Partial Approval

Edge cases​

ScenarioBehaviour
Contactless limit exceededTerminal falls back to chip insert — instruct the cardholder to insert their card
Card chip read failureTerminal retries up to 3 times, then offers magstripe fallback — acquirer support for swipe varies
Duplicate detectionIf checkDuplicates is enabled and the same card + amount is seen within the window, the gateway rejects the second transaction
Connection drops mid-salePersist transactionReference before awaiting the result — query GET /transactions/{transactionReference}/status/all to recover the outcome

Testing​

Test on the TEST/DEMO merchant or staging device. Use test cards provided by your acquirer for specific scenarios.

ScenarioHow to trigger
ApprovedSend a valid request — verify finStatus: AUTHORISED, note transactionID for reversal tests
DeclinedUse acquirer test card for decline — verify finStatus: DECLINED
Partial approvalUse acquirer test card for partial approval — verify finStatus: PARTIAL_APPROVAL and that your app handles it
Timeout recoveryDrop connectivity mid-transaction — query GET /transactions/{transactionReference}/status/all to confirm outcome

Key Entry Sale​

On-device · operator keys card numberCloud APIAndroid (PAX)JavaScript SDKWindows (.NET)

Commands a PAX terminal to display a manual card entry screen — the cashier types the cardholder's card number, expiry, and CVV directly on the terminal's touchscreen. The terminal tokenizes the entry internally and processes it as a MOTO transaction. The ISV system never handles raw card data.

Processed as MOTO — acquirer fees apply

Despite using a physical PAX terminal, Key Entry Sale is submitted to the acquirer as a MOTO (card-not-present) transaction, not as a card-present key-entry transaction. This is because the card is manually entered rather than electronically read. MOTO transactions typically carry higher interchange rates than card-present transactions. Confirm the fee structure with your acquirer during merchant onboarding.

When to use it​

Use for phone orders where the cardholder reads their card details aloud to a call centre agent, or in-person situations where the card cannot be read electronically. The PAX terminal must be present in your environment and running in integrated mode.

Card data stays on the terminal

Unlike back-office MOTO (which uses a stored card token), key entry sale requires the PAX terminal to be physically present. The operator's system sends the command; the terminal's screen collects the card details.

Code​

POST https://cloud.handpoint.com/transactions
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "operation": "moToSale",
  "amount": "1000",
  "currency": "USD",
  "terminal_type": "PAXA920",
  "serial_number": "082104578",
  "transactionReference": "2bfde1fc-23b1-4c67-93d9-1d4a557f4d4f"
}

Amount in smallest currency unit. The terminal shows a card entry screen — the operator types card details on device.

Parameters​

NameTypeRequiredDescription
operationstringYesMust be "moToSale" — triggers card entry screen on terminal
amountstringYesAmount in smallest currency unit — "1000" = $10.00
currencystringYesISO 4217 code, e.g. "USD"
terminal_typestringYesTerminal model, e.g. "PAXA920"
serial_numberstringYesPAX terminal serial number
transactionReferencestringNoUUID v4 for idempotency and status queries
taxInformationobjectNoLevel 2 tax data: taxAmount (string, minor units) and taxExempt (boolean). taxAmount is required: "0" when taxExempt is true, greater than "0" otherwise, and never above amount. Must be sent with purchaseOrderNumber
purchaseOrderNumberstringNoLevel 2 purchase order number. Must be sent with taxInformation. Alphanumeric, max 25 characters

Errors​

CodeMeaningRecovery
DECLINEDIssuer declinedAsk cardholder to provide another card
CANCELLEDOperator cancelled on terminalNo action required
MOTO_NOT_ENABLEDMOTO not enabled for this merchantContact Handpoint team

Remote Sale (MOTO)​

Back-office · charges a stored card tokenAndroid (PAX)CordovaBackoffice

A card-not-present sale submitted directly to the gateway using a stored card token — no terminal or card reader required. The ISV system sends the charge via REST API or Android SDK using a token previously issued by a supported token provider.

When to use it​

Use for recurring billing, subscription charges, or any scenario where you hold a card-on-file token from a prior tokenization or card-present transaction. A card token must already exist before this operation can be sent.

How to obtain a card token​

MethodHowWhen to use
Sale & Tokenize (saleAndTokenizeCard)Charges the card and issues a token in one stepOnly when getting the token alongside the sale is a hard requirement — if the tokenization step fails, the entire authorisation also fails
Tokenize Only (tokenizeCard)No charge — reads the card and stores a tokenLoyalty enrolment, "save my card" flows, or any time you need a token without a payment
Deferred — GET token after sale (recommended)Do a regular sale, then call GET /transactions/{id}/token (Backoffice REST, no terminal needed)Preferred for recurring billing — decouples the token from the sale; a tokenisation failure doesn't affect the transaction result

The deferred approach is recommended because the card-present sale completes independently. You call the backoffice token endpoint afterwards and store the token for future card-not-present charges.

No raw card data — tokens only

Handpoint back-office MOTO does not accept raw PAN, expiry, or CVV from the ISV. All charges use a cardToken issued by a supported provider (e.g. Paysafe, Tokenex). The token provider de-tokenizes at processing time — the ISV never handles card data.

Code​

Back-office sale — no terminal required, amount in major currency units. Synchronous — the result is returned immediately; no polling or callback URL needed.

POST https://cloud.handpoint.com/moto/sale
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "amount": "10.00",
  "currency": "USD",
  "cardToken": "YOUR_STORED_CARD_TOKEN",
  "transactionReference": "538f1ee7-9f6f-49b7-8a49-89f7cc3aaad9"
}

Parameters​

Amount in major currency units — "10.00" = $10.00. Synchronous — result returned immediately in the response body.

NameTypeRequiredDescription
amountstringYesAmount in major currency units — "10.00" = $10.00. Must match ^\d+(\.\d+)?$, otherwise 422; within that, at most 12 digits, or 13 characters with a decimal point, no leading zeros except a single 0 before the decimal point, as in 0.50, otherwise 400
currencystringYesISO 4217 code, e.g. "USD"
cardTokenstringYesCard-on-file token from a supported provider — never a raw PAN
transactionReferencestringRecommendedUUID v4 for idempotency and recovery via GET /transactions/{reference}/status/all
customerReferencestringNoMerchant reference forwarded to the acquirer
taxInformationobjectNoLevel 2 tax data: taxAmount (string, major currency units, e.g. "1.00"; at most 12 digits, or 13 characters with a decimal point, no leading zeros except a single 0 before the decimal point, as in 0.50) and taxExempt (boolean). taxAmount is required: "0" when taxExempt is true, greater than "0" otherwise, and never above amount. Must be sent with purchaseOrderNumber
purchaseOrderNumberstringNoLevel 2 purchase order number. Must be sent with taxInformation. Alphanumeric, max 25 characters

Errors​

CodeMeaningRecovery
DECLINEDIssuer declinedRequest another payment method from the customer
INVALID_TOKENToken not recognised or expiredVerify token and token provider match acquirer
MOTO_NOT_ENABLEDMOTO not provisioned for this merchantContact Handpoint team
400 (validation)Invalid amount format, or invalid taxInformation / purchaseOrderNumberFix the field — see Level 2 validation errors

Sale with Tip​

On-device · tip collected at checkoutCloud APIAndroid (PAX)Android (HiLite)CordovaJavaScript SDKWindows (.NET)

Configure a tip prompt on the terminal as part of the sale — the cardholder selects a tip amount before completing payment. This is distinct from Tip Adjustment (which adds a tip after the sale is authorised).

When to use it​

Use in hospitality environments (restaurants, taxis, salons) where tipping is expected at point of sale. The tip is collected at the terminal, included in the authorised amount, and settled together with the base sale — no second operation is needed.

Code​

POST https://cloud.handpoint.com/transactions
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "operation": "sale",
  "amount": "1000",
  "currency": "USD",
  "terminal_type": "PAXA920",
  "serial_number": "082104578",
  "tipConfiguration": {
    "baseAmount": "1000",
    "tipPercentages": [10, 15, 20],
    "enterAmountEnabled": true,
    "skipEnabled": true,
    "footer": "Thank you!"
  },
  "transactionReference": "2bfde1fc-23b1-4c67-93d9-1d4a557f4d4f"
}

baseAmount is used to calculate the percentage amounts displayed. enterAmountEnabled: true lets the cardholder type a custom tip. skipEnabled: true adds a "No tip" option.

TipConfiguration fields​

FieldTypeDescription
baseAmountstring / BigIntegerBase sale amount used to calculate percentage tip values shown on screen
tipPercentagesarray of integersTip percentage options to display, e.g. [10, 15, 20]
enterAmountEnabledbooleantrue to show a "Custom amount" entry option
skipEnabledbooleantrue to show a "No tip / Skip" option
footerstringOptional message shown at the bottom of the tip screen

Result fields​

FieldDescription
tipAmountTip amount chosen by the cardholder (minor units)
totalAmountBase amount + tip — what was authorised and will settle

Pre-selected tip (ISV-collected)​

Use this variant when your application has already collected the tip from the cardholder — for example, your POS shows a custom tip screen and the cardholder selects a tip amount before the card is presented. Pass TipConfiguration(tipAmount) with the pre-determined amount; the terminal skips its own tip-selection screen and charges base + tip in a single authorisation.

POST https://cloud.handpoint.com/transactions
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "operation": "sale",
  "amount": "1000",
  "currency": "USD",
  "terminal_type": "PAXA920",
  "serial_number": "082104578",
  "tipConfiguration": {
    "tipAmount": "500"
  },
  "transactionReference": "2bfde1fc-23b1-4c67-93d9-1d4a557f4d4f"
}

The terminal charges amount + tipAmount in a single authorisation. No tip-selection screen is shown on the terminal.

Tip Adjustment vs Sale with Tip

Sale with Tip collects the tip at the terminal before authorisation — the total (base + tip) is authorised in one step. Tip Adjustment adds a tip after an already-authorised sale, updating the settlement amount. Use Sale with Tip when the cardholder is at the terminal; use Tip Adjustment for tip-at-table flows where you capture a signature and enter the tip later.

Errors​

CodeMeaningRecovery
DECLINEDIssuer declined (after tip selection)Ask cardholder to try another card
CANCELLEDCardholder cancelled at tip screen or payment screenNo action required — no amount was authorised
TIMEOUTTerminal did not respondCheck connection; retry
COMMUNICATION_ERRORNetwork failureVerify connectivity; retry

Edge cases​

ScenarioBehaviour
Cardholder skips tiptipAmount is 0 or absent in the result; totalAmount equals the base amount
baseAmount differs from sale amountTip percentages are calculated on baseAmount — use this intentionally (e.g. to exclude tax from the tip base)
Pre-selected tip + card declineFull amount + tipAmount was attempted; no partial capture — treat as a standard decline

Testing​

Test on the TEST/DEMO merchant or staging device.

ScenarioHow to trigger
Tip from percentageSet tipPercentages: [10, 15, 20] — select a percentage at terminal — verify tipAmount and totalAmount in result
Custom tipSet enterAmountEnabled: true — enter a custom amount — verify totalAmount = baseAmount + entered tip
Skip tipSet skipEnabled: true — select No Tip — verify tipAmount: 0, totalAmount equals base
Pre-selected tipPass TipConfiguration(tipAmount: 500) — verify terminal skips tip screen, totalAmount = amount + 500
Cardholder cancelsCancel at tip screen — verify CANCELLED and no charge

Sale with Paysafe Token​

On-device · captures a Paysafe single-use token for Customer Vault APICloud APIAndroid (PAX)Android (HiLite)iOS (HiLite)CordovaJavaScript SDKWindows (.NET)

Charge the card and simultaneously capture a Paysafe single-use token — a short-lived, one-time credential that lets you securely pass card data to Paysafe's Customer Vault API without your server ever handling the raw PAN.

Paysafe-ecosystem token — not for Handpoint MOTO

This token is intended for use on Paysafe's Customer Vault API, not Handpoint's Remote Sale (MOTO) endpoint. Handpoint Gateway does not detokenize Paysafe single-use tokens for MOTO processing.

Contact the Paysafe team before building a token-based flow to confirm the token format Handpoint returns meets your integration requirements.

When to use it​

Use when onboarding a customer in person — take the first payment as a normal card-present sale and simultaneously capture a Paysafe single-use token. Your system then calls the Paysafe Customer Vault API to vault the card and receive a permanent paymentToken for future recurring charges.

Code​

POST https://cloud.handpoint.com/transactions
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "operation": "saleAndTokenizeCard",
  "amount": "1000",
  "currency": "USD",
  "terminal_type": "PAXA920",
  "serial_number": "082104578",
  "transactionReference": "2bfde1fc-23b1-4c67-93d9-1d4a557f4d4f"
}

The cardToken in the result is a Paysafe single-use token — pass it to the Paysafe Customer Vault API. It is not for use with Handpoint's /moto/sale endpoint.

Result fields​

FieldDescription
cardTokenPaysafe single-use token — pass to Paysafe Customer Vault API; not for Handpoint MOTO
cardTokenProvider"PAYSAFE"
finStatusAUTHORISED on success

Using the token​

Pass the single-use token to Paysafe's Customer Vault API to vault the card and receive a permanent paymentToken for future recurring charges. The single-use token expires in ~15 minutes — vault it promptly.

For implementation details, see the Paysafe Single-Use Token section in Tokenization.

Token scope

Paysafe tokens are specific to the merchant configuration. Test tokens (from api.test.paysafe.com) are not valid in production.

Refund​

EMV Refund​

On-device · card present at terminalCloud APIAndroid (PAX)Android (HiLite)iOS (HiLite)CordovaJavaScript SDKWindows (.NET)

Returns funds to a cardholder's account for a card-present transaction. The cardholder must present their payment method at the terminal.

Linked refund (recommended): includes originalTransactionId — the gateway validates the original transaction and caps the refund at the original amount. Include partial amounts for partial refunds.

Unlinked refund: omit originalTransactionId — sends a standalone credit without referencing the original sale. Some acquirers restrict unlinked refunds; check your acquirer agreement.

Same payment method

Per merchant configuration, the same card used in the original sale must be presented. Physical card inserts and mobile wallet taps (Apple Pay, Google Pay) produce different PAN tokens — if same-card verification is enabled and the original sale was a physical insert, a wallet tap at refund time will decline. Advise the cardholder to use the same payment method they used at purchase.

When to use it​

Use for returns after settlement has occurred. For cancellations of unsettled transactions, use Reversal — it is faster and incurs no interchange fees.

Code​

Linked refund (no transactionReference — subsequent operation):

POST https://cloud.handpoint.com/transactions
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "operation": "refund",
  "amount": "1000",
  "currency": "USD",
  "terminal_type": "PAXA920",
  "serial_number": "082104578",
  "originalTransactionId": "01236fc0-8192-11eb-9aca-ad4b0e95f241"
}

Unlinked refund (include transactionReference — original operation):

POST https://cloud.handpoint.com/transactions
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "operation": "refund",
  "amount": "1000",
  "currency": "USD",
  "terminal_type": "PAXA920",
  "serial_number": "082104578",
  "transactionReference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Parameters​

NameTypeRequiredDescription
operationstringYesMust be "refund"
amountstringYesRefund amount in smallest currency unit. Can be less than original for a partial refund
currencystringYesISO 4217 code — must match original sale
terminal_typestringYesTerminal model, e.g. "PAXA920"
serial_numberstringYesTarget terminal serial number
originalTransactionIdstringLinked onlytransactionID from the original sale result. Do NOT combine with transactionReference
transactionReferencestringUnlinked onlyUUID v4 — include on unlinked refunds; omit on linked refunds

Errors​

CodeMeaningRecovery
DECLINEDAmount exceeds original or issuer declinedReduce amount to at most original totalAmount; contact acquirer support
ORIGINAL_NOT_FOUNDoriginalTransactionId not foundVerify the GUID is the transactionID from the sale result, not eFTTransactionID
UNLINKED_REFUND_NOT_ALLOWEDAcquirer does not permit unlinked refundsAlways include originalTransactionId for this acquirer
TIMEOUTTerminal did not respondCheck connection; retry
COMMUNICATION_ERRORNetwork failureVerify connectivity; retry

Edge cases​

ScenarioBehaviour
Partial refundSend less than the original totalAmount — acquirer caps at the original amount; do not exceed it
Multiple partial refundsEach linked refund reduces the refundable balance; sending more than the cumulative remaining amount will decline
Wallet vs physical cardIf same-card verification is enabled, Apple Pay / Google Pay taps produce different PAN tokens from a physical card insert — the cardholder must use the same payment method as the original sale
Refund of a tipped saleInclude the full totalAmount (base + tip) if refunding the whole transaction; a partial refund should target the base only unless the acquirer allows tip refunds
Already settledLinked refunds work post-settlement — this is the correct path after batch close

Testing​

Test on the TEST/DEMO merchant or staging device.

ScenarioHow to trigger
Full linked refundComplete a sale, then send a refund with originalTransactionId for the full amount — verify AUTHORISED
Partial linked refundSend refund for less than the original amount — verify AUTHORISED and correct totalAmount
Over-amount linked refundSend refund for more than the original amount — verify DECLINED
Unlinked refundOmit originalTransactionId, include transactionReference — verify acquirer allows it

Remote Refund (MOTO)​

Back-office · linked to original MOTO saleAndroid (PAX)CordovaBackoffice

A card-not-present refund submitted directly to the gateway — no terminal or card reader required. References the original MOTO sale by its GUID. Valid up to 12 months after the original sale date.

When to use it​

Use to refund a previously processed back-office MOTO or key-entry sale. The cardholder does not need to be present or provide their card again — the gateway retrieves the card from the original transaction.

Code​

Synchronous — the result is returned immediately. No terminal, no polling.

POST https://cloud.handpoint.com/moto/refund
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "amount": "10.00",
  "currency": "USD",
  "originalGuid": "01236fc0-8192-11eb-9aca-ad4b0e95f241"
}

originalGuid is the efttransactionID (or transactionID) from the original MOTO sale result. Amount is in major currency units — "10.00" = $10.00. Do not include transactionReference on refunds (linked operation).

Parameters​

Amount in major currency units — "10.00" = $10.00. Synchronous — result returned immediately.

NameTypeRequiredDescription
amountstringYesRefund amount in major currency units — "10.00" = $10.00
currencystringYesISO 4217 code, e.g. "USD"
originalGuidstringYesefttransactionID from the original MOTO sale. Gateway retrieves the card token — do not pass cardToken on refunds

Errors​

CodeMeaningRecovery
DECLINEDAmount exceeds original or issuer declinedReduce to at most the original amount
ORIGINAL_NOT_FOUNDoriginalGuid not foundVerify the GUID is from the MOTO sale result
MOTO_NOT_ENABLEDMOTO not provisionedContact Handpoint team

Reversal​

Reversal​

On-device · no card requiredCloud APIAndroid (PAX)Android (HiLite)iOS (HiLite)CordovaJavaScript SDKWindows (.NET)

What this does​

Cancels an unsettled transaction before batch settlement — the full authorised amount is released to the cardholder without interchange fees. No card present required.

When to use it​

Use when a transaction needs to be cancelled before the batch closes (same business day, before cut-off time). This is always preferable to a post-settlement Refund — faster and fee-free. Do NOT use after settlement — send a Refund instead.

Implementation notes​

  1. Same business day only. Reversal works on the current open batch only. Once the batch closes (cut-off time, typically end of business day), the transaction settles and only a post-settlement Refund is available.
  2. No card present required. Reversal references the original transactionID electronically — the cardholder does not need to return to the terminal.
  3. Terminal must be online. The SDK paths route the reversal through the connected reader — the terminal must be reachable at the time of the call.

Code​

Routes through the connected terminal SDK — the reversal is processed by the device and appears in the device app transaction history. Asynchronous — poll GET /transaction-result/{transactionResultId} for the outcome. Amount in minor units.

POST https://cloud.handpoint.com/transactions
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "operation": "saleReversal",
  "amount": "1100",
  "currency": "USD",
  "terminal_type": "PAXA920",
  "serial_number": "0821599465",
  "originalTransactionId": "f2075470-9194-11f1-90c9-a73194216a3b"
}

Response:

{
  "statusMessage": "Operation Accepted",
  "transactionResultId": "0821599465-1786020446467"
}

Parameters​

Routes through the terminal. Amount in minor units (e.g. "1100" = $11.00). Asynchronous — poll GET /transaction-result/{transactionResultId}.

NameTypeRequiredDescription
operationstringYesMust be "saleReversal"
amountstringYesFull original sale amount in minor units as a string, e.g. "1100" = $11.00
currencystringYesISO 4217 currency code — must match the original sale
terminal_typestringYesTerminal model, e.g. "PAXA920"
serial_numberstringYesTerminal serial number
originalTransactionIdstringYestransactionID from the original sale result
callbackUrlstringNoURL to receive the result via HTTP POST. If omitted, poll GET /transaction-result/{transactionResultId}
tokenstringNoOpaque value included with the push notification. Only used when callbackUrl is set

Errors​

Errors arrive in the polled result object, not in the initial 202. Check finStatus — do not parse statusMessage for programmatic logic as it can be localized.

finStatusstatusMessageMeaningWhat to do
DECLINEDUNABLE_TO_FIND_MESSAGE_TO_REVERSE.originalTransactionId not found in the open batchVerify the GUID; if the batch has closed, send a Refund instead
FAILEDTransaction failed, error: Error getting advanced transaction status...originalTransactionId not found (pre-auth reversal path)Verify the GUID is from the pre-auth create result

Immediate HTTP errors (returned before the 202):

HTTPmessageMeaningWhat to do
403No valid key found in headerInvalid API keyCheck ApiKeyCloud header value
400{"error":1001,"message":"Device is busy"}Terminal is processing another operationWait and retry; implement a short backoff

Testing​

Test reversals on the TEST/DEMO merchant or staging device.

ScenarioHow to trigger
SuccessComplete a sale, send POST /transactions same day — verify AUTHORISED via GET /transaction-result/{id}
After cut-offClose the batch, attempt reversal — verify error and route to Refund
Already reversedSend the same reversal twice — verify idempotent or ALREADY_REVERSED response

Remote Reversal​

Back-office · no reader requiredCloud APIBackoffice
Cloud API vs. Backoffice — what's the difference?
PathHow it worksTransaction history
Cloud APIRoutes through the connected terminal SDK — the device processes the reversalAppears in device app transaction history
BackofficeSends directly to the payment gateway — no terminal or SDK involvedAppears in your POS/solution only — not in the device app

Both paths use the same ApiKeyCloud credential.

What this does​

Cancels any unsettled transaction — sale, MOTO, pre-auth capture, or refund — without the cardholder returning to the terminal.

When to use it​

  • Cloud API path: Use when you have a terminal online and want the reversal recorded in the device transaction history.
  • Backoffice path: Use when the terminal is unavailable, or when the original transaction was fully server-side (MOTO, pre-auth via Cloud API). No MOTO or TMS enablement required for full reversals.

Implementation notes​

  1. Backoffice amount is in major units (decimal string) — e.g. "11.00" for $11.00. Cloud API uses minor units (integer string).
  2. Omit amount and currency for a full reversal. Include them only for a partial reversal (EPI only — requires TMS enablement per merchant).
  3. Do NOT include a transactionReference on either path — this is a subsequent operation linked to the original.
  4. Interac cards (Paysafe + Interac gateway only): Remote reversal is not available for Interac card transactions. Interac requires card-present at terminal. Use the on-device Reversal flow instead. Non-Interac cards on the same gateway work normally.

Code​

Routes through the connected terminal SDK. Asynchronous — poll GET /transaction-result/{transactionResultId} for the outcome. The reversal appears in the device app transaction history.

POST https://cloud.handpoint.com/transactions
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "operation": "saleReversal",
  "amount": "1100",
  "currency": "USD",
  "terminal_type": "PAXA920",
  "serial_number": "0821599465",
  "originalTransactionId": "f2075470-9194-11f1-90c9-a73194216a3b"
}

Response:

{
  "statusMessage": "Operation Accepted",
  "transactionResultId": "0821599465-1786020446467"
}

For parameters, async result polling, and error codes — see the Reversal section above.

Parameters​

Routes through the terminal — same parameters as the on-device Reversal. Amount in minor units (e.g. "1100" = $11.00).

NameTypeRequiredDescription
operationstringYesMust be "saleReversal"
amountstringYesOriginal sale amount in smallest currency unit, e.g. "1100" = $11.00
currencystringYesISO 4217 code — must match the original sale
terminal_typestringYesTerminal model, e.g. "PAXA920"
serial_numberstringYesTerminal serial number
originalTransactionIdstringYestransactionID from the original transaction result

Errors​

Errors arrive in the polled result — see Reversal — Errors.

Testing​

Same test scenarios as on-device Reversal — see Reversal — Testing.

Tip Adjustment​

Post-authorization · adjust tip before batch closeAndroid (PAX)Android (HiLite)CordovaBackoffice

Modifies the tip amount on a completed sale before batch close. Used in restaurant/hospitality flows where the cardholder signs a paper receipt and adds a tip after the initial authorization.

Full guide

For acquirer restrictions, batch-close deadline, cross-SDK usage, iOS HiLite specifics, and the Sale with Tip vs Tip Adjustment comparison, see the Tipping Guide.

Tip adjustment + partial refund ordering

If you need to perform a partial refund on a transaction that already has a tip adjustment, follow this sequence:

  1. Send a $0 tip adjustment to zero out the existing tip
  2. Perform the partial refund
  3. Send a new tip adjustment for the correct tip amount on the remaining balance

Why: This acquirer's backend links the tip to the original authorization amount. A partial refund against a tipped transaction can produce incorrect settlement figures unless the tip is zeroed first. Sending a new tip adjustment after the refund restores the correct tip on the adjusted balance.

PAYSAFE

PAYSAFE merchants may be onboarded on TSYS, TNS, or both. When a merchant has both processors configured, the Handpoint gateway routes based on card type: Interac cards → TNS (card-present only), all other cards → TSYS. INTERAC VOID: For Interac card transactions, show VOID in your UI — not Refund or Reverse. The only post-sale correction is VOID (full amount, card must be present at terminal). Standard refund is not available for Interac. BATCHING: Batch close applies to TSYS (non-Interac) transactions only. TNS (Interac) transactions settle independently and do not participate in the TSYS batch. Paysafe single-use token: requires merchant onboarding by Paysafe/Handpoint before use.

Code​

Synchronous — the gateway responds immediately. No terminal, no polling.

POST https://cloud.handpoint.com/transactions/01236fc0-8192-11eb-9aca-ad4b0e95f241/tip-adjustment
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "amount": 9.00
}

The transactionID from the original sale goes in the URL path. To void a tip, send "amount": 0.

Parameters​

Amount in major currency units — 9.00 = $9.00. Synchronous — result returned immediately.

NameTypeRequiredDescription
{transactionID}string (path)YestransactionID from the original sale result (in the URL path)
amountnumberYesTip amount in major currency units, e.g. 9.00 for $9.00. Send 0 to void an existing tip
taxInformation.taxAmountnumberNoTax amount in major currency units (e.g. 1.50). Note: different format from POST /transactions, where tax is a string in minor units. 0 corrects the tax of the tip adjustment to zero
taxInformation.taxExemptbooleanNoLevel 2 tax-exempt flag. When true, taxAmount, if sent, must be 0

Response​

{
  "statusMessage": "tip adjusted",
  "batchNumber": "123",
  "taxInformation": {
    "taxAmount": 1.50,
    "taxAmountIdentifier": "1"
  }
}

taxInformation is only present when the gateway returns it. taxAmountIdentifier is "1" for local sales tax, "2" for tax exempt.

FieldTypeDescription
statusMessagestring"tip adjusted" on success
batchNumberstringThe current open batch number, if returned by the acquirer. May be absent
taxInformation.taxAmountnumberThe tax amount recorded by the gateway, in major units. Absent when not returned
taxInformation.taxAmountIdentifierstring"1" local sales tax, "2" tax exempt. Absent when not returned

Errors​

CodeMeaningRecovery
ORIGINAL_NOT_FOUNDTransaction ID not foundVerify the ID
BATCH_ALREADY_CLOSEDBatch has closedRefund the tip amount instead
TIP_ADJUSTMENT_NOT_ENABLEDTMS config not setContact Handpoint onboarding team
AMOUNT_EXCEEDS_LIMITTip exceeds allowed percentageVerify tip amount
400 (Level 2 validation)Invalid taxInformation, for example a non-zero taxAmount with taxExempt true, or an unsupported fieldFix the field — see Level 2 validation errors

Testing​

Test tip adjustment on the TEST/DEMO merchant or staging device. Tip adjustment is enabled by default — no additional configuration required. See the Tipping guide for full details on tip-at-table flows.

Pre-Authorization​

Pre-Authorization​

On-device · chip, contactless, or magstripeCloud APIAndroid (PAX)CordovaBackoffice

What this does​

Places a hold on funds without capturing them, allowing the final amount to be adjusted before settlement.

When to use it​

Use for hotel check-ins, car rentals, or any flow where the final amount is unknown at the time of card interaction. Do NOT use for standard retail — use Sale instead.

Pre-Auth is a bundle of operations​

Supporting pre-auth means supporting the full lifecycle:

OperationDescription
CreatePlace the initial hold
Increase / DecreaseAdjust the held amount before capture — see the Pre-Authorization Guide
CaptureFinalise and charge the held amount
Pre-Auth ReversalRelease the hold without charging (pre-capture)
Capture ReversalCancel a completed capture (pre-settlement) — see separate section

Implementation notes​

  1. A pre-auth creates an authorisation hold on the cardholder's account. Funds are not captured until you send a Capture.
  2. The hold typically expires after 7–30 days depending on the card network and issuer. Always capture or void before expiry.
  3. Increase / Decrease adjusts the hold with a delta, not a new total, and always references the original pre-auth transactionID. Not available on every acquirer — see the Pre-Authorization Guide.
  4. Always reverse unused pre-authorisations — unreleased holds affect the cardholder's available credit.
PAYSAFE

PAYSAFE merchants may be onboarded on TSYS, TNS, or both. When a merchant has both processors configured, the Handpoint gateway routes based on card type: Interac cards → TNS (card-present only), all other cards → TSYS. INTERAC VOID: For Interac card transactions, show VOID in your UI — not Refund or Reverse. The only post-sale correction is VOID (full amount, card must be present at terminal). Standard refund is not available for Interac. BATCHING: Batch close applies to TSYS (non-Interac) transactions only. TNS (Interac) transactions settle independently and do not participate in the TSYS batch. Paysafe single-use token: requires merchant onboarding by Paysafe/Handpoint before use.

Create​

Code​

POST https://cloud.handpoint.com/transactions
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "operation": "preAuthorization",
  "amount": "10000",
  "currency": "USD",
  "terminal_type": "PAXA920",
  "serial_number": "082104578",
  "transactionReference": "2bfde1fc-23b1-4c67-93d9-1d4a557f4d4f"
}

Parameters​

NameTypeRequiredDescription
operationstringYesMust be "preAuthorization"
amountstringYesAuthorisation amount in smallest currency unit as a string
currencystringYesISO 4217 currency code
terminal_typestringYesTerminal model, e.g. "PAXA920"
serial_numberstringYesTarget terminal serial number
transactionReferencestringNoUUID v4. Send on Pre-Auth create only — do not send on Capture, Void, or Increase. Enables status queries and groups all lifecycle operations

Testing​

Test pre-auth on the TEST/DEMO merchant or staging device.

ScenarioHow to trigger
Create holdSend with transactionReference — verify finStatus: AUTHORISED and no amount settled yet
Full lifecycleCreate → Capture → query /status/all — verify both operations in chain
Release without captureCreate → Void — verify hold released, no settlement
transactionReference on subsequent opsSend transactionReference on Capture or Void — verify it is not accepted

For complete lifecycle test scenarios, see Testing Edge Cases.

Capture​

No card required — settle the held amountCloud APIAndroid (PAX)CordovaBackoffice

Pre-Authorization Capture​

Captures the funds from a previously created pre-authorization (completion).

When to use: When you know the final amount and are ready to settle. Send the actual charged amount — it may differ from the original pre-auth amount.

Implementation notes:

  1. The capture amount can be less than the pre-auth amount. Most acquirers also allow a small overage (check your acquirer rules).
  2. You must capture before the hold expires (typically 7–30 days).
  3. After capture, a standard refund process applies if the cardholder requests a return.

Direct to the gateway — no terminal required. Synchronous — result returned immediately.

POST https://cloud.handpoint.com/preauthorization/capture
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "originalGuid": "01236fc0-8192-11eb-9aca-ad4b0e95f241",
  "capturedAmount": "95.00"
}

originalGuid is the transactionID from the pre-authorization result.

Parameters​

Amount in major currency units — "95.00" = $95.00. Synchronous — result returned immediately.

ParameterTypeRequiredDescription
originalGuidstringYestransactionID from the pre-authorization result (UUID v4)
capturedAmountstringYesCapture amount in major currency units, e.g. "95.00" for $95.00; at most 12 digits, or 13 characters with a decimal point, no leading zeros except a single 0 before the decimal point, as in 0.50
tipAmountstringNoOptional tip in major currency units — Cloud API only; not supported in SDK paths
taxInformationobjectNoLevel 2 tax data: taxAmount (string, major currency units, e.g. "9.50") and taxExempt (boolean). taxAmount is required: "0" when taxExempt is true, greater than "0" otherwise, and never above capturedAmount. Must be sent with purchaseOrderNumber
purchaseOrderNumberstringNoLevel 2 purchase order number. Must be sent with taxInformation. Alphanumeric, max 25 characters

Errors​

Backoffice (POST /preauthorization/capture) — synchronous, errors are immediate:

HTTPcodemessageMeaningWhat to do
4005001NullPointerExceptionoriginalGuid not foundVerify the GUID is the transactionID from the pre-auth create result. Code 5001 for this endpoint always means the original transaction was not found
4004066Partial reversal amount exceeds original amountcapturedAmount exceeds the pre-auth hold amountReduce the capture amount
4003051Already reversedPre-auth was already voidedCheck your records — void and capture are mutually exclusive; you cannot capture after a void
4003211(pre-auth already settled)Pre-auth has already been captured — a second capture is not possibleVerify state via the TXN Feed API; if the first capture succeeded, issue a refund if needed
400—Invalid capturedAmount, must be in the major unit of currency (20.50 is 20.50 EUR)capturedAmount doesn't match the format aboveSend a decimal string such as "95.00"
400—(Level 2 validation message)Invalid taxInformation or purchaseOrderNumber, for example Invalid taxInformation.taxAmount, must not exceed capturedAmountFix the field — see Level 2 validation errors
403—No valid key found in headerInvalid API keyCheck ApiKeyCloud header
422VALIDATION_FAILEDMissing required fieldRequest body is missing originalGuid or capturedAmountSee details array in response for the specific field

Testing​

ScenarioHow to trigger
Capture full hold amountcapturedAmount = original Pre-Auth amount — verify AUTHORISED
Capture partial amountcapturedAmount < original amount — verify settled amount in portal
Capture with tipInclude tipAmount — verify total settled = capturedAmount + tipAmount
Invalid originalGuidUse a random UUID — verify ORIGINAL_NOT_FOUND

Pre-Auth Reversal​

Release the hold without chargingCloud APIAndroid (PAX)CordovaBackoffice

Pre-Auth Reversal​

Releases a pre-authorization hold without capturing funds.

When to use: When a booking is cancelled or the pre-auth is no longer needed. Always reverse unused pre-auths — unreleased holds affect cardholder available credit.

Timing — not same-day restricted

Reversing a pre-auth hold is not subject to the same-day cut-off that applies to sale reversals. You can reverse the hold at any point before it expires — typically 7–30 days from the original authorization, depending on the card network and issuer. After expiry the hold is released automatically by the network. See Pre-Authorization Hold Durations for card-brand rules.

POST https://cloud.handpoint.com/transactions
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "operation": "preAuthorizationReversal",
  "terminal_type": "PAXA920",
  "serial_number": "082104578",
  "originalTransactionId": "01236fc0-8192-11eb-9aca-ad4b0e95f241"
}

Parameters​

ParameterTypeRequiredDescription
operationstringYesMust be "preAuthorizationReversal"
terminal_typestringYesTerminal model, e.g. "PAXA920"
serial_numberstringYesTarget terminal serial number
originalTransactionIdstringYestransactionID from the pre-authorization result

Errors​

Void is a with-reader operation — errors arrive in the polled result, not in the initial 202 response.

finStatusMeaningWhat to do
DECLINED / FAILEDoriginalTransactionId not foundVerify the GUID is the transactionID from the pre-auth create result
DECLINEDPre-auth has already been captured or voided — hold no longer existsCheck transaction state before voiding
note

There is no separate "already voided" error code — attempting to void an already-captured or already-voided pre-auth returns a DECLINED or FAILED result. Always check the finStatus field in the polled result.

Testing​

ScenarioHow to trigger
Void before captureCreate Pre-Auth → send Void — verify AUTHORISED and no settlement in portal
Void after captureCreate → Capture → Void — verify whether acquirer supports post-capture void
Invalid referenceUse a random originalTransactionId — verify ORIGINAL_NOT_FOUND

Tokenization​

Paysafe Single-Use Token​

Paysafe · single-use token — for use on Paysafe APIs; consult Paysafe teamCloud APIAndroid (PAX)Android (HiLite)iOS (HiLite)CordovaJavaScript SDKWindows (.NET)

What this does​

Reads the card at the terminal and generates a Paysafe single-use token — a short-lived, one-time credential that lets you securely pass card data to Paysafe's Customer Vault without your server ever handling the raw PAN. Handpoint Gateway returns the token in the cardToken field of the transaction result.

When to use it​

Use when your integration also calls Paysafe's own Customer Vault API to store a card on file. The Handpoint-issued single-use token is the secure input to that vault call — once consumed, Paysafe returns a permanent paymentToken your system can store for recurring charges.

Paysafe-ecosystem token — not for Handpoint MOTO

This token is intended for use on Paysafe's Customer Vault API, not Handpoint's /moto/sale endpoint. The Handpoint Gateway does not detokenize Paysafe single-use tokens for MOTO processing.

Contact the Paysafe team before building a token-based flow to confirm the token format Handpoint returns meets your specific integration requirements.

How the vaulting flow works​

Terminal reads card
  → Handpoint Gateway requests single-use token from Paysafe
  → Paysafe returns single-use token (expires in ~15 min)
  → Handpoint returns cardToken to your system

Your system calls:
  POST https://api.paysafe.com/customervault/v1/profiles
    { "singleUseToken": "<cardToken>" }

  → Paysafe vaults the card and returns a permanent paymentToken
  → Your system stores the permanent paymentToken for future charges

The permanent paymentToken is what Paysafe intends for recurring billing and is reusable with no expiry.

Implementation notes​

  1. 15-minute expiry. The single-use token expires ~15 minutes after generation (timeToLiveSeconds: 899 in Paysafe's response). Pass it to the Paysafe Customer Vault API within that window.
  2. Non-deterministic. The same card submitted twice produces different tokens each time — these tokens are not stable card identifiers and cannot be used for loyalty or card-matching.
  3. Not for MOTO. Handpoint does not detokenize Paysafe single-use tokens. You cannot pass cardToken to /moto/sale on a Paysafe merchant — use the permanent vault token through Paysafe's own APIs instead.
  4. Token scope: Tokens are specific to the Paysafe merchant configuration. Test tokens (from api.test.paysafe.com) are not valid in production.
  5. Consult Paysafe. Work with the Paysafe team to confirm your merchant's Customer Vault setup and that the token format Handpoint returns is compatible with your integration before going live.
Team review pending

The Paysafe vaulting flow described above is based on Paysafe's public Customer Vault API documentation. Please have the Handpoint team verify this matches the actual gateway implementation before publishing.

Code​

Tokenize only (no charge):

POST https://cloud.handpoint.com/transactions
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "operation": "tokenizeCard",
  "terminal_type": "PAXA920",
  "serial_number": "082104578"
}

Sale and tokenize (charge + token in one step):

POST https://cloud.handpoint.com/transactions
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "operation": "saleAndTokenizeCard",
  "amount": "1000",
  "currency": "USD",
  "terminal_type": "PAXA920",
  "serial_number": "082104578",
  "transactionReference": "2bfde1fc-23b1-4c67-93d9-1d4a557f4d4f"
}

The cardToken in the response is a Paysafe single-use token for use on Paysafe APIs.

Response fields​

FieldDescription
cardTokenPaysafe single-use token — pass to Paysafe APIs; not for Handpoint MOTO
cardTokenProvider"PAYSAFE"
expiryDateMMYYToken expiry (matches card expiry)

Testing​

Test tokens are returned on the TEST/DEMO merchant or staging device. Confirm with Paysafe that test tokens are accepted on the Paysafe API sandbox before running end-to-end tests.

TokenEx​

3rd-party · TokenEx — loyalty / card-matching; no detokenization through HandpointCloud APIAndroid (PAX)Android (HiLite)iOS (HiLite)CordovaJavaScript SDKWindows (.NET)

What this does​

Reads the card at the terminal and stores it in the TokenEx token vault — a 3rd-party PCI-compliant token service. Handpoint returns a TokenEx token in the cardToken field. The token represents the card identity without storing the PAN in your system.

When to use it​

Use for loyalty programs and card-matching flows — identifying that the same card is being used across multiple visits or transactions. TokenEx tokens let you correlate card-present transactions to a loyalty account or stored profile without ever handling PAN data.

No detokenization — not for MOTO / remote charging

TokenEx tokens cannot be detokenized through Handpoint. They cannot be used for back-office MOTO charges or remote sales. If you need card-not-present charging from a stored token, see the Cygma flavor (EPI acquirer) or Paysafe Single-Use Token flavor (Paysafe acquirer).

Implementation notes​

  1. 3rd-party vault: TokenEx operates independently of Handpoint acquirers. The same TokenEx token can be issued regardless of which Handpoint acquirer processes the sale.
  2. No detokenization: The original PAN cannot be retrieved from a TokenEx token through Handpoint's APIs. TokenEx supports detokenization through its own APIs for clients with a direct TokenEx contract — this is outside the Handpoint integration.
  3. Token stability: The same card consistently maps to the same TokenEx token (within the same merchant configuration), making it reliable for card-matching and loyalty purposes.
  4. Token scope: Tokens are specific to the merchant configuration. Test tokens are not valid in production.

Code​

Tokenize only (no charge):

POST https://cloud.handpoint.com/transactions
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "operation": "tokenizeCard",
  "terminal_type": "PAXA920",
  "serial_number": "082104578"
}

Sale and tokenize (charge + token in one step):

POST https://cloud.handpoint.com/transactions
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "operation": "saleAndTokenizeCard",
  "amount": "1000",
  "currency": "USD",
  "terminal_type": "PAXA920",
  "serial_number": "082104578",
  "transactionReference": "2bfde1fc-23b1-4c67-93d9-1d4a557f4d4f"
}

The cardToken in the response is a TokenEx token. Match it to a loyalty profile or record it for card-correlation purposes.

Response fields​

FieldDescription
cardTokenTokenEx token — stable card identifier for loyalty / card-matching. Cannot be used for MOTO
cardTokenProvider"TOKENEX"
expiryDateMMYYToken expiry (matches card expiry)

Testing​

Test tokens are returned on the TEST/DEMO merchant or staging device. Use the TokenEx sandbox to verify card-matching behavior before testing on production.

Void​

Cancel a transaction before settlement — card must be presentCloud APIAndroid (PAX)Android (HiLite)iOS (HiLite)Cordova
Interac cards only

Void applies exclusively to Interac card transactions. For non-Interac cards, use Reversal instead — the Interac network does not support standard reversal.

What this does​

Voids a transaction — used for Interac card transactions where standard reversal is not available.

When to use it​

Use specifically for Interac card transactions via TNS. For non-Interac transactions, use Reversal instead. The card must be physically present at the terminal. This must occur before settlement.

Implementation notes​

  1. Interac / TNS only. For non-Interac cards, use Reversal instead.
  2. The card must be inserted or tapped at the terminal — card-not-present void is not supported by the Interac network.
  3. Full amount only — partial voids are not supported.
  4. ISV UI note: label this button "VOID" in your application — never "Refund" or "Reverse". This is an Interac network requirement.
  5. SDK behaviour: the Android SDK method called is refund(). The Handpoint gateway detects that the original transaction was processed via TNS (Interac) and automatically maps the refund request to a TNS VOID internally. You do not call a separate void function.

See also: Interac VOID — implementation guide

PAYSAFE

PAYSAFE merchants may be onboarded on TSYS, TNS, or both. When a merchant has both processors configured, the Handpoint gateway routes based on card type: Interac cards → TNS (card-present only), all other cards → TSYS. INTERAC VOID: For Interac card transactions, show VOID in your UI — not Refund or Reverse. The only post-sale correction is VOID (full amount, card must be present at terminal). Standard refund is not available for Interac. BATCHING: Batch close applies to TSYS (non-Interac) transactions only. TNS (Interac) transactions settle independently and do not participate in the TSYS batch. Paysafe single-use token: requires merchant onboarding by Paysafe/Handpoint before use.

Code​

POST https://cloud.handpoint.com/transactions
ApiKeyCloud: YOUR_MERCHANT_API_KEY
Content-Type: application/json

{
  "operation": "refund",
  "amount": "1000",
  "currency": "CAD",
  "terminal_type": "PAXA920",
  "serial_number": "082104578",
  "originalTransactionId": "01236fc0-8192-11eb-9aca-ad4b0e95f241"
}

The gateway detects that the original transaction was Interac/TNS and maps to the correct void protocol automatically. Do not include a transactionReference — this is a subsequent operation.

Parameters​

NameTypeRequiredDescription
operationstringYesMust be "refund" — gateway maps to TNS VOID automatically
amountstringYesFull original sale amount in smallest currency unit as a string
currencystringYesMust be "CAD" for Interac
terminal_typestringYesTerminal model, e.g. "PAXA920"
serial_numberstringYesTarget terminal serial number
originalTransactionIdstringYestransactionID from the original Interac sale result

Errors​

CodeMeaningRecovery
CARD_NOT_PRESENTCard was not inserted/tappedAsk cardholder to present card at terminal
ALREADY_SETTLEDTransaction already settledCredit refund is not available for Interac
ORIGINAL_NOT_FOUNDReference not foundVerify reference

Testing​

Test void (Interac/TNS) on the TEST/DEMO merchant. A physical card must be present at the terminal — card must be inserted or tapped.

Interac Card Transactions​

Interac card transactions — full void only, card present requiredCloud APIAndroid (PAX)JavaScript SDKWindows (.NET)

If you are building for merchants that process Interac card transactions, this section is your integration reference. Interac cards are routed to the TNS processor automatically — no special configuration is required by the ISV beyond what is already set up for Paysafe.

ISV onboarding checklist:

  • Your Sale flow already covers Interac EMV sales.
  • You must implement EMV VOID (not Refund) as the post-sale correction for Interac transactions — see Void section above.
  • Remote reversal (POST /reversal) is not available for Interac — card must be physically present at the terminal for any post-sale correction.

Supported operations for Interac cards​

OperationSupportNotes
EMV Sale✅All integration paths — see Sale section
Sale with Tip✅Tip selection screen on terminal; tip is included in the authorized total (F4). No separate tip breakdown field is forwarded to TNS. Confirmed in production.
EMV VOID✅Same-day, before settlement cut-off, card must be present — see Void section above
Remote Reversal❌Not available — card must be present at terminal; no back-office void path
MOTO / Remote Sale❌Interac network does not support card-not-present
Credit Refund❌Not available for Interac — use VOID (same-day) instead
Pre-Authorization❌Explicitly rejected by Interac network
Tip Adjustment❌Hard-blocked at the TNS protocol validator — post-sale tip modification is not possible on this route
Key Entry Sale❌Not supported on Interac

For code, parameters, and testing, see the Void section above — it covers all integration paths including Cordova.