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.

KYC status can be reversed from FULL_USER due to fraud suspicion or documents becoming outdated. Make sure to process this reversal properly.

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
kycProcessingStatus	String \| null	`null` – no request in progress `USER_CREATION_IN_PROGRESS` `APPLICANT_CREATION_IN_PROGRESS` `DOCUMENT_UPLOAD_IN_PROGRESS` `VERIFICATION_IN_PROGRESS`

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",
  "kycProcessingStatus": null
}

The callback data above is provided for demonstration purposes only.

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.