KYC Completion Webhook

Business clients receive a notification when a customer's identity verification is finished. This webhook is only sent when every required identity check for that customer has cleared.

When is this webhook sent?

The kyc_completed webhook is sent when:

  • The customer belongs to your business
  • Your business API key has a webhook URL configured
  • Every required identity verification check for that customer has completed successfully

A single identity check clearing is not enough. For example, a customer who has passed the first identity check but is still pending a second required check will not receive this webhook yet. The webhook fires once, when the last required check clears.

A terminal identity rejection can also send this webhook with status: "REJECTED".

Payload Schema

json
{  "event_type": "kyc_completed",  "customer_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",  "status": "APPROVED",  "timestamp": "2024-01-15T10:30:00Z"}

Payload Fields

FieldTypeRequiredDescription
event_typestringYesAlways "kyc_completed" for this webhook type
customer_idstringYesUnique identifier for the customer who completed KYC (UUID format)
statusstringYesFinal KYC outcome: "APPROVED" or "REJECTED"
timestampstringYesRFC3339 timestamp indicating when the event was emitted (UTC)

Status Values

StatusDescription
APPROVEDEvery required identity verification check has cleared for this customer
REJECTEDIdentity verification failed and the customer cannot complete KYC

Intermediate states such as PENDING do not trigger this webhook.

Example Payloads

Example 1: KYC Approved

json
{  "event_type": "kyc_completed",  "customer_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",  "status": "APPROVED",  "timestamp": "2024-01-15T10:30:00Z"}

Example 2: KYC Rejected

json
{  "event_type": "kyc_completed",  "customer_id": "7ba7b810-9dad-11d1-80b4-00c04fd430c9",  "status": "REJECTED",  "timestamp": "2024-01-15T11:45:00Z"}

Important Notes

  1. All checks must clear: This webhook is sent only after every required identity verification check has completed. Use GET /api/v1/client/customers/:customer_id/onboarding-status and the kyc_state field if you need to poll while checks are still in progress.

  2. Webhook Security: This webhook uses the same security mechanism as other business webhooks:

    • Signed with HMAC-SHA256 using your API key's secret
    • Includes X-Transfaar-Signature header for verification
    • Same retry logic applies (up to 10 attempts with exponential backoff, only retries if response is not 200 OK)

  3. Idempotency: The completion event is emitted once per customer when KYC becomes fully complete. Your webhook receiver should still treat deliveries as at-least-once and deduplicate by customer_id and status.