Webhook Payload Reference

Payblr sends webhook notifications to your configured endpoint when a subscribed event occurs exactly as it is received.

Implementation note: Use this section to understand the payload delivered to your endpoint. Your system should route each webhook by context.eventCode and use context.notificationId for duplicate detection and idempotent processing.

Standard Payload Structure

Webhook notifications use a standard structure with a context object and an event-specific payload object.

{
  "context": {
    "notificationId": "notification-uuid",
    "eventCode": 103,
    "eventVersion": "v1",
    "notificationTime": "2026-06-09T16:15:30Z"
  },
  "payload": {
    "eventSpecificField": "eventSpecificValue"
  }
}

Payload Examples by Event Code

Event Code 101 - Fraud Rule Triggered by a Transaction

This event is sent when a fraud rule is triggered by a transaction.

{
  "context": {
    "notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "eventCode": 101,
    "eventVersion": "v1",
    "notificationTime": "2024-01-24T23:20:28Z"
  },
  "payload": {
    "fraudAlertId": "05e991e3-9058-4d79-bf01-76d4e8fe2059",
    "productId": 123,
    "transactionId": 98765432101212,
    "tokenId": 545454121,
    "transactionAmount": "50.75",
    "currency": "USD",
    "merchantName": "Sample Merchant",
    "location": "United Kingdom",
    "dateTime": "2024-01-24T14:30:00Z",
    "mcc": "4567",
    "notificationMessageContent": "Did you attempt $50.75 on card ending 1234 at Example Merchant ? We suspect fraud and blocked the card, Acknowledge if you made this purchase."
  }
}

Event Code 102 - Fraud Acknowledgement Notification

This event is sent when a fraud alert is acknowledged, closed, or times out.

Timeout Response

{
  "context": {
    "notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d481",
    "eventCode": 102,
    "eventVersion": "v1",
    "notificationTime": "2025-01-24T23:20:28Z"
  },
  "payload": {
    "fraudAlertId": "05e991e3-9058-4d79-bf01-76d4e8fe2081",
    "fraudAlertType": "Timeout",
    "notificationMessageContent": "From Bank: No response was received to confirm if the purchase of 3 days ago was fraudulent. Your card remains blocked. Please contact Customer Service.",
    "productId": 123
  }
}

Acknowledgement Response

{
  "context": {
    "notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "eventCode": 102,
    "eventVersion": "v1",
    "notificationTime": "2024-01-24T23:20:28Z"
  },
  "payload": {
    "fraudAlertId": "05e991e3-9058-4d79-bf01-76d4e8fe2059",
    "fraudAlertType": "Acknowledgement",
    "notificationMessageContent": "From Bank: Thank you for replying. Your card ending 1234 has been unblocked.",
    "productId": 123
  }
}

Event Code 103 - Card Status Change

This event is sent when a card status changes.

{
"context": {
"notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"eventCode": 103,
"eventVersion": "v1",
"notificationTime": "2024-01-24T23:20:28Z"
},
"payload": {
"tokenId": "123456789",
"productId": 123,
"dateTime": "2024-01-24T14:30:00Z",
"newCardStatus": "41",
"oldCardStatus": "00",
"message": "Card status changed from active to lost or stolen.",
"trackingId": "60b83k64-526e-4d25-84c7-32b6e47c02b3"
}
}

Event Code 104 - Custom PAN Creation

This event is sent when a card with a custom PAN has been created.

{
  "context": {
    "notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "eventCode": 104,
    "eventVersion": "v1",
    "notificationTime": "2024-01-24T23:20:28Z"
  },
  "payload": {
    "productId": 123,
    "messageId": "60b83k64-526e-4d25-84c7-32b6e47c02b3",
    "publicToken": "123456789"
  }
}

Event Code 105 - Payment Manual Review Outcome

This event is sent when a pending payment has been reviewed.

{
  "context": {
    "programManagerId": 16,
    "eventCode": 105,
    "eventVersion": "v1",
    "notificationTime": "2024-11-24T11:20:28Z",
  },
  "payload":
   {
      "transactionId": "123412341234",
      "eventid": "55221979-a4cd-4d7a-bb0c-1b3f0b7cb92c",
      "reviewStatus": "no-risk",
      "reviewDate": "2024-11-24T09:15:10.086Z"
   },
  "messageHeaders": {
    "schemaId": 1
  }
}

