Skip to main content

Transaction result object

All payment operations return a transaction result asynchronously. The structure varies by integration path — select yours below.

Cloud API — transaction result​

The result is delivered as a JSON POST to your callbackUrl, or retrieved via GET /transaction-result/{transactionResultId} if no callback URL was provided.

{
  "transactionID": "9985dba0-9cbb-11f1-b018-b122502914b1",
  "efttransactionID": "9985dba0-9cbb-11f1-b018-b122502914b1",
  "efttimestamp": 1787246502000,
  "transactionReference": "5ad2dcf3-56b8-4295-b73f-0628a45d21b9",
  "transactionOrigin": "CLOUD",
  "type": "SALE",
  "finStatus": "AUTHORISED",
  "statusMessage": "Aprobado o completado con éxito",
  "errorMessage": "",
  "multiLanguageStatusMessages": {},
  "multiLanguageErrorMessages": {},
  "recoveredTransaction": false,

  "requestedAmount": 1002,
  "totalAmount": 1002,
  "tipAmount": 0,
  "tipPercentage": 0,
  "dueAmount": 0,
  "taxAmount": null,
  "surcharge": {
    "amount": 0,
    "applied": false,
    "reason": ""
  },
  "currency": "USD",

  "cardEntryType": "ICC",
  "paymentScenario": "CHIPCONTACTLESS",
  "tenderType": "CREDIT",
  "verificationMethod": "NOT_REQUIRED",
  "cardSchemeName": "VISA",
  "maskedCardNumber": "************0936",
  "cardTypeId": "************0936",
  "expiryDateMMYY": "1027",
  "cardHolderName": "",
  "cardLanguagePreference": "es_ES",
  "cardToken": "",
  "accountType": "",
  "unMaskedPan": "",
  "balance": null,

  "authorisationCode": "123456",
  "issuerResponseCode": "00",
  "rrn": "0000820374195",

  "aid": "A0000000031010",
  "applicationLabel": "VISA CLASICA",
  "tvr": "0000000000",
  "tsi": "",
  "iad": "06011203A00000",
  "arc": "0000",
  "chipTransactionReport": "",

  "mid": "630000026730",
  "tid": "08215994",
  "merchantName": "Postman Test1",
  "merchantAddress": "Test Address 2 10111 London",
  "customerReference": "",
  "budgetNumber": "",
  "batchNumber": "123",
  "originalEFTTransactionID": "",
  "metadata": null,
  "customFields": null,
  "customData": "",

  "customerReceipt": "https://receipts.handpoint.io/receipts/9985dba0-9cbb-11f1-b018-b122502914b1/customer.html",
  "merchantReceipt": "https://receipts.handpoint.io/receipts/9985dba0-9cbb-11f1-b018-b122502914b1/merchant.html",
  "signatureUrl": "",

  "deviceStatus": {
    "applicationName": "Payments",
    "applicationVersion": "20.4.14.0-RC.66",
    "batteryCharging": "Not Charging",
    "batteryStatus": "59",
    "batterymV": "3829",
    "bluetoothName": "PAXA920",
    "externalPower": "Unknown",
    "serialNumber": "0821599465",
    "statusMessage": ""
  }
}

Core identifiers​

FieldTypeDescription
transactionIDstringUUID v4 — the primary transaction identifier. Store for reversals, tip adjustments, and status queries.
efttransactionIDstringAlias of transactionID. Same value.
efttimestampnumberTransaction timestamp — Unix epoch in milliseconds.
transactionReferencestringThe UUID v4 you sent in the request. Echoed back for sale, refund, saleAndTokenizeCard, and preAuthorization; system-generated (not your value) for all other operations (reversals, captures, tokenizeCard, etc.). Use to correlate with your own system.
originalEFTTransactionIDstringFor refunds, reversals, captures: the transactionID of the original transaction. Empty on original transactions.
transactionOriginstringCLOUD when processed via Cloud API. STANDALONE when processed directly on terminal.

Status​

