19 Apata Finalised Event Webhook

The Apata Finalised Event webhook enables you to receive notifications when Apata finalises a 3DS transaction. This includes transaction, challenge, and card details.

What are Webhooks?

Webhooks are a comprehensive service designed to facilitate real-time event subscription and notification delivery. You can utilise its REST API to create and update webhook endpoints, which in turn means you can set up the Apata Finalised Event webhook.

When a webhook has been created, events can be created for them. An event is an activity that happens outside of your system, such the Apata Finalised Event. The webhook is then sent the details of the event.

How it Works

  1. Program managers create a webhook using the Create Webhook endpoint.

  2. The program manager creates a subscription for the webhook to subscribe to specific events using the Add Event Subscriptions endpoint. This allows the webhook to receive notifications for those events.

  3. When the setup is complete, whenever the event triggers, the webhook sends notifications to the program managers, ensuring they receive updates on relevant events and changes on their systems or applications.

Creating an Apata Finalised Event Webhook

The Apata Finalised Event webhook uses the event code 111. See the following example of a Create Webhook request for event code 111.

Copy
{
  "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.

Copy
{
  "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"
      }
    }
  }
}

For more information on webhooks and the fields included in the 111 response, see Introduction to Webhooks and Event Code 111 - Apata Finalised Event.