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.

Recommended handling:

1. Generate a Sumsub link for the account.
2. Send the link to the applicant.
3. Ask the applicant to complete the missing or corrected information.
4. Wait for the next bp.kyc.status_changed webhook before enabling KYC-gated actions.

Generate a Sumsub 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>'

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": "..."
}

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 approved

Use approved 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 rejected

Use rejected 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.