FieldTypeDescription
finStatusstringPrimary result indicator. See finStatus values below.
typestringTransaction type. See type values below.
statusMessagestringHuman-readable status in the cardholder's card language (cardLanguagePreference), not the terminal's configured language. For example, a Spanish-issued Visa card returns "Aprobado o completado con éxito" even if the terminal is configured in English.
errorMessagestringError detail if finStatus is FAILED or DECLINED. Empty on success.
multiLanguageStatusMessagesobjectMap of locale code → localised status message. May be empty.
multiLanguageErrorMessagesobjectMap of locale code → localised error message. May be empty.
issuerResponseCodestringISO 8583 response code from the issuer. "00" = approved.
authorisationCodestring6-character approval code from the acquirer. Present on approved transactions.
recoveredTransactionbooleantrue if this result was delivered via the terminal recovery loop (callback was retried after a network failure).

Amounts​

All amounts are in the smallest currency unit (cents for USD/EUR/GBP, etc.).

FieldTypeDescription
requestedAmountintegerAmount originally requested. May differ from totalAmount on partial approvals or tip adjustments.
totalAmountintegerTotal amount charged, including tip.
tipAmountintegerTip amount. 0 if no tip.
tipPercentagenumberTip as a percentage of the base amount.
dueAmountintegerOutstanding amount after partial payment (if applicable).
taxAmountintegerTax amount included in the total (App 4.14.0 / REST API 2.28.0+). 0 if not applicable or not yet available.
surchargeintegerSurcharge applied by the acquirer (App 4.14.0 / REST API 2.28.0+). 0 if not applicable.
currencystringISO 4217 currency code: "USD" "GBP" "EUR" etc.

Card​

FieldTypeDescription
cardEntryTypestringHow the card was read. See cardEntryType values.
paymentScenariostringDetailed entry path. See paymentScenario values.
tenderTypestringCREDIT DEBIT PREPAID NOT_SET (MOTO and cancelled transactions)
verificationMethodstringHow the cardholder was verified. See verificationMethod values.
cardSchemeNamestringCard network as emitted by terminal firmware (always uppercase): "VISA" "MASTERCARD" "AMEX" etc.
maskedCardNumberstringPAN masked as "************1234".
cardTypeIdstringAlternative masked PAN representation (same format).
expiryDateMMYYstringCard expiry date in MMYY format, e.g. "1027" = October 2027.
cardHolderNamestringCardholder name as read from the card. May be empty.
cardLanguagePreferencestringLanguage preference from the card chip (IETF tag, e.g. "es_ES").
cardTokenstringTokenized card number. Non-empty only when tokenizeCard or saleAndTokenizeCard was used.
accountTypestringAccount type selected by the cardholder (e.g. "CHEQUE" "SAVINGS").
unMaskedPanstringFull PAN. Empty in standard operation — only populated in specific acquirer configurations.
balanceobject|nullBalance returned by the issuer (e.g. for prepaid or debit cards). null if not provided.

EMV fields​

Present on chip (ICC) and contactless chip transactions. Empty on swipe (MSR) or card-not-present (CNP).

FieldTypeDescription
aidstringEMV Application Identifier (tag 9F06), e.g. "A0000000031010" for Visa.
applicationLabelstringHuman-readable application name from the card chip, e.g. "VISA CLASICA" "MASTERCARD".
tvrstringTerminal Verification Results (tag 95). 5-byte hex string.
tsistringTransaction Status Information (tag 9B). 2-byte hex string.
iadstringIssuer Application Data (tag 9F10).
arcstringAuthorisation Response Code (tag 8A), e.g. "0000" = approved.
chipTransactionReportstringFull chip transaction data report. May be empty.

Merchant & terminal​

