Handle KYC status webhooks

Handle KYC status webhooks by updating the applicant’s onboarding state based on the latest data.kyc.status value.

KYC status handling

Due sends KYC status updates through the bp.kyc.status_changed webhook event. Use data.id as the account ID and data.kyc.status as the current KYC status.

{
  "id": "wh_evt__123",
  "type": "bp.kyc.status_changed",
  "data": {
    "id": "acct_98765ABCDE",
    "kyc": {
      "status": "manual_review",
      "link": "https://..."
    }
  },
  "occurredAt": "2025-09-22T12:00:00Z"
}

Handle every status explicitly in your onboarding flow:

1. Handle pending

Use pending when the applicant has not completed all required KYC information.

Recommended handling:

1. Keep the account in onboarding.
2. Prompt the applicant to continue the KYC flow.
3. Keep KYC-gated actions disabled until the status changes.

2. Handle resubmission_required

Use resubmission_required when the applicant must correct or resubmit information. Complete the submission through the hosted flow or the API, then wait for the next bp.kyc.status_changed webhook before enabling KYC-gated actions.

Option A — Hosted

Use the hosted flow when you want Sumsub to collect the required information from the applicant.

1. Create a KYC session for the account.
2. Send the returned link to the applicant, or use the returned accessToken to initialize the Sumsub WebSDK in your application.
3. Ask the applicant to complete the missing or corrected information.
4. Wait for the webhook event that follows completion.

Completing the hosted session closes the submission automatically.

Create a KYC session:

curl --request POST \
     --url https://api.due.network/v1/kyc/session \
     --header 'Due-Account-Id: <ACCOUNT_ID>' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <API_KEY>'

If an existing link has expired, force a new link:

curl --request POST \
     --url https://api.due.network/v1/kyc/session \
     --header 'Due-Account-Id: <ACCOUNT_ID>' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <API_KEY>' \
     --header 'content-type: application/json' \
     --data '
{
  "force": true
}
'

A successful response returns a link and access token:

{
  "link": "https://...",
  "accessToken": "..."
}

Option B — API

Use the API flow when you collect and submit the applicant's KYC information in your own experience.

1. Call GET /v1/kyc/submissions to find the account's open submission.
2. Read the submission's requirements and collect only the information those requirements request.
3. Submit the required data to the corresponding endpoint:
   • POST /v1/kyc/submissions/{submissionId}/info for applicant information.
   • POST /v1/kyc/submissions/{submissionId}/documents for documents.
   • POST /v1/kyc/submissions/{submissionId}/questionnaires for questionnaire answers.
   • POST /v1/kyc/submissions/{submissionId}/agreements for accepted agreements.
   • POST /v1/kyc/submissions/{submissionId}/relations for required relations.
4. Call POST /v1/kyc/submissions/{submissionId}/complete after you satisfy the submission requirements.
5. Wait for the next bp.kyc.status_changed webhook before enabling KYC-gated actions.

Requests for information

An RFI (request for information) is separate from the KYC submission and resubmission flow. Do not treat an RFI as a KYC requirement or complete a KYC submission solely because you responded to an RFI.

3. Handle manual_review

Use manual_review when the case is under internal review by Due.

Recommended handling:

1. Show a review-in-progress state to the applicant.
2. Do not ask the applicant to resubmit information unless the status changes to resubmission_required.
3. Use the review SLA in your support messaging:
   • Weekdays: 24 hours
   • Weekends: 48 hours

4. Handle passed

Use passed when KYC has passed.

Recommended handling:

1. Mark KYC as complete for the account.
2. Enable product flows that require KYC.
3. Store the approved state so the applicant does not repeat KYC unnecessarily.

5. Handle failed

Use failed when KYC has reached a final rejected status.

Recommended handling:

1. Mark KYC as rejected.
2. Keep KYC-gated product flows blocked.
3. Treat the status as final unless Due provides a new status update.