Event Code 111 - Apata Finalised Event

The 111 event code is used when Apata sends a finalised event.

{
  "productId": 12345,
  "events": [111],
  "webhookStatus": "active",  
  "config": {
    "url": "https://client_domain.com/webhook",
    "customHeaders": {
      "header1": "value_1",
      "header2": "value_2"
    }
  }
}

After the webhook has been successfully set up, when Apata sends a finalised event, a notification response is sent asynchronously from the Event Delivery Service to the URL specified in the webhook. See the below example of a response.

{
  "context": {
    "notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "eventCode": 111,
    "eventVersion": "v1",
    "notificationTime": "2024-01-24T23:20:28Z"
  },
  "payload": {
    "version": "V2.0",
    "eventType": "FINALISED_EVENT",
    "transaction": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "dsTransactionId": "98315a91-e0b6-4fe0-8842-9ed82ea8ef0b",
      "threeDsServerTransactionId": "3f9430da-4dd7-473c-b3a3-5100a79deb0d",
      "cardProgramId": "ec737f30-0c61-4383-9732-83d7c7b38b49",
      "riskProfileId": "c0ca8866-27de-4ac6-bdda-8dfc24a74ae9",
      "challengePreference": "NO_PREFERENCE",
      "decoupledPreference": "REQUIRED",
      "amount": 1000,
      "currency": "EUR",
      "recurFrequency": 0,
      "recurEndDate": "2019-08-24",
      "installments": 0,
      "merchantId": "string",
      "merchantName": "string",
      "merchantCountry": "IRL",
      "mcc": "1234",
      "threeDsRequestorId": "string",
      "threeDsRequestorName": "string",
      "threeDsRequestorUrl": "string",
      "threeDsServerReferenceNumber": "string",
      "threeDsServerOperatorId": "string",
      "renderType": "APP_NATIVE",
      "date": "2019-08-24T14:15:22Z",
      "acquirerBin": "123456",
      "authenticationValue": "AABBCCDDEEFFAABBCCDDEEFFAAA=",
      "eci": "string",
      "state": "SUCCEEDED",
      "errorCode": "resource_not_found",
      "reason": "CARD_EXPIRED",
      "exemption": "LOW_VALUE_PAYMENT",
      "protocolVersion": "1.0.2",
      "category": "PAYMENT",
      "transactionType": "PAYMENT",
      "channel": "APP",
      "deviceIP": "string",
      "devicePlatform": "string",
      "deviceModel": "string",
      "deviceOs": "string",
      "deviceOsVersion": "string",
      "deviceLocale": "string",
      "deviceTimezone": "string",
      "deviceAdvertisingId": "string",
      "deviceScreenHeight": 0,
      "deviceScreenWidth": 0,
      "deviceName": "string",
      "deviceLatitude": 0,
      "deviceLongitude": 0,
      "deviceCountry": "string",
      "deviceLanguage": "string",
      "browserAcceptHeader": "string",
      "browserJavaEnabled": true,
      "browserJavascriptEnabled": true,
      "browserColourDepth": 0,
      "browserUtcOffsetMinutes": 0,
      "browserUserAgent": "string"
    },
    "challenges": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "challengeProfileId": "950c886e-8eba-4465-8443-d22f90d269f8",
        "challengeMethodId": "12b5985b-8771-477a-9d02-4528a83cf2b4",
        "challengeMethodAlias": "string",
        "challengeMethodType": "SMS_OTP",
        "created": "2019-08-24T14:15:22Z",
        "updated": "2019-08-24T14:15:22Z",
        "ttl": 300,
        "state": "PENDING"
      }
    ],
    "card": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "externalId": "my-custom-card-reference",
      "language": "en",
      "scheme": "VISA",
      "tags": {
        "property1": "string",
        "property2": "string"
      }
    }
  }
}

The below table describes each of the fields included in the notification response.