FieldTypeDescription
midstringMerchant ID assigned by the acquirer.
tidstringTerminal ID assigned by the acquirer.
merchantNamestringMerchant name configured on the terminal.
merchantAddressstringMerchant address configured on the terminal.
rrnstringRetrieval Reference Number — acquirer-assigned reference for this transaction.
customerReferencestringEchoed-back value from customerReference in the request, if sent.
budgetNumberstringBudget/instalment number (South African acquirers).
batchNumberstringBatch number returned by the acquirer (App 4.14.0 / REST API 2.28.0+). Empty string if not yet available or acquirer does not return it.
metadataobject|nullCustom metadata echoed from the request, if used.
customFieldsarray|nullKey-value pairs for acquirer-specific data. Present on terminal-initiated reversals — see Terminal-Initiated Reversals for the messageReasonCode values. null otherwise.

Receipts​

FieldTypeDescription
merchantReceiptstringMerchant receipt. Three possible forms: (1) a https://receipts.handpoint.io/... URL when successfully uploaded to cloud storage; (2) raw HTML if S3 upload failed or for MOTO on-terminal (check startsWith("<")); (3) empty string "" if the SDK lost connection before receiving a response or if finStatus is UNDEFINED. Always handle all three cases.
customerReceiptstringCustomer receipt. Same three forms as merchantReceipt — URL, raw HTML, or empty string "". Always handle all three cases.
signatureUrlstringCaptured signature image. Two possible forms: (1) https:// URL when successfully uploaded to Handpoint's servers (normal case); (2) raw base64-encoded image binary if the upload failed and the terminal could not reach Handpoint servers. Always check value.startsWith("http") to determine which form you received before displaying. Empty string "" if no signature CVM was used.

Device​

FieldTypeDescription
deviceStatus.applicationNamestringName of the payment app on the terminal.
deviceStatus.applicationVersionstringVersion of the payment app.
deviceStatus.batteryStatusstringBattery level as a percentage string, e.g. "79".
deviceStatus.batteryChargingstring"Charging" or "Not Charging".
deviceStatus.batterymVstringBattery voltage in millivolts.
deviceStatus.externalPowerstringPower source: "USB" "AC" "None".
deviceStatus.bluetoothNamestringBluetooth device name of the terminal.
deviceStatus.serialNumberstringTerminal serial number.
deviceStatus.statusMessagestringTerminal status message.

finStatus values​

ValueMeaning
AUTHORISEDApproved by the issuer. Funds captured (or held, for pre-auth).
DECLINEDDeclined by the issuer or gateway.
CANCELLEDCancelled by the cardholder at the terminal, or reversed automatically by the terminal after host approval. For terminal-initiated reversals, inspect customFields.messageReasonCode for the specific cause — see Terminal-Initiated Reversals.
FAILEDTechnical failure — check errorMessage.
UNDEFINEDNo result received from the gateway. Query /status endpoint — see Transaction Recovery.
PARTIAL_APPROVALPartial approval — totalAmount is less than requestedAmount. Not final when returned from GET /transaction-result/{id}. The terminal presents an accept/decline prompt to the merchant/cardholder; if they decline, the SDK automatically reverses the transaction and the final outcome changes. Wait at least 60 seconds or until the final transaction-result is delivered before treating as settled. US acquirers only.
REFUNDEDTransaction was subsequently refunded. Returned on status queries for original transactions that have been fully refunded.
PROCESSEDOperation processed — used for non-financial operations such as tokenizeCard, Start of Day, and Host Init.
CAPTUREDPre-authorization was captured.
IN_PROGRESSTransaction is still being processed — not a final state. Keep polling. Also returned by GET /transaction-result/{id} while in flight.

type values​

ValueDescription
SALECard-present sale
REFUNDRefund (linked or unlinked)
REVERSALSale reversal
PRE_AUTHORIZATIONPre-auth hold
PRE_AUTHORIZATION_INCREASEPre-auth increase
PRE_AUTHORIZATION_CAPTUREPre-auth capture
MOTO_SALEMOTO sale
MOTO_REFUNDMOTO refund
MOTO_REVERSALMOTO reversal
TOKENIZE_CARDCard tokenization only
SALE_AND_TOKENIZE_CARDSale + tokenize
TIP_ADJUSTMENTTip adjustment on an existing sale
VOID_SALESale reversal (saleReversal()). Tag string: "SALE VOID". Also used for Interac / TNS void.
TRANSACTION_STATUSStatus query result
UNDEFINEDUnknown

