KYC & Compliance

Overview

This skill enables AI agents and applications to check and manage KYC (Know Your Customer) verification status for Eclipse customers.

It supports:

• Retrieving current KYC verification status and individual check results
• Triggering or re-triggering KYC ratification
• Interpreting PASSED, FAILED, and PENDING states for operator action

KYC verification in Eclipse is called ratification. Ratification checks may include identity verification, liveness detection, and sanctions screening — the specific checks performed depend on the KYC provider configured for the tenant.

1. Get KYC Status

Trigger: "check KYC", "KYC status", "verify customer identity", "is the customer verified"

Required inputs: tenantId, customerId

GET {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/ratify
Authorization: Bearer {jwt}

Returns a list of EclipseKycResult objects, most recent first. Pass offset=0&limit=1 for the latest result only.

Response — PASSED:

[
  {
    "status": "PASSED",
    "lastModified": "2026-05-19T08:30:20.000Z",
    "sanctionsListCheck": { "checked": true, "passed": true, "pending": false },
    "selfieMatchesNationalIdentity": { "checked": true, "passed": true, "pending": false },
    "nationalIdentityIsLegitimate": { "checked": true, "passed": true, "pending": false }
  }
]

Response — FAILED:

[
  {
    "status": "FAILED",
    "lastModified": "2026-05-19T08:30:20.000Z",
    "sanctionsListCheck": { "checked": true, "passed": false, "pending": false, "comment": "Match found on OFAC list" },
    "selfieMatchesNationalIdentity": { "checked": true, "passed": true, "pending": false }
  }
]

Each check field (e.g. sanctionsListCheck, selfieMatchesNationalIdentity, identityNumberMatchesNationalIdentity) contains checked (was this check run?), passed (did it pass?), pending (still in progress?), and optionally score and comment.

Notes

• PASSED — customer fully verified; no action needed.
• FAILED — review individual check fields where passed=false. Common causes: ID mismatch, name mismatch, sanctions hit, poor document quality.
• PENDING at the result level or on individual checks — verification is still in progress; poll after 30–60 seconds.
• Sanctions check failures must be escalated to a compliance officer; do not clear them via API alone.

API Reference: GET /customers/{customerId}/ratify · POST /customers/{customerId}/ratify

2. Trigger KYC Ratification

Trigger: "ratify user", "run KYC", "re-verify customer"

Required inputs: tenantId, customerId

POST {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/ratify
Authorization: Bearer {jwt}
Content-Type: application/json

{}

Request body may be empty ({}) to run the default check set, or include type (NORMAL or COMPARISON) and checksToRun to limit which checks are executed.

Response: A single EclipseKycResult object with individual check fields, status, and lastModified.

After submitting, poll GET .../ratify?offset=0&limit=1 every 30–60 seconds until the top-level status is no longer PENDING.

Expected output: State the overall status. For FAILED or PENDING, list each failing check with its description so the operator knows what to address.

3. AWS Liveness — Eclipse Hosted Flow

Trigger: "aws liveness", "liveness check", "facial liveness", "start liveness session", "liveness detection"

Required inputs: tenantId, customerId, landingUrl (the URL the web view redirects to after liveness completes)

Eclipse Hosted AWS Liveness delegates the entire liveness UI to an Eclipse-managed web view. The channel only needs to open a URL in a web view — Eclipse handles the AWS Amplify SDK, video streaming, and result retrieval.

Prerequisites:

• Tenant config ratifyUserProcessors includes selfieIsLegitimate=AWSLivenessRatifyProcessor
• A valid JWT

Step 1 — Request an AWS liveness session

Post a FACIAL_PHOTO document with mediaType: aws/liveness and a landingUrl in extraInfo. The landingUrl is where Eclipse redirects the customer's browser after the liveness check completes.

POST {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/documents?performOcr=false&validateDocType=false
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "documentType": "FACIAL_PHOTO",
  "mediaType": "aws/liveness",
  "extraInfo": "{\"landingUrl\":\"https://your-app.example.com/liveness/callback\"}"
}

To append custom query parameters to the completionUrl that Eclipse returns, pass the completionUrlParams request header. Eclipse appends the header value directly to the completionUrl after an &.

Response (201 Created):

{
  "documentId": 608561,
  "documentType": "FACIAL_PHOTO",
  "customerId": 1592544,
  "mediaType": "aws/liveness",
  "extraInfo": "{\"landingUrl\":\"https://your-app.example.com/liveness/callback\",\"awsLivenessSessionId\":\"e64e642b-f8db-499b-b3f1-db10f3100387\",\"completionUrl\":\"https://eclipsetests.backdraft.ukheshe.rocks/t/wXExW\"}",
  "awsFaceLivenessSessionId": "e64e642b-f8db-499b-b3f1-db10f3100387"
}

Extract completionUrl from extraInfo — this is the Eclipse-hosted liveness URL to open in the customer's web view.

📘

Note

The AWS session ID expires 3 minutes after issue. Open the completionUrl promptly after receiving it.

Step 2 — Open the completionUrl in a web view

Serve completionUrl in an iFrame or browser. Eclipse manages the full AWS Amplify liveness UI. On completion, the customer's browser is redirected to the landingUrl with one of:

• {landingUrl}?status=COMPLETED — liveness check succeeded
• {landingUrl}?status=CANCELLED — user cancelled or an error occurred

Do not proceed to Step 3 if status=CANCELLED.

Step 3 — Update the FACIAL_PHOTO document to retrieve liveness results

Once status=COMPLETED, PUT the document back using the same documentId and the original response body. This triggers Eclipse to fetch the liveness result and score from AWS and store them on the document.

PUT {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/documents/{documentId}?returnFullResult=false
Authorization: Bearer {jwt}
Content-Type: application/json

{
  "documentId": 608561,
  "documentType": "FACIAL_PHOTO",
  "customerId": 1592544,
  "mediaType": "aws/liveness",
  "extraInfo": "{\"landingUrl\":\"https://your-app.example.com/liveness/callback\",\"awsLivenessSessionId\":\"e64e642b-f8db-499b-b3f1-db10f3100387\",\"completionUrl\":\"https://eclipsetests.backdraft.ukheshe.rocks/t/wXExW\"}",
  "awsFaceLivenessSessionId": "e64e642b-f8db-499b-b3f1-db10f3100387"
}

Response (200 OK):

{
  "documentId": 608561,
  "documentType": "FACIAL_PHOTO",
  "customerId": 1592544,
  "mediaType": "image/jpeg",
  "extraInfo": "{\"AwsFaceLivenessResult\":\"SUCCEEDED\",\"AwsFaceLivenessScore\":\"75.73\",\"landingUrl\":\"https://your-app.example.com/liveness/callback\",\"awsLivenessSessionId\":\"e64e642b-f8db-499b-b3f1-db10f3100387\"}"
}

Check AwsFaceLivenessResult in extraInfo:

• SUCCEEDED — confidence score met the threshold; proceed to ratification
• Anything else — liveness failed; advise the customer to retry

The default confidence score threshold is 55. This is controlled by tenant config aws.face.liveness.ConfidenceScoreMin.

Step 4 — Run KYC ratification

POST {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/ratify
Authorization: Bearer {jwt}
Content-Type: application/json

{}

Poll GET .../ratify?offset=0&limit=1 every 30–60 seconds until status is no longer PENDING.

Notes

• Do not initiate a new liveness session if KYC fails for reasons unrelated to liveness (e.g. name mismatch). Only the failed check needs to be addressed — re-running liveness incurs third-party costs.
• Do not re-run liveness on a customer who has already passed it unless explicitly instructed by an authorised operator.
• If status=CANCELLED at the landingUrl, report the failure to the operator and offer the customer the option to retry from Step 1.

Common Patterns for AI Agents

1. KYC Status Check Flow (Standard)

1. Get KYC status
2. PASSED — no action needed; report to operator
3. PENDING — advise operator to check back in 30–60 seconds
4. FAILED — list each failed check with its description; escalate any sanctions failures to compliance

3. AWS Liveness Flow (Eclipse Hosted)

1. POST FACIAL_PHOTO with mediaType: aws/liveness and landingUrl in extraInfo → receive completionUrl
2. Open completionUrl in the customer's web view
3. On redirect to landingUrl?status=COMPLETED, PUT the document using the original response body → check AwsFaceLivenessResult in extraInfo
4. If SUCCEEDED, POST to ratify
5. Poll GET .../ratify?offset=0&limit=1 until status is no longer PENDING

Do not re-run liveness if KYC fails for a reason other than selfieIsLegitimate.

4. Re-Ratification Flow

Use only when:

• The customer has updated their identity documents
• A previous FAILED attempt had a correctable cause (e.g. name mismatch now resolved)
• Explicitly instructed by an authorised operator

Warning: Re-triggering on a PASSED customer restarts the KYC process. The customer becomes PENDING again until verification completes.

Error Handling

[
  {
    "type": "BUSINESS",
    "severity": "LOW",
    "description": "KYC ratification already in progress",
    "code": "KYC001",
    "traceId": "3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d",
    "spanId": "1a2b3c4d5e6f7a8b",
    "environment": "eclipse-sandbox"
  }
]

Best Practices

• Never re-trigger KYC on a PASSED customer without explicit operator instruction.
• Escalate all sanctions check failures to a compliance officer immediately; do not attempt to clear them programmatically.
• Always state the individual check results when reporting a FAILED status — the top-level status alone is insufficient for diagnosis.
• Apply a 30–60 second polling interval for PENDING status; verification involves external providers and polling faster provides no benefit.
• When a traceId is returned in an error, record it and reference it in any support escalation.