To improve visibility into KYC failures/rejected reasons and reduce friction during integration, we are introducing two new fields in the KYC status API response. These fields provide detailed explanations for rejection reasons and indicate whether a KYC retry is allowed.

API Endpoint : `/v2/kyc/user`

New Fields Introduced

canRetryKyc – Boolean flag indicating if the KYC process can be retried/resubmitted.
reasons – Object containing rejection reason details, including:
- label – A short identifier for the rejection reason.
- description – A detailed explanation of the rejection reason.

API Response – Current Implementation

{
  "status": "kyc_failed",
  "rejectLabels": [
    "INCOMPLETE_DOCUMENT",
    "SELFIE_MISMATCH"
  ]
}

API Response – Updated Implementation

{
  "status": "kyc_failed",
  "canRetryKyc": true,
  "rejectLabels": [
    "INCOMPLETE_DOCUMENT",
    "SELFIE_MISMATCH"
  ],
  "reasons": [
    {
      label: "INCOMPLETE_DOCUMENT",
      description: "User document is incomplete format.Kindly submit both sides of the document.",
    },
    {
      label: "SELFIE_MISMATCH",
      description: "User selfie is mismatched with the documents.",
    }
  ]
}

Impact on Existing Customers

Backward Compatibility – No breaking changes. The existing response structure remains unchanged.
Fields Addition – Two new fields are appended to the response payload, ensuring seamless integration with current implementations.

This update enhances transparency in KYC failure handling and facilitates automated decision-making for retry attempts.

Changelog

KYC Status Response Enhancement

Enhanced Customer Balance Management

Initial Release