List of webhooks sent to your server
KYC Status Updates
KYC status update webhooks are sent to the path /kyc appended to your Webhook URL configured on the Striga dashboard.
interface KYCStatusWebhook {
userId: string;
status: VerificationStatus; // Refer to the enum below for a list of statuses
details?: Array<string>; // Details on why the KYC failed, if it did
rejectionComments?: {
userComment: string; // KYC rejection comment for the user from the compliance team
autoComment: string; // KYC rejection comment generated by the system
};
rejectionFinal?: boolean; // If the KYC rejection is final, the user cannot be verified
currentTier: number;
tier0: {
eligible: boolean,
status: VerificationStatus
};
tier1: {
eligible: boolean,
status: VerificationStatus
};
tier2: {
eligible: boolean,
status: VerificationStatus
};
tier3: {
eligible: boolean,
status: VerificationStatus
};
ts: number;
}
enum VerificationStatus {
NOT_STARTED = 'NOT_STARTED',
INITIATED = 'INITIATED', // The "Start KYC" endpoint has been called and the SumSub token has been fetched
PENDING_REVIEW = 'PENDING_REVIEW', // Documents have been submitted and are pending review
ON_HOLD = 'ON_HOLD', // Requires manual review from the compliance team
APPROVED = 'APPROVED', // User approved
REJECTED = 'REJECTED', // User rejected - Can be final or not
REJECTED_FINAL = 'REJECTED_FINAL'
}
Informing your users about their KYC status
General suggestions to increase conversion and keep your users informed are to watch for KYC status updates sent by Striga which relies upon a complex flow behind the scenes, configured via our document processing partner SumSub. In several cases, we suggest sending email/push notifications to users' about their updated KYC statuses with more information as follows about each status -
APPROVED- This status typically means your user is now fully compliant and ready to transact. These statuses may be changed as time goes on and situations in the real world change.ON_HOLD- This status indicates that a member of the compliance team is reviewing the users' application and/or manual intervention may be required and/or a check needs to be performed by our compliance team. Often, statuses may move from ON_HOLD to APPROVED and back. In these cases, we recommend waiting a few minutes before processing an ON_HOLD or APPROVED notification.REJECTED_FINAL- This status indicates that the user cannot be verified. However, often SumSub overturns final decisions or a member of our team overturns a final decision to allow users to try again. We recommend waiting for atleast 24 hours during a business day before notifying an end user about this status.REJECTED- This status implies that there is incomplete information that the user is required to fill out. You may notify the user and redirect them to the SumSub SDK to retry/complete their application. It is important to note that all of these statuses may occur at any point in time depending upon the specific user and their internal status with Striga. For example: A user that is APPROVED in January may be updated to REJECTED in April and is required to submit additional information to continue transacting and therefore must be redirected to the SumSub SDK to redo their KYC.
You can use the above webhook format to inform your user about the current status of KYC and details on why an attempt may be rejected and require re-submission of documents.
In the case that a user is REJECTED, the following details are available via the webhook and the Get KYC Status API.
{
"userId": "4a5e7ba5-cde2-480d-9549-26568100c150",
"status": "REJECTED",
"details": [
"BAD_PROOF_OF_ADDRESS"
],
"rejectionComments": {},
"currentTier": 2,
"tier0": {
"eligible": false,
"status": "NOT_STARTED"
},
"tier1": {
"eligible": false,
"status": "APPROVED",
"inboundLimitConsumed": {
"all": "0",
"va": "0"
},
"inboundLimitAllowed": {
"all": "1500000",
"va": "1000000"
}
},
"tier2": {
"eligible": true,
"status": "REJECTED"
},
"tier3": {
"eligible": false,
"status": "NOT_STARTED"
},
"ts": 1732703202876
}In the case that a user is REJECTED_FINAL, this means that the user cannot be verified and the following details are available.
{
"userId": "4a5e7ba5-cde2-480d-9549-26568100c150",
"status": "REJECTED_FINAL",
"details": [
"SPAM"
],
"rejectionComments": {
"autoComment": "You have exceeded the number of times to upload your documents. If you have any questions, please contact the Company where you try to verify your profile [email protected]",
"userComment": "You have exceeded the number of times to upload your documents. If you have any questions, please contact the Company where you try to verify your profile [email protected]"
},
"currentTier": 2,
"tier0": {
"eligible": false,
"status": "NOT_STARTED"
},
"tier1": {
"eligible": false,
"status": "APPROVED",
"inboundLimitConsumed": {
"all": "0",
"va": "0"
},
"inboundLimitAllowed": {
"all": "1500000",
"va": "1000000"
}
},
"tier2": {
"eligible": true,
"status": "REJECTED_FINAL"
},
"tier3": {
"eligible": false,
"status": "NOT_STARTED"
},
"ts": 1732703202876
}Tier 2 Timeout Webhook
When a user fails to complete Tier 2 verification within the stipulated timeout window (30 days typically), the user is automatically moved to a SUSPENDED status, with a webhook sent as follows
{
"userId": "4a5e7ba5-cde2-480d-9549-26568100c150",
"status": "SUSPENDED",
"details": [],
"rejectionComments": {
},
"currentTier": 2,
"tier0": {
"eligible": false,
"status": "NOT_STARTED"
},
"tier1": {
"eligible": false,
"status": "APPROVED",
"inboundLimitConsumed": {
"all": "0",
"va": "0"
},
"inboundLimitAllowed": {
"all": "1500000",
"va": "1000000"
}
},
"tier2": {
"eligible": true,
"status": "INITIATED"
},
"tier3": {
"eligible": false,
"status": "NOT_STARTED"
},
"ts": 1732703202876
}Rejection Details
The details array contains helpful information if present, that may be used to display messages to the end user. All possible values of tags that may appear in the details array can be found here or obtained as a result from SumSub's SDK directly. In addition to these, we attach a tag COMPLIANCE in cases where it is impossible to onboard a user or reset their verification status.
User Terminations
If for an internal/external reason a user wishes to close their account, the KYC status is updated to TERMINATED and a reason is provided in the reason field. Tier information on these webhooks is not sent as a user in this state is permanently terminated and cannot be re-activated. Reasons can be T_C_BASED_ACCOUNT_CLOSURE, COMPLIANCE_BASED_ACCOUNT_CLOSURE or CLIENT_REQUESTED_ACCOUNT_CLOSURE.
{
"userId": "4a5e7ba5-cde2-480d-9549-26568100c150",
"status": "SUSPENDED",
"reason": 'T_C_BASED_ACCOUNT_CLOSURE',
"ts": 1732703202876
}