Get KYC Status

Get the current status of KYC verification

This endpoint will return the current KYC status mapped with the customerId.

Status Flow by Region after OTP_COMPLETED:

Once the user completes OTP verification and submits KYC data for verification:

• The status transitions from OTP_COMPLETED to IN_REVIEW if it is the first time the user is submitting KYC data.

• For all fiat types except Turkey and Brazil:

  • IN_REVIEW transitions to INTERMEDIATE_KYC_COMPLETED after successful document and ID verification.

  • In some cases, IN_REVIEW may change to TEMPORARY_FAILURE or PERMANENT_FAILURE, depending on the rejection reason and number of attempts.

  • Upon retry after a TEMPORARY_FAILURE, the status reverts to IN_REVIEW on resubmission, and updates to INTERMEDIATE_KYC_COMPLETED if successful.

• For Brazil:

  • IN_REVIEW transitions to BASIC_KYC_COMPLETED.

  • After an additional document verification step, the status progresses to INTERMEDIATE_KYC_COMPLETED.

• For India:

  • IN_REVIEW transitions to INTERMEDIATE_KYC_COMPLETED after successful Aadhaar and PAN ID verification.

  • Upon successful Video KYC, the status is updated to COMPLETED.

  • If Enhanced Due Diligence (EDD) is required for onramp transactions, the status further transitions to EDD_COMPLETED upon successful completion.

---

🇹🇷 Turkey KYC Flow (Available only through the Widget)

1. BASIC_KYC

• User submits: Turkish ID, address, and basic details (name, income, etc.)

• On submission → IN_REVIEW

• If verified → BASIC_KYC_COMPLETED

• If rejected → TEMPORARY_FAILURE / PERMANENT_FAILURE

"currentKycVerificationStep": "BASIC_KYC"

---

2. ADVANCE_KYC (NFC Verification)

• After BASIC_KYC, user uploads ID (front, back, selfie) and scans NFC with physical ID.

• On submission → IN_REVIEW

• If verified → ADVANCE_KYC_COMPLETED

• If rejected → TEMPORARY_FAILURE / PERMANENT_FAILURE

"currentKycVerificationStep": "ADVANCE_KYC"

---

3. VIDEO_KYC (Live Video Call)

• After NFC, user submits POA barcode number and books live video call.

• On submission → IN_REVIEW

• If verified → COMPLETED

"currentKycVerificationStep": "VIDEO_KYC"

---

4. EDD (Enhanced Due Diligence)

• POA (residence certificate) is verified here.

• On submission, or after a successful video call (if the user had already submitted earlier) → IN_REVIEW

• If verified → EDD_COMPLETED (final step)

• If rejected → TEMPORARY_FAILURE / PERMANENT_FAILURE

• In case of temporary failure → prompt user to resubmit POA barcode.

"currentKycVerificationStep": "EDD"

---

Best Practice

Always redirect the user to the widget in case of TEMPORARY_FAILURE, as the user is eligible for resubmission.

Always call the KYC Status API to fetch the latest status before redirecting or updating the UI.

---

🧾 KYC Status Reference

---

1. LOGIN_REQUIRED

• User has not finished login.

• OTP required to begin KYC.

---

2. OTP_COMPLETED

• OTP login succeeded.

• KYC not started yet.

---

3. IN_REVIEW

• KYC submission is under review.

• Outcome: failure or continue to KYC approval.

---

Failure States

4.1 TEMPORARY_FAILURE

• Temporary rejection (e.g., blurry images or wrong docs).

• User can retry.

• Failure reason in API/webhook.

4.2 PERMANENT_FAILURE

• User blocked after maximum attempts.

• Must contact support.

• Failure reason in API/webhook.

---

Passed KYC States

5.1 BASIC_KYC_COMPLETED

• Identity/non-docs verified.

• No document check yet.

5.2 INTERMEDIATE_KYC_COMPLETED

• Identity, non-doc, and documents checked.

5.3 ADVANCE_KYC_COMPLETED

• Advanced (e.g., NFC) done.

• Not for all countries.

5.4 COMPLETED

• Video or video call verified (if required).

5.5 EDD_COMPLETED

• Enhanced Due Diligence done.

• For India, Turkey (e.g., POA check).

---

GET the current KYC verification status.

POST https://api.onramp.money/onramp/api/v2/whiteLabel/kyc/status

Request Body

Name	Type	Description
customerId*	String	Unique id received from /kyc/url

200: OK

{
    "status": 1,
    "code": 200,
    "data": {
        "status": "COMPLETED",
        "countryISO": "IN",
        "currentKycVerificationStep": "EDD",
        "previousSuccessfulKycStep": "VIDEO_KYC"
    }
}

200: OK

KYC Failure response ->

{
    "status": 1,
    "code": 200,
    "data": {
        "status": "TEMPORARY_FAILURE",
        "failedReason": "Invalid Documents",
        "countryISO": "IN",
        "currentKycVerificationStep": "EDD",
        "previousSuccessfulKycStep": "VIDEO_KYC"
    }
}

400: Bad Request Missing required parameter

{
    "status": 0,
    "code": 400,
    "error": "Missing customerId!"
}

500: Internal Server Error Internal Servor Error

{
    "status": 0,
    "code": 500,
    "error": "Internal Servor Error"
}

Response

{
    "status": 1,
    "code": 200,
    "data": {
        "status": "COMPLETED",
        "countryISO": "IN",
        "currentKycVerificationStep": "EDD",
        "previousSuccessfulKycStep": "VIDEO_KYC"
    }
}

Explanation

• status -> 0 is for unsuccessful request, 1 is for a successful one

• data -> current kycStatus can be

  • COMPLETED

  • BASIC_KYC_COMPLETED

  • INTERMEDIATE_KYC_COMPLETED

  • ADVANCE_KYC_COMPLETED

  • EDD_COMPLETED (for INDIA only)

  • PERMANENT_FAILURE

  • TEMPORARY_FAILURE

  • IN_REVIEW

  • OTP_COMPLETED -> The user has signed in, but the KYC verification has not yet begun.

  • LOGIN_REQUIRED -> The user has not completed the login verification.

• currentKycVerificationStep -> current ongoing or next kyc verification step.

• previousSuccessfulKycStep -> last verified kyc verification step.

• Possible values of currentKycVerificationStep/previousSuccessfulKycStep ->

  • BASIC_KYC

  • INTERMEDIATE_KYC

  • ADVANCE_KYC

  • VIDEO_KYC (corresponding to COMPLETED kycStatus)

  • EDD

• countryISO -> ISO Alpha-2 countryCode