Field	Description	Type	Mandatory
context	Object that contains the context of the notification, such as the event code.
notificationId	Unique identifier of the notification.	String	Yes
eventCode	The event code. In this case, the event code is 111.	Integer	Yes
eventVersion	The event version.	String	Yes
notificationTime	When the notification was created. Time in the UTC format of 'yyyy-MM-ddTHH:mm:ssZ'.	String	Yes
payload	Object that contains the payload of the notification, which is specific to the event code.
version	The version of the event (for example, `V2.0`).	String	Yes
eventType	The type of the event, indicating this is a finalized event.	String	Yes
transaction	Object that contains details of the finalized transaction.
id	The unique identifier for the transaction.	UUID	Yes
dsTransactionId	The transaction ID assigned by the directory server.	UUID	Yes
threeDsServerTransactionId	The transaction ID assigned by the 3D Secure server.	UUID	Yes
cardProgramId	The ID representing the card program used for this transaction.	UUID	No
riskProfileId	The risk profile ID associated with the transaction.	UUID	No
challengePreference	The preference for challenges. For example, `CHALLENGE_MANDATED`.	String	Yes
decoupledPreference	The merchant’s preference for decoupled authentication.	String	Yes
amount	The purchase amount in the currency's minor unit.	Integer	No
currency	The ISO-4217 alpha currency code.	String	No
recurFrequency	The minimum number of days between authorisations.	Integer	No
recurEndDate	The date after which no further authorisations should be performed in the format.	Date	No
installments	The max number of permitted instalment payments.	Integer	No
merchantId	The acquirer-assigned merchant identifier.	String	No
merchantName	The merchant name assigned by the Acquirer or Payment System.	String	No
merchantCountry	The ISO 3166 alpha country code for the merchant.	String	No
mcc	The directory server specific code describing the merchant's type of business, product or service.	String	No
threeDsRequestorId	The 3DS requestor ID.	String	Yes
threeDsRequestorName	The name of the 3DS requestor.	String	No
threeDsRequestorUrl	The URL of the 3DS requestor.	String	Yes
threeDsServerReferenceNumber	The reference number from the 3DS server.	String	No
threeDsServerOperatorId	The operator ID from the 3DS server.	String	No
renderType	The format in which the challenge is displayed to the cardholder.	String	No
date	The date the transaction was initiated.	Date-Time	Yes
acquirerBin	The BIN of the acquirer.	String	No
authenticationValue	The authentication value generated for the transaction.	String	No
eci	The Electronic Commerce Indicator representing the outcome of authentication.	String	No
state	The final status of the transaction.	String	Yes
errorCode	The error code provided for transactions that encountered an error. For more information on the different error codes that can be returned, see Error Codes.	String	No
reason	The explanation for why the transaction failed or was rejected.	String	No
exemption	For frictionless transactions, indicates the exemption type applied.	String	No
protocolVersion	The 3DS protocol version.	String	Yes
category	The classification of the transaction (For example, payment, non-payment).	String	Yes
transactionType	The type of transaction being processed.	String	Yes
channel	The channel through which the transaction originated (For example, browser, app).	String	Yes
deviceIP	The IP address of the device used for the transaction.	String	No
devicePlatform	The platform of the device used.	String	No
deviceModel	The model of the device used for the transaction.	String	No
deviceOs	The operating system of the device used.	String	No
deviceOsVersion	The operating system version of the device.	String	No
deviceLocale	The locale of the device.	String	No
deviceTimezone	The timezone of the device.	String	No
deviceAdvertisingId	The advertising ID of the device.	String	No
deviceScreenHeight	The screen height of the device.	Number	No
deviceScreenWidth	The screen width of the device.	Number	No
deviceName	The name of the device.	String	No
deviceLatitude	The latitude of the device’s location.	Number	No
deviceLongitude	The longitude of the device’s location.	Number	No
deviceCountry	The country of the device user.	String	No
deviceLanguage	The language of the device.	String	No
browserAcceptHeader	The value of the HTTP Accept header sent by the browser.	String	No
browserJavaEnabled	Indicates whether Java is enabled in the browser.	Boolean	No
browserJavascriptEnabled	Indicates whether JavaScript is enabled in the browser.	Boolean	No
browserColourDepth	The colour depth of the browser.	Number	No
browserUtcOffsetMinutes	UTC offset in minutes of the browser.	Number	No
browserUserAgent	The User Agent string of the browser.	String	No
transaction	End of the transaction object.
challenges	Object that contains details on the challenges performed if the transaction underwent a challenge.
id	The unique identifier of the challenge.	UUID	Yes
challengeProfileId	The identifier of the challenge profile in which this challenge method is configured.	UUID	No
challengeMethodId	The identifier of the challenge method used for this challenge.	UUID	Yes
challengeMethodAlias	The alias of the challenge method used for this challenge.	String	No
challengeMethodType	The type of the challenge method used.	String	Yes
created	When the challenge was created.	Date-Time	Yes
updated	When the challenge state was last updated.	Date-Time	Yes
ttl	The time limit (in seconds) set for completing this challenge.	Integer	Yes
state	The final status of the challenge.	String	Yes
challenges	End of the challenges object.
card	Object that contains information on the card.
id	The unique identifier of the card generated by Apata.	UUID	Yes
externalId	The unique identifier of the card generated by the issuer.	String	No
language	The ISO 639-1 or BCP-47 language code for the card.	String	No
scheme	The payment scheme of the card. For example, `MASTERCARD`.	String	Yes
tags	Object that contains custom tags associated with the card.
property1	The first custom tag property for the card.	String	No
property2	The second custom tag property for the card.	String	No
tags	End of the tags object.
card	End of the card object.
payload	End of the tags object.

