> ## Documentation Index
> Fetch the complete documentation index at: https://developer.tazapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# KYC Link Webhooks

<br />

## KYC link status specific events

| Event | Description | Default |
| - | - | - |
| `kyc_link.pending` | Triggered when a KYC link is generated | On |
| `kyc_link.requires_action` | Triggered when the individual must resubmit through the same link | On |
| `kyc_link.approved` | Triggered when the verification is approved | On |
| `kyc_link.rejected` | Triggered when the verification is rejected | On |
| `kyc_link.expired` | Triggered when a KYC link expires or is expired through the API | On |

## Payload

The `data.kyc_link` object in every event has the same shape as the [Fetch KYC Link](/api-reference/tazapay-api/retrieve-kyc-link) response. Fields without a value are sent as `null` rather than omitted: `completed_at` is `null` until the link is approved, rejected or expired, and `verification_result` is `null` until the link is approved or rejected. See [KYC Link](/api-reference/tazapay-api/kyc-link) for the field reference. Unlike the API response, `document_number` is masked in webhook payloads.

## Sample Events

### kyc\_link.pending

```json expandable theme={null}
{
  "type": "kyc_link.pending",
  "id": "evt_aaaaaaaaaaaaaaaaaaa1",
  "object": "event",
  "created_at": "2026-09-25T10:15:01Z",
  "data": {
    "entity_id": "ent_aaaaaaaaaaaaaaaaaaaa",
    "kyc_link": {
      "url": "https://verify.example.com/kyc/demo-link-001",
      "status": "pending",
      "created_at": "2026-09-25T10:00:00Z",
      "expires_at": "2026-10-25T10:00:00Z",
      "completed_at": null,
      "verification_result": null,
      "metadata": null
    }
  }
}
```

### kyc\_link.requires\_action

```json expandable theme={null}
{
  "type": "kyc_link.requires_action",
  "id": "evt_aaaaaaaaaaaaaaaaaaa2",
  "object": "event",
  "created_at": "2026-09-25T10:15:01Z",
  "data": {
    "entity_id": "ent_aaaaaaaaaaaaaaaaaaaa",
    "kyc_link": {
      "url": "https://verify.example.com/kyc/demo-link-001",
      "status": "requires_action",
      "created_at": "2026-09-25T10:00:00Z",
      "expires_at": "2026-10-25T10:00:00Z",
      "completed_at": null,
      "verification_result": null,
      "metadata": {
        "customer_reference": "customer_demo_001"
      }
    }
  }
}
```

### kyc\_link.approved

```json expandable theme={null}
{
  "type": "kyc_link.approved",
  "id": "evt_aaaaaaaaaaaaaaaaaaa3",
  "object": "event",
  "created_at": "2026-09-25T10:15:01Z",
  "data": {
    "entity_id": "ent_aaaaaaaaaaaaaaaaaaaa",
    "kyc_link": {
      "url": "https://verify.example.com/kyc/demo-link-001",
      "status": "approved",
      "created_at": "2026-09-25T10:00:00Z",
      "expires_at": "2026-10-25T10:00:00Z",
      "completed_at": "2026-09-25T10:15:00Z",
      "verification_result": {
        "outcome": "approved",
        "rejection_type": null,
        "rejection_reasons": [],
        "checks": {
          "identity": {
            "status": "passed",
            "document_type": "ID_CARD",
            "document_country": "IND",
            "document_number": "123****789",
            "document_expiry": "2035-12-31"
          },
          "address": {
            "status": "passed",
            "document_type": "UTILITY_BILL"
          },
          "selfie": {
            "status": "passed",
            "document_type": "SELFIE",
            "document_country": "IND",
            "document_number": null,
            "document_expiry": null
          }
        },
        "extracted_data": {
          "first_name": "Alex",
          "last_name": "Morgan",
          "date_of_birth": "1990-05-15",
          "nationality": "IND",
          "address": {
            "line1": "12 Example Street",
            "line2": "Apartment 4B",
            "city": "Example City",
            "state": "Example State",
            "postal_code": "110001",
            "country": "IND"
          }
        }
      },
      "metadata": {
        "customer_reference": "customer_demo_001"
      }
    }
  }
}
```

### kyc\_link.rejected

```json expandable theme={null}
{
  "type": "kyc_link.rejected",
  "id": "evt_aaaaaaaaaaaaaaaaaaa4",
  "object": "event",
  "created_at": "2026-09-25T10:15:01Z",
  "data": {
    "entity_id": "ent_aaaaaaaaaaaaaaaaaaaa",
    "kyc_link": {
      "url": "https://verify.example.com/kyc/demo-link-001",
      "status": "rejected",
      "created_at": "2026-09-25T10:00:00Z",
      "expires_at": "2026-10-25T10:00:00Z",
      "completed_at": "2026-09-25T10:15:00Z",
      "verification_result": {
        "outcome": "rejected",
        "rejection_type": "FINAL",
        "rejection_reasons": [
          {
            "code": "SELFIE_MISMATCH",
            "description": "The submitted selfie could not be matched to the identity document.",
            "user_message": "Please contact support for assistance."
          }
        ],
        "checks": {
          "identity": {
            "status": "failed",
            "document_type": "PASSPORT",
            "document_country": "IND",
            "document_number": "Z12****678",
            "document_expiry": "2032-08-14"
          },
          "address": {
            "status": "failed",
            "document_type": "UTILITY_BILL"
          },
          "selfie": {
            "status": "failed",
            "document_type": "SELFIE",
            "document_country": "IND",
            "document_number": null,
            "document_expiry": null
          }
        },
        "extracted_data": {
          "first_name": "Alex",
          "last_name": "Morgan",
          "date_of_birth": "1990-05-15",
          "nationality": "IND",
          "address": {
            "line1": "12 Example Street",
            "line2": "Apartment 4B",
            "city": "Example City",
            "state": "Example State",
            "postal_code": "110001",
            "country": "IND"
          }
        }
      },
      "metadata": {
        "customer_reference": "customer_demo_001"
      }
    }
  }
}
```

### kyc\_link.expired

```json expandable theme={null}
{
  "type": "kyc_link.expired",
  "id": "evt_aaaaaaaaaaaaaaaaaaa5",
  "object": "event",
  "created_at": "2026-09-26T10:12:01Z",
  "data": {
    "entity_id": "ent_aaaaaaaaaaaaaaaaaaaa",
    "kyc_link": {
      "url": "https://verify.example.com/kyc/demo-link-001",
      "status": "expired",
      "created_at": "2026-09-25T10:00:00Z",
      "expires_at": "2026-09-26T10:00:00Z",
      "completed_at": "2026-09-26T10:12:00Z",
      "verification_result": null,
      "metadata": {
        "customer_reference": "customer_demo_001"
      }
    }
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.