Skip to main content

​
Webhook subscription setup

To setup endpoint and subscribe to webhook events you should execute PATCH /v2/webhook method. The following parameters should be specified in request body:
  • url - the path to the service you’ll receive your webhooks on
  • enable - whether or not webhook send is enabled
  • rateLimit - amount of events per second
  • events - the list of events you subscribe to
The list of available events can be obtained in GET /v2/webhook/event method.
In order to check if everything is configured correctly, execute GET /v2/webhook method.
Any company user can execute the method and configure a webhook for themselves with the required pool of events and with their own url.

​
Webhook retry

If a webhook delivery attempt fails, the system will automatically try to resend the message at the following time intervals after the initial failure:
  • 5 seconds
  • 5 minutes (300 seconds)
  • 30 minutes (1800 seconds)
  • 2 hours (7200 seconds)
  • 5 hours (18000 seconds)
  • 10 hours (36000 seconds)

​
Webhook Headers

Each webhook request sent from Finsei includes several HTTP headers that help ensure security, integrity, and traceability of events.
HeaderDescriptionExample
Content-TypeSpecifies the media type of the webhook payload.application/json
User-AgentIdentifies the Finsei webhook service version.Finsei-Webhook/1.0.0 (https://api.finsei.com/doc/webhook.md)
Webhook-IdUnique identifier of the webhook delivery attempt. Useful for idempotency or debugging.0199e36e-30b8-7063-8831-1af941108e25
Webhook-TimestampUNIX timestamp (seconds) when the webhook was created by Finsei.1760457280
Webhook-SignatureHMAC-based signature to verify the authenticity and integrity of the payload.aqpd2Y8elIDUwXcouBeD7bSMEb8ttedxNXif8pWq19Ghiu3rR5JbPV2gNDhNKAm…

​
Webhook example values

​
v2.payment.create

{
  "id": 0,
  "uuid": "string",
  "status": "new",
  "type": "string",
  "fee": {
    "amount": 0,
    "currencyId": "str"
  },
  "amount": 0,
  "total": 0,
  "counterparty": {
    "name": "string",
    "accountHolderName": "string",
    "bic": "string",
    "iban": "string"
  },
  "beneficiaryId": 0,
  "walletId": 0,
  "walletUuid": "string",
  "icon": "CONVERT",
  "entity": "PAYMENT",
  "currencyId": "str",
  "currencyExchangeId": 0,
  "currencyExchangeUuid": "string",
  "reference": "string",
  "transactionAmount": 0,
  "transactionCurrencyId": "str",
  "transactionExchangeRate": "string",
  "retrievalReferenceNumber": "string",
  "rejectReason": "string",
  "purposeCode": {
    "code": "string",
    "purpose": "string"
  },
  "operationType": "string",
  "createdAt": 1666666666999,
  "updatedAt": 1666666666999,
  "completedAt": 1667404598000
}

​
v2.payment.update

{
  "id": 0,
  "uuid": "string",
  "status": "new",
  "type": "string",
  "fee": {
    "amount": 0,
    "currencyId": "str"
  },
  "amount": 0,
  "total": 0,
  "counterparty": {
    "name": "string",
    "accountHolderName": "string",
    "bic": "string",
    "iban": "string"
  },
  "beneficiaryId": 0,
  "walletId": 0,
  "walletUuid": "string",
  "icon": "CONVERT",
  "entity": "PAYMENT",
  "currencyId": "str",
  "currencyExchangeId": 0,
  "currencyExchangeUuid": "string",
  "reference": "string",
  "transactionAmount": 0,
  "transactionCurrencyId": "str",
  "transactionExchangeRate": "string",
  "retrievalReferenceNumber": "string",
  "rejectReason": "string",
  "purposeCode": {
    "code": "string",
    "purpose": "string"
  },
  "operationType": "string",
  "createdAt": 1666666666999,
  "updatedAt": 1666666666999,
  "completedAt": 1667404598000
}

​
v2.payment.delete

{
"id": 0,
"uuid": "string",
"walletId": 0,
"walletUuid": "string"
}

​
v3.wallet.create

{
  "id": 0,
  "uuid": "string",
  "balance": 0,
  "balanceLock": 0,
  "balanceInProgress": 0,
  "currencyId": "str",
  "description": "string",
  "data": {
    "type": "BANK",
    "accountId": "string",
    "details": [
      {
        "id": "string",
        "isMain": true,
        "label": "string",
        "iban": "string",
        "bicSwift": "string",
        "bank": {
          "accountHolderName": "string",
          "name": "string",
          "address": "string"
        }
      }
    ]
  },
  "flags": {
    "isVisible": true,
    "isFavourite": true
  },
  "status": "ACTIVE",
  "color": "string",
  "name": "string",
  "updatedAt": 1666666666999
}

​
v3.wallet.update

{
  "id": 0,
  "uuid": "string",
  "balance": 0,
  "balanceLock": 0,
  "balanceInProgress": 0,
  "currencyId": "str",
  "description": "string",
  "data": {
    "type": "BANK",
    "accountId": "string",
    "details": [
      {
        "id": "string",
        "isMain": true,
        "label": "string",
        "iban": "string",
        "bicSwift": "string",
        "bank": {
          "accountHolderName": "string",
          "name": "string",
          "address": "string"
        }
      }
    ]
  },
  "flags": {
    "isVisible": true,
    "isFavourite": true
  },
  "status": "ACTIVE",
  "color": "string",
  "name": "string",
  "updatedAt": 1666666666999
}

​
v2.card.create

{
  "id": "string",
  "walletId": "string",
  "type": "ChipAndPin",
  "maskedPan": "474359******5050",
  "status": "PROCESS",
  "validUntilDate": "string",
  "cardholderName": "string",
  "notification": {
    "type": "ERROR",
    "title": "string",
    "message": "string"
  },
  "orderInfo": {
    "title": "string",
    "message": "string",
    "orderedAt": 0,
    "dispatchedAt": 0,
    "delivery": {}
  },
  "isSmsBalanceNotification": false,
  "designId": "AIV",
  "updatedAt": 1666666666,
  "version": 1
}

​
v2.card.update

{
  "id": "string",
  "walletId": "string",
  "type": "ChipAndPin",
  "maskedPan": "474359******5050",
  "status": "PROCESS",
  "validUntilDate": "string",
  "cardholderName": "string",
  "notification": {
    "type": "ERROR",
    "title": "string",
    "message": "string"
  },
  "orderInfo": {
    "title": "string",
    "message": "string",
    "orderedAt": 0,
    "dispatchedAt": 0,
    "delivery": {}
  },
  "isSmsBalanceNotification": false,
  "designId": "AIV",
  "updatedAt": 1666666666,
  "version": 1
}

​
v2.cardLimits.calculate

{
  "withdrawal": {
      "currencyId": "EUR",
      "switch": {
        "enabled": true,
        "value": true
      },
      "transaction": {
        "default": 1500,
        "max": 3000,
        "value": 1500
      },
      "daily": {
        "default": 1500,
        "max": 3000,
        "value": 1500,
        "used": 0,
        "available": 1500,
        "reset": 1774483200
      },
      "monthly": {
        "default": 5000,
        "max": 10000,
        "value": 5000,
        "used": 0,
        "available": 5000,
        "reset": 1775001600
      }
    },
    "internetPurchase": {
      "currencyId": "EUR",
      "switch": {
        "enabled": true,
        "value": true
      },
      "transaction": {
        "default": 2000,
        "max": 12500,
        "value": 2000
      },
      "daily": {
        "default": 4000,
        "max": 25000,
        "value": 4000,
        "used": 0,
        "available": 4000,
        "reset": 1774483200
      },
      "monthly": {
        "default": 10000,
        "max": 50000,
        "value": 10000,
        "used": 0,
        "available": 10000,
        "reset": 1775001600
      }
    },
    "contactlessPurchase": {
      "currencyId": "EUR",
      "switch": {
        "enabled": true,
        "value": true
      },
      "transaction": {
        "default": 1000,
        "max": 12500,
        "value": 1000
      },
      "daily": {
        "default": 2000,
        "max": 25000,
        "value": 2000,
        "used": 0,
        "available": 2000,
        "reset": 1774483200
      },
      "monthly": {
        "default": 10000,
        "max": 50000,
        "value": 10000,
        "used": 0,
        "available": 10000,
        "reset": 1775001600
      }
  }
}

​
v2.cardLimits.updated

{
  "id": "00000000-0000-0000-0000-000000000000",
  "updatedAt": 1667484942666
}

​
v2.cardLimits.updateError

{
  "id": "00000000-0000-0000-0000-000000000000",
  "message": "string"
}