Webhooks

Webhooks notify the partner's external system about events on the platform — onboarding outcomes, balance and transaction changes, risk decisions, application reviews, etc.

Webhook acceptance and retry

The system retries delivery 3 times with a 10-second interval between attempts. This applies to every response with an HTTP status code other than 200.

Refer to the Behavior reference panel below for the per-status-code rules. Each section after the panel documents the JSON payload of a specific webhook event.

Behavior

HTTP status	Outcome	Behaviour
`HTTP 200`	SUCCESS	Request is considered as success and the webhook is acknowledged.
`HTTP 4xx`	RETRY	Request will be retried up to 3 times at 10-second intervals.
`HTTP 5xx`	RETRY	Request will be retried up to 3 times at 10-second intervals.

Merchant created

Example payload of the MERCHANT.CREATED event:

MERCHANT CREATED

{
   "action": "MERCHANT.CREATED",
   "payload": {
      "application": "1819684f-9a85-40fd-8857-13b42f88cbf9",
      "merchant": "8fa03672-5b7f-432b-97ce-f83988a62d4e"
   }
}

Store created

Example payload of the STORE.CREATED event:

STORE CREATED

{
   "action": "STORE.CREATED",
   "payload": {
      "application": "1819684f-9a85-40fd-8857-13b42f88cbf9",
      "merchant": "5f4e1c3e-3d2b-4f4e-8f4e-1c3e3d2b4f4e",
      "store": {
         "token": "2fcd5da3-dd8a-4860-8fca-56ecb964e12b",
         "card_acceptor_identification_code": "16000000",
         "type": "type",
         "terminal": {
            "token": "7cb0db76-6c86-cdda-3939-871adfece952",
            "card_acceptor_terminal_id": "cae2cdcb-e0db-4159-b522-44c0629179d9"
         }
      }
   }
}

Merchant risk score

Example payload of the MERCHANT.RISK_SCORE event:

MERCHANT RISK SCORE

{
   "action": "MERCHANT.RISK_SCORE",
   "payload": {
      "application": "2d782bee-356f-46f1-b3bd-b8cdc054a1e3",
      "merchant": "cf64a82e-a2b1-406a-9edd-fa2fd5a82db1",
      "level": "medium"
   }
}

Account IBAN

Example payload of the ACCOUNT.IBAN event:

ACCOUNT IBAN

{
   "action": "ACCOUNT.IBAN",
   "payload": {
      "account": "da72f6ff-3140-463a-8bba-27e041ece3ea",
      "iban": "BG18RZBB91550123456789"
   }
}

Transaction new

Example payload of the TRANSACTION.NEW event:

TRANSACTION NEW

{
   "action": "TRANSACTION.NEW",
   "version": 2,
   "payload": {
      "id": 161340,
      "token": "2f86714a-0abf-485a-bcac-e3127c001b96",
      "execution_date": null,
      "created_at": "2023-03-31 08:17:19",
      "updated_on": "2023-03-31 08:17:19",
      "channel": "balance-adjustment",
      "fee": null,
      "status": 1,
      "pending_reason": null,
      "is_hidden": false,
      "description": "9028;money",
      "reference": null,
      "reference2": null,
      "reference3": null,
      "reference4": null,
      "linked_transaction": null,
      "refundable_amount": null,
      "voidable": null,
      "admin": "a",
      "is_recurring": false,
      "is_initial_recurring": false,
      "external_identifier": null,
      "external_link": null,
      "type": "wire-transfer",
      "code": null,
      "original_amount": 1000,
      "original_currency": "EUR",
      "is_paid": false,
      "instance": "7cb0db766c86cdda3939871adfece952",
      "merchant": "2fcd5da3-dd8a-4860-8fca-56ecb964e12b",
      "user": null,
      "account": "da72f6ff-3140-463a-8bba-27e041ece3ea",
      "balance": "055d5fc6-bc1b-41e6-9cec-1b22c485fd17",
      "external_balance": "107362589",
      "amount": 1000,
      "currency": "EUR",
      "debit_credit": "credit",
      "phone": null,
      "email": null,
      "name": null,
      "info": null,
      "fx": 1,
      "balance_before": 0,
      "balance_after": 1000
   }
}

Transaction update

Example payload of the TRANSACTION.UPDATE event:

TRANSACTION UPDATE

{
   "action": "TRANSACTION.UPDATE",
   "version": 2,
   "payload": {
      "wires": {
         "status": "settled"
      },
      "status": 1,
      "updated_on": "2023-03-23 16:38:03",
      "token": "f5ef915a-0d45-46ae-9109-acddeb38bcda"
   }
}

Balance update

Example payload of the BALANCE.UPDATE event:

BALANCE UPDATE

{
   "action": "BALANCE.UPDATE",
   "version": 2,
   "payload": {
      "merchant": "2fcd5da3-dd8a-4860-8fca-56ecb964e12b",
      "account": "da72f6ff-3140-463a-8bba-27e041ece3ea",
      "balance": "055d5fc6-bc1b-41e6-9cec-1b22c485fd17",
      "external_identifier": "107362589",
      "card": "14233190-c11b-48cf-8b87-6e90afac332c",
      "available": 1000,
      "blocked": 0,
      "actual": 1000,
      "previous_available": 0,
      "previous_blocked": 0,
      "transaction": "2f86714a-0abf-485a-bcac-e3127c001b96"
   }
}

Transaction suspended

Example payload of the TRANSACTION.SUSPENDED event:

TRANSACTION SUSPENDED

{
   "action": "TRANSACTION.SUSPENDED",
   "version": 1,
   "payload": {
      "queue": "2fcd5da3-dd8a-4860-8fca-56ecb964e12b"
   }
}

Risk NP webhook

Example payload of the RISK.NP.SCORE event:

RISK NATURAL PERSONS WEBHOOK

{
   "action": "RISK.NP.SCORE",
   "version": 1,
   "payload": {
      "message": "Natural Person Classified as High Risk",
      "token": "604cede2f73431055608ccaac916cc1db364a8ba437cfd21"
   }
}

3D authorization webhook

Example payload of the 3d_authorization event:

3D AUTHORIZATION WEBHOOK

{
   "action": "3d_authorization",
   "payload": {
      "merchant_info": {
         "acquirer_id": "270092",
         "merchant_id": "000000000208203",
         "merchant_name": "Paynetics",
         "merchant_url": "https://www.paynetics.digital/",
         "merchant_category_code": 5999,
         "merchant_country_code": "BG"
      },
      "transaction_info": {
         "transaction_timestamp": "2021-02-26T12:23:36.102Z",
         "transaction_amount": 10,
         "transaction_currency": "EUR"
      },
      "request_id": "c624f9d9-2e7b-4912-aa08-cb267a2c1874",
      "public_token": "101602643",
      "user_token": "5c4b0fcb934b3702dfa9d86bd1e269ba3f617fd7ac0278e1",
      "notification_type": "3d_payment"
   }
}

Application approved webhook

Example payload of the APPLICATION.APPROVED event:

APPLICATION APPROVED WEBHOOK

{
   "action": "APPLICATION.APPROVED",
   "payload": {
      "application": "1819684f-9a85-40fd-8857-13b42f88cbf9",
      "merchant": "5f4e1c3e-3d2b-4f4e-8f4e-1c3e3d2b4f4e",
      "status": "approved"
   }
}

Application declined webhook

Example payload of the APPLICATION.DECLINED event:

APPLICATION DECLINED WEBHOOK

{
   "action": "APPLICATION.DECLINED",
   "payload": {
      "application": "1819684f-9a85-40fd-8857-13b42f88cbf9",
      "status": "declined"
   }
}