Event Code 106 - Tokenisation Authorisation Request

This event is sent when a tokenisation authorisation request is received.

{
"context": {
"notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"eventCode": 106,
"eventVersion": "v1",
"notificationTime": "2024-01-24T23:20:28Z"
},
"payload": {
"publicToken": "123456789",
"productId": "124",
"paymentToken": "987654321",
"dpan": "5168563000002547",
"networkTokenReference": "67024958022",
"provisioningTraceId": "VIS1-20210318-381077544887139",
"tokenisationServiceDateTime": "2024-10-29T15:16:30Z",
"processorDateTime": "2024-10-29T15:16:50Z",
"responseCode": "85",
"requestSource": "MOBILE_BANKING_APP",
"tokenRequestorId": "1234",
"orangeFlowIndicator": true
}
}

Event Code 107 - Activation Code Notification

This event is sent when an activation code notification is generated.

{
"context": {
"notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"eventCode": 107,
"eventVersion": "v1",
"notificationTime": "2024-01-24T23:20:28Z"
},
"payload": {
"publicToken": "123456789",
"productId": "124",
"paymentToken": "987654321",
"dpan": "5168563000002547",
"networkTokenReference": "67024958022",
"provisioningTraceId": "VIS1-20210318-381077544887139",
"tokenisationServiceDateTime": "2024-10-29T15:16:30Z",
"processorDateTime": "2024-10-29T15:16:50Z",
"otpValue": "123456",
"otpReason": "TOKEN_DEVICE_BINDING",
"otpExpirationDate": "2024-10-29T15:46:30Z",
"activationMethod": "6",
"deviceInfo": {
		"deviceId": "01234B234C1230011230054848300695D86E17C703548A4A",
		"deviceType": "W"
 							}
}
}

Event Code 108 - Tokenisation Complete Notification

This event is sent when tokenisation has completed.

{
  "context": {
    "notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "eventCode": 108,
    "eventVersion": "v1",
    "notificationTime": "2024-01-24T23:20:28Z"
  },
  "payload": {
    "publicToken": "123456789",
    "productId": "124",
    "paymentToken": "987654321",
    "dpan": "5168563000002547",
    "networkTokenReference": "67024958022",
    "provisioningTraceId": "VIS1-20210318-381077544887139",
    "tokenisationServiceDateTime": "2024-10-29T15:16:30Z",
    "processorDateTime": "2024-10-29T15:16:50Z"
  }
}

Event Code 109 - Tokenisation Event Notification

This event is sent when a tokenisation lifecycle event occurs.

{
  "context": {
    "notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "eventCode": 109,
    "eventVersion": "v1",
    "notificationTime": "2024-01-24T23:20:28Z"
  },
  "payload": {
    "publicToken": "123456789",
    "productId": "124",
    "paymentToken": "987654321",
    "dpan": "5168563000002547",
    "networkTokenReference": "67024958022",
    "provisioningTraceId": "VIS1-20210318-381077544887139",
    "tokenisationServiceDateTime": "2024-10-29T15:16:30Z",
    "processorDateTime": "2024-10-29T15:16:50Z",
    "eventReason": "8",
    "messageReasonCode": "02",
    "eventRequestor": " ",
    "processorTokenStatus": "ACTIVE",
    "tokenisationServiceTokenStatus": "ACTIVE"
  }
}

Event Code 110 - Tokenisation Status Update Failure Notification

This event is sent when a token status update fails.

{
  "context": {
    "notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "eventCode": 110,
    "eventVersion": "v1",
    "notificationTime": "2024-01-24T23:20:28Z"
  },
  "payload": {
    "publicToken": "123456789",
    "productId": "124",
    "paymentToken": "987654321",
    "dpan": "5168563000002547",
    "networkTokenReference": "67024958022",
    "provisioningTraceId": "VIS1-20210318-381077544887139",
    "tokenisationServiceDateTime": "2024-10-29T15:16:30Z",
    "processorDateTime": "2024-10-29T15:16:50Z",
    "processorTokenStatus": "ACTIVE",
    "tokenisationServiceTokenStatus": "ACTIVE"
  }
}

Event Code 111 - 3DS Finalised Event

