Finalised Event

📘
The Finalised Event is configured per Financial Institution. When enabled, Apata sends a POST request to the configured endpoint immediately after each transaction concludes.

📘
See the API reference for the full webhook payload schema.

Payload Structure

The webhook payload contains three main sections: Transaction, Challenges, and Card.

transaction

The full authentication record, including outcome, risk evaluation, merchant details, and device data.

challenges

An array of individual challenge attempts. Present only when a Challenge Flow occurred.

card

Details of the card that was authenticated.

Identifiers

Field	Description
`id`	Unique transaction identifier generated by the ACS
`dsTransactionId`	Transaction ID assigned by the DS
`threeDsServerTransactionId`	Transaction ID assigned by the merchant's 3DS Server
`cardProgramId`	Card Program used during evaluation
`riskProfileId`	Risk Profile applied during evaluation
`isSimulatedTransaction`	Whether this is a test or live transaction

Transaction Details

Field	Description
`amount`	Total transaction amount
`currency`	Transaction currency
`category`	Classification (payment, non-payment)
`transactionType`	Type of transaction
`channel`	Origin channel (Browser Channel, App Channel, 3RI)
`date`	Transaction initiation date
`accountType`	Account type (credit, debit)
`issuingCountry`	Country where card was issued
`bin`	Issuer's BIN

Merchant Information

Field	Description
`merchantId`	Merchant ID assigned by Acquirer
`merchantName`	Merchant name
`merchantCountry`	Merchant country code
`mcc`	MCC (Merchant Category Code)
`threeDsRequestorId`	3DS Requestor ID from DS
`threeDsRequestorName`	3DS Requestor name
`threeDsRequestorUrl`	3DS Requestor website URL
`acquirerBin`	Acquiring institution ID

Authentication Outcome

Field	Description
`state`	Final transaction state (SUCCEEDED, FAILED, REJECTED, etc.)
`authenticationValue`	Authentication Value (cryptogram) for successful transactions
`eci`	ECI representing authentication outcome
`exemption`	Exemption type applied for Frictionless Transactions
`errorCode`	Error code if transaction errored
`errorDescription`	Error description
`reason`	Reason for failure or rejection
`protocolVersion`	Protocol Version used

Challenge & Preference Flags

Field	Description
`challengePreference`	Merchant's Challenge Preference
`decoupledPreference`	Merchant's Decoupled Authentication preference
`wasChallenged`	Whether transaction was challenged
`wasFrictionless`	Whether transaction was frictionless
`wasPresentedChoice`	Whether cardholder saw choice screen
`didMakeChoice`	Whether cardholder made a choice
`didWhitelist`	Whether cardholder Whitelisted merchant

Risk Evaluation

Field	Description
`riskEngineRecommendation`	Risk engine recommendation
`riskRuleId`	Risk Rule ID that determined outcome
`riskRuleType`	Type of risk rule (Conditional, PSD2 Low Value, etc.)
`riskProfileVersion`	Risk Profile version used
`riskProfileEvalReason`	Evaluation reason when no rule triggered

riskProfileEvalReason values:

Value	Description
`APATA_DEFAULT_ACTION`	No rules triggered; default action is challenge
`CHALLENGE_PREFERENCE`	Acquirer-mandated challenge; rules not executed
`CONCURRENT_AREQ_FOR_CARD`	Multiple concurrent requests for same card
`CARD_DISABLED`	Rejected due to disabled card
`NO_RULES`	No rules configured; transaction challenged

Device Information

Field	Description
`deviceIP`	Device IP address
`devicePlatform`	Platform (Android, iOS, Windows)
`deviceModel`	Device model
`deviceOs`	Operating system
`deviceOsVersion`	OS version
`deviceLocale`	Device locale
`deviceTimezone`	Device timezone
`deviceCountry`	Country from IP address
`deviceLanguage`	Device language
`deviceScreenHeight`	Screen height in pixels
`deviceScreenWidth`	Screen width in pixels
`deviceLatitude`	Device latitude
`deviceLongitude`	Device longitude
`deviceAdvertisingId`	Advertising ID
`deviceName`	Device name

Browser Information

Field	Description
`browserAcceptHeader`	HTTP Accept header
`browserJavaEnabled`	Java enabled
`browserJavascriptEnabled`	JavaScript enabled
`browserColourDepth`	Browser colour depth
`browserUtcOffsetMinutes`	UTC offset in minutes
`browserUserAgent`	User Agent string

