KYC Completion Webhook

Business clients receive real-time notifications when KYC (Know Your Customer) verification is completed for one of their customers. This client webhook is triggered automatically when a customer's KYC status is updated to a completion status.

When is this webhook sent?

The kyc_completed webhook is sent when:

A customer's KYC status is updated to PASS, VERIFIED, or APPROVED
The customer belongs to your business
Your business API key has a webhook URL configured

Note: This webhook is only sent for completion statuses. Statuses like PENDING, IN_PROGRESS, FAIL, or REJECTED will not trigger this webhook.

Payload Schema

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

Payload Fields

Field	Type	Required	Description
`event_type`	string	Yes	Always `"kyc_completed"` for this webhook type
`customer_id`	string	Yes	Unique identifier for the customer/user who completed KYC (UUID format)
`status`	string	Yes	KYC status indicating completion: `"PASS"`, `"VERIFIED"`, or `"APPROVED"`
`timestamp`	string	Yes	RFC3339 timestamp indicating when the KYC was completed (UTC)

KYC Status Values

The webhook is only sent when the KYC status is one of these completion values:

Status	Description
`PASS`	KYC verification passed successfully
`VERIFIED`	Customer identity has been verified
`APPROVED`	KYC has been approved

Other statuses like PENDING, IN_PROGRESS, FAIL, or REJECTED will not trigger this webhook.

Example Payloads

Example 1: KYC Passed

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

Example 2: KYC Verified

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

Example 3: KYC Approved

{
  "event_type": "kyc_completed",
  "customer_id": "8ba7b810-9dad-11d1-80b4-00c04fd430c0",
  "status": "APPROVED",
  "timestamp": "2024-01-15T12:00:00Z"
}

Important Notes

Completion Statuses Only: This webhook is only sent when KYC reaches a completion status (PASS, VERIFIED, or APPROVED). Intermediate or failure statuses do not trigger this webhook.
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)
Idempotency: You should implement idempotency handling in your webhook receiver. The same KYC completion event may be sent multiple times if retries occur, so use the customer_id and timestamp combination to deduplicate.

Virtual Wallet Creation Quotes