This event is sent when a 3DS authentication event is finalised.

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

Event Code 112 - Transaction Confirmation Event

This event is sent for transaction confirmation notifications.

{
"context": {
"notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"eventCode": 112,
"eventVersion": "v1",
"notificationTime": "2024-01-24T23:20:28Z"
},
"payload": {
"network": "Visa",
"subnetwork": "STAR",
"programManagerCode": "FTX",
"programManagerName": "FintechX",
"programManagerResponse": "00",
"actualBalance": "1500.0000",
"additionalAmount": "50.0000",
"transactionFee": "2.00",
"processorAuthorisationCode": "134822",
"acquiringInstitutionId": "06003758",
"acquirerForwarderId": "000405700",
"availableBalance": "1480.0000",
"billingAmount": "100.0000",
"billingCurrency": "840",
"blockedAmount": "0.0000",
"customerAccount": "CUST123456",
"fxPadding": "1.25",
"fixedFee": "0.0000",
"rateFee": "0.0000",
"mcc": "5411",
"mccDescription": "Grocery Stores",
"mccPadding": "0.50",
"merchantId": "MID98765",
"merchantName": "Walmart NY",
"transactionNote": "Weekly grocery purchase",
"localTransactionTime": "010107",
"localTransactionDate": "20250626",
"processingCode": "000000",
"schemeResponseCode": "00",
"token": "123456789",
"transactionAmount": "100.0000",
"transactionCurrency": "840",
"acceptorCountryCode": "USA",
"transactionDescription": "POS Purchase",
"processorTransactionDateTime": "2025-05-28T10:15:17Z",
"transactionId": "789456123",
"transactionStatusCode": "A",
"transactionType": "A",
"isThreddAuthorised": "Y",
"avsResult": "Y",
"mtid": "0100",
"productId": "1234",
"velocityGroup": "VG01",
"posCapability": "0001000000000100000000000000000000100000000230000",
"posData": "58V9000900000Px100",
"transactionLifeCycleId": "VIS1-20160608-086160508692217",
"transLink": "250415787144555555",
"retrievalReferenceNumber": "510559697285",
"posTerminal": "ECOMM001",
"networkFraudData": "",
"paymentTokenId": "998877",
"paymentTokenWallet": "APPLE",
"schemeTransactionIdentifier": "SCM123456789012345",
"terminalCity": "London",
"processorResponseCode": "00"
}
}

Event Code 115 - Fraud Monitoring Alert Creation

This event is sent when a new fraud monitoring alert is created.

{
  "context": {
    "notificationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "eventCode": 115,
    "eventVersion": "v1",
    "notificationTime": "2025-10-29T23:20:28Z"
  },
  "payload": {
    "AlertTime": "2025-10-29T15:00:00Z",
    "EventTime": "2025-10-29T14:59:30Z",
    "AlertId": "1814885-SleFPH53",
    "EventId": "46d99b92-0d4d-48a4-97a4-eba49b94c9f1",
    "EventType": "cardRT",
    "SystemEventId": "1814885-SleFPH53",
    "ThreddTransactionId": "6167181535",
    "CustomerId": "TRD-1",
    "CardId": "3181200146334628",
    "ProductId": "10030",
    "ProgramManagerCode": [
      "TRD"
    ],
    "TenantId": [
      "TRD"
    ],
    "ActionTags": [
      {
        "Tag": "Action",
        "Values": [
          "Decline"
        ]
      }
    ],
    "TriggeredRules": [
      "AlertingRule",
      "AlertingRule_2"
    ],
    "TriggeringEntities": [
      "3181200136754628",
      "TRD-1"
    ]
  }
}

Recommended Processing Behavior

Area	Recommendation
HTTP response	Your endpoint should return a `2XX` HTTP status code after receiving the webhook.
Duplicate handling	Use `context.notificationId` as the primary duplicate check where present.
Event routing	Use `context.eventCode` to route the notification to the correct internal process.
Payload parsing	Parse the `payload` object according to the subscribed event code.
Logging	Log `notificationId`, `eventCode`, `notificationTime`, and your internal processing result.
Retries	If your endpoint does not return a successful `2XX` response, webhook delivery may be retried up to `3` times. Your processing should be idempotent and should not apply duplicate business impact when the same notification is received more than once.