Currency Conversion

Field	Description
`purchaseAmountInEuro`	Amount in EUR
`purchaseAmountInUSD`	Amount in USD
`purchaseAmountInGBP`	Amount in GBP
`exchangeRateEUR`	Exchange rate to EUR
`exchangeRateUSD`	Exchange rate to USD
`exchangeRateGBP`	Exchange rate to GBP
`exchangeRateTimestamp`	Exchange rate timestamp

Recurring & Instalment

Field	Description
`recurFrequency`	Minimum days between authorisations
`recurEndDate`	End date for recurring payments
`installments`	Maximum authorisations for instalment plan

Cardholder Data (Hashed)

Field	Description
`emailHash`	Hashed email address
`homePhoneHash`	Hashed home phone
`mobilePhoneHash`	Hashed mobile phone
`workPhoneHash`	Hashed work phone
`cardholderNameHash`	Hashed cardholder name

Address Information

Field	Description
`billAddressCity`	Billing city
`billAddressState`	Billing state/province
`billAddressCountry`	Billing country
`shipAddressCity`	Shipping city
`shipAddressState`	Shipping state/province
`shipAddressCountry`	Shipping country
`addressesMatch`	Whether addresses match

SDK & Technical

Field	Description
`sdkTransactionId`	SDK transaction ID
`sdkAppId`	SDK application ID
`threeDsServerReferenceNumber`	EMVCo reference number
`threeDsServerOperatorId`	3DS Server operator ID
`renderType`	Challenge display format
`isNetworkToken`	Whether PAN was detokenized by scheme
`avCreationKeyId`	AV key ID used
`redactedAreq`	Redacted AReq payload

EMVco Field Mapping

Most fields in the Finalised Event payload are sourced directly from the AReq or generated by the ACS during processing. The table below maps Finalised Event fields to their corresponding EMV 3DS field names. Fields with no EMVco equivalent are computed by Apata.

Finalised Event field	EMVco field
`transaction.id`	`acsTransID`
`transaction.dsTransactionId`	`dsTransID`
`transaction.merchantId`	`acquirerMerchantID`
`transaction.merchantName`	`merchantName`
`transaction.merchantCountry`	`merchantCountryCode`
`transaction.mcc`	`mcc`
`transaction.acquirerBin`	`acquirerBIN`
`transaction.threeDsRequestorUrl`	`threeDSRequestorURL`
`transaction.challengePreference`	`threeDSRequestorChallengeInd`
`transaction.protocolVersion`	`messageVersion`
`transaction.channel`	`deviceChannel`
`transaction.category`	`messageCategory`
`transaction.transactionType`	`threeDSRequestorAuthenticationInd` (APP / Browser) or `threeRIInd` (3RI)
`transaction.amount`	`purchaseAmount`
`transaction.currency`	`purchaseCurrency`
`transaction.recurFrequency`	`recurringFrequency`
`transaction.recurEndDate`	`recurringExpiry`
`transaction.installments`	`purchaseInstalData`
`transaction.deviceIP`	`browserIP` (Browser Channel) or SDK device data fields (App Channel)
`transaction.browserUserAgent`	`browserUserAgent`
`transaction.redactedAreq`	Full AReq payload with PAN and cardholder name removed
`transaction.date`	Apata-generated - no EMVco equivalent
`card.id`	Apata-generated - no EMVco equivalent
`card.externalId`	Issuer-provided via Card Link - no EMVco equivalent
`card.scheme`	Derived from the DS connection - no EMVco equivalent

📘
Fields not listed above (converted purchase amounts, exchange rates, risk evaluation fields, challenge details) are computed by Apata during transaction processing and have no direct EMVco equivalent.

Transaction Category

The transaction.category field uses Apata enum values that map to the EMV 3DS messageCategory codes.

`transaction.category`	EMVco `messageCategory`	Description
`PAYMENT`	`01`	A payment transaction involving a monetary amount and currency.
`NON_PAYMENT`	`02`	An NPA transaction that validates cardholder identity without a purchase. Amount and currency fields are not applicable.

Transaction Type

The transaction.transactionType field consolidates two separate EMV 3DS fields depending on the Device Channel.

APP and Browser

Maps to threeDSRequestorAuthenticationInd. Describes the type of request, such as payment, recurring, instalment, or add card.

3RI

Maps to threeRIInd. Describes the reason for the merchant-initiated request, such as recurring payment or split shipment. This field is null for APP and Browser transactions.