cardEntryType values​

ValueDescription
ICCChip insert — contact EMV.
CONTACTLESS_ICCContactless chip (NFC tap) — EMV over the air.
MAG_STRIPEMagnetic stripe swipe. Also emitted as MSR on some terminal firmware versions — treat both as equivalent.
CNPCard Not Present — MOTO / back-office keyed entry.
UNDEFINEDUnknown entry method. Common on reversals and cancelled transactions where no card was presented.

paymentScenario values​

ValueDescription
CHIPCard inserted, EMV chip processed.
CHIPCONTACTLESSCard tapped, EMV chip processed over NFC.
MAGSTRIPECard swiped (magnetic stripe).
MAGSTRIPECONTACTLESSContactless magnetic stripe (legacy contactless cards).
CHIPFAILMAGSTRIPEChip failed — fell back to magnetic stripe.
MOTOMail order / telephone order (card not present).
SWIPEDSwiped (alias for MAGSTRIPE on some acquirers).
FALLBACK_SWIPEContactless and chip failed — swiped as final fallback.
UNKNOWNUnknown scenario.

issuerResponseCode values​

ISO 8583 response code returned by the card network. Use finStatus for programmatic branching — issuerResponseCode provides additional context for logging and merchant display.

"00" does not always mean approved

When the transaction does not reach the issuer (terminal-level decline for a disabled capability), the gateway sets "00" as a placeholder. Always check finStatus first.

CodeMeaningCommon scenario
"00"Approved / completed successfullyTransaction authorised by issuer — or terminal-local decision (see caution above)
"01" / "02"Refer to card issuerIssuer wants voice authorisation
"05"Do not honourGeneric decline — issuer did not specify reason
"12"Invalid transactionTransaction type not permitted for this card
"13"Invalid amountAmount out of range (zero, negative, or exceeds limit)
"14"Invalid card numberPAN does not pass Luhn check
"41"Lost cardCard reported lost
"43"Stolen cardCard reported stolen
"51"Insufficient fundsCard balance or credit limit exceeded
"54"Expired cardCard past its expiry date
"55"Incorrect PINPIN entered does not match
"57"Transaction not permitted to cardholderCard scheme restriction on this transaction type
"61"Exceeds withdrawal amount limitSingle transaction exceeds the card's per-transaction limit
"62"Restricted cardCard restricted to specific merchant category codes
"65"Exceeds withdrawal frequency limitToo many transactions in the allowed period
"75"Allowable number of PIN tries exceededCard locked after repeated incorrect PIN attempts
"91"Issuer not available / card scheme timeoutIssuer host unreachable — may be transient
"96"System malfunctionIssuer internal error — may be transient

arc values​

EMV Authorisation Response Code (tag 8A). Indicates the outcome of the EMV decision flow. Only meaningful when cardEntryType is ICC.

ValueMeaning
"0000"Online approval — transaction was authorised by the issuer online
"0010"Online decline — transaction was declined by the issuer online
"1000"Gateway error — acquirer was not reached; the terminal generated an offline decline. Also set when the terminal itself declined offline (e.g. a capability restriction prevented the transaction from going online).
"" (empty)Not applicable — MOTO, FAILED outcome, or EMV processing did not complete
Capability declines and arc

On a terminal-enforced capability decline (e.g. pre-auth not enabled), you may see arc: "1000" because the terminal generated an offline decline response — even though the real reason was a configuration restriction, not an issuer or card-scheme decision.

verificationMethod values​

ValueDescription
NOT_REQUIREDNo cardholder verification required (e.g. low-value contactless).
PINOffline or online PIN entered.
SIGNATURESignature captured.
PIN_SIGNATUREBoth PIN and signature.
MOBILE_PASS_CODEOn-device biometric / passcode ("See Phone" — Apple Pay, Google Pay).
PIN_BYPASSPIN bypass by cardholder.
CVCCard verification code (CNP transactions).
FAILEDVerification attempted but failed.
UNDEFINEDUnknown.