KYC callback#

During the KYC process within the SEPA Secure flow, the customer's status can change multiple times. To keep you informed, a callback (webhook) is sent whenever there is a status update, along with information about any missing documents or errors that occurred during the KYC. A callback is also sent when the customer's entity (account) status changes — for example when the customer is blocked or requires a Terms & Conditions patch.

KYC status can be reversed from FULL_USER due to fraud suspicion or documents becoming outdated. Make sure to process this reversal properly. The reversal could be reflected in the entityStatus field (BLOCKED), which is independent from the KYC status.

Set up the KYC details callback endpoint#

To accept the KYC status updates you should configure the endpoint on your side and provide it during the integration setup.

Callback endpoint#

POST https://your-callback-url-here.com/handle-kyc-status

A payload will be delivered to you on every KYC change (usually tied to the KYC process or before/after the payment transaction).

Callback payload#

Name	Type	Description
callbackType	"kyc"	The type of callback
customerId	String	The unique customer ID in the merchant system
docsMissing	Array({docType: string}) \| null	The array of missing docs.
hash	String	The base64-encoded hash is generated using the sha512 algorithm and includes the customer ID, and secret key. The string that will be hashed: `{customer ID}.{secretKey}`.
kycRejectLabel	String \| null	The message indicates the reason for rejecting KYC.
kycEndUserErrorMessage	String \| null	The message provides a detailed description of the error that occurred during KYC.
status	String \| null	Status of KYC: `CREATED` : KYC user is created via POST /customer/{id}/bank-transfer/user `KYC_NEEDED`: KYC process required `PENDING_KYC_DATA`: Awaiting KYC data `KYC_PENDING`: KYC is in progress `SOFT_KYC_FAILED`: Non-critical KYC failure `HARD_KYC_FAILED`: Critical KYC failure `FULL_USER`: KYC completed successfully
entityStatus	String \| null	Customer entity (applicant) status, independent of the KYC status. A callback is sent whenever this status changes: `UNBLOCKED` – default, the customer is active and transactions are allowed `BLOCKED` – transactions for the customer are suspended (e.g. due to fraud suspicion or compliance reasons) `MISSING_TERMS_AND_CONDITIONS_SIGNED` – the customer requires a Terms & Conditions patch before transactions can proceed
kycProcessingStatus	String \| null	`null` – no request in progress `USER_CREATION_IN_PROGRESS` `APPLICANT_CREATION_IN_PROGRESS` `DOCUMENT_UPLOAD_IN_PROGRESS` `VERIFICATION_IN_PROGRESS`
missingLegalDocuments	Array({docType: string}) \| null	The array of missing legal documents (e.g. privacy policy, Terms & Conditions, Terms of Service). Each item contains a `docType` field with one of: `PRIVACY_POLICY`, `TERMS_AND_CONDITIONS`, `TERMS_OF_SERVICE`.

Payload example#

The callback you get after a confirmed or failed transaction might look like this:

{
  "callbackType": "kyc",
  "customerId": "demo_customer_id",
  "docsMissing": ["SELFIE", "PASSPORT"],
  "kycRejectLabel": "BAD_SELFIE, BAD_PASSPORT",
  "kycEndUserErrorMessage": null,
  "status": "SOFT_KYC_FAILED",
  "entityStatus": "UNBLOCKED",
  "kycProcessingStatus": null,
  "missingLegalDocuments": null
}

The callback data above is provided for demonstration purposes only.

Entity status change example#

When a customer is blocked (e.g. due to fraud suspicion) or requires a Terms & Conditions patch, the callback carries the updated entityStatus while the KYC status remains unchanged:

{
  "callbackType": "kyc",
  "customerId": "demo_customer_id",
  "docsMissing": null,
  "kycRejectLabel": null,
  "kycEndUserErrorMessage": null,
  "status": "FULL_USER",
  "entityStatus": "BLOCKED",
  "kycProcessingStatus": null,
  "missingLegalDocuments": null
}

When entityStatus is BLOCKED or MISSING_TERMS_AND_CONDITIONS_SIGNED, transactions for the customer are suspended. Stop accepting deposits/withdrawals for this customer until a subsequent callback restores entityStatus to UNBLOCKED.

Response and data handling#

You may handle the payload information as needed. You do not need to send anything back other than a success status to confirm that the callback has been received and processed on your side.