Error Codes

The errorCode field returns a code which explains why a transaction failed or was rejected. The following table describes each of the error codes that can be returned.

Error Code	Description
card_already_enrolled	Indicates the card is already registered for 3DS, and this is a duplicate enrolment attempt.
card_not_enrolled	Indicates the card is not enrolled in 3DS, and you cannot proceed with authentication.
no_such_card_range	Indicates the BIN/card range does not exist in the system.
card_range_overlap	Indicates the card range conflicts with an existing range.
card_does_not_exist	Indicates the specific card cannot be found.
no_retries_remaining	Indicates no more retry attempts left.
no_such_transaction	Indicates the referenced transaction ID does not exist.
no_such_challenge	Indicates the referenced challenge does not exist.
fallbacks_exceeded	Indicates if the cardholder exceeded the permitted number of fallback attempts across Challenge Methods.
resource_exists	Indicates a resource being created already exists.
resource_locked	Indicates the resource is locked and cannot be modified.
resource_in_use	Indicates the resource is currently in use.
resource_not_found	Indicates the requested resource cannot be found.
no_permissions	Indicates the requestor lacks permission.
webhook_call_failed	Indicates if a webhook call from the Apata ACS to the issuer failed.
sms_send_failed	Indicates if the ACS was unable to send an SMS OTP to the cardholder.
email_send_failed	Indicates if the ACS was unable to send an Email OTP to the cardholder.
decryption_failure	Indicates the system failed to decrypt the payload (For example, a bad key or corrupted data).
ds_error	Indicates if the DS returned an error when the ACS attempted to report the transaction result.
client_error	Indicates if the 3DS Requestor reported an error on their side to the ACS.
decoupled_not_supported	Indicates if the Decoupled Authentication was required but the Challenge Method configured for the card does not support it. Decoupled authentication is only available under EMV 3DS 2.2 and later.
non_payment_not_supported	Indicates that non-payment authentications are not supported.
requestor_initiated_not_supported	Indicates 3DS requestor initiated transactions are not supported.
not_authorized	Indicates the request is not authorised.
not_healthy	Indicates the request is not healthy.
invalid_request	Indicates the request is malformed or missing required fields.
internal_server_error	Indicates an unexpected server-side error occurred.
invalid_config	Indicates if the transaction could not be completed due to invalid or incomplete configuration.
validation_error	Indicates if a 3DS message received by the ACS was invalid according to the EMV 3DS protocol.
forbidden	Indicates the access to the resource is forbidden for this caller.
card_link_failed	Indicates if the request sent to the issuer via Card Link was unsuccessful.