# Reusable KYC (Didit Integration)

***

### Overview

To enable reusable KYC:

* The merchant completes KYC on Didit
* The merchant must provide the Didit `sessionId` as part of the Create Instance API request. This is done via the `userDetails` object using the reserved `kyc` key. 
* Tylt calls a merchant-provided endpoint to retrieve the reusable KYC session. The details of the endpoint that must be exposed to Tylt are provided below.
* The merchant generates a Didit `share_token`
* Tylt imports and validates the KYC session

***

### Passing KYC Details to Tylt

The merchant must provide the Didit `sessionId` as part of the Create Instance API request. This is done via the `userDetails` object using the reserved `kyc` key. 

```json
{
  "userDetails": {
    "kyc": {
      "source": "Didit",
      "sessionId": "string"
    }
  }
}
```

***

### Merchant Setup

The merchant must expose a secure backend endpoint that Tylt can call to retrieve a reusable KYC session.

***

### Standard Endpoint Specification

#### Endpoint

```http
POST /tylt-kyc/didit/share-session
```

* Must be accessible over HTTPS
* Must be server-to-server only

***

### Request (Tylt → Merchant)

```json
{
  "merchantOrderId": "string",
  "sessionId": "string",
  "tyltDiditApplicationId": "string"
}
```

#### Field Definitions

| Field                    | Type   | Required | Description                           |
| ------------------------ | ------ | -------: | ------------------------------------- |
| `merchantOrderId`        | string |      Yes | Unique identifier for the transaction |
| `sessionId`              | string |      Yes | Didit session ID of completed KYC     |
| `tyltDiditApplicationId` | string |      Yes | Tylt’s Didit application ID           |

***

### Expected Merchant Behavior

Upon receiving the request, the merchant must:

1. Authenticate and validate the request
2. Verify the `sessionId` exists and is eligible
3. Call Didit Share Session API internally
4. Generate a `share_token`
5. Return the token to Tylt

***

### Internal Didit API Call

#### Endpoint

```http
POST https://verification.didit.me/v3/session/{sessionId}/share/
```

#### Headers

```http
Content-Type: application/json
x-api-key: <merchant-didit-api-key>
```

#### Body

```json
{
  "for_application_id": "<tyltDiditApplicationId>",
  "ttl_in_seconds": 300
}
```

***

### Response (Merchant → Tylt)

#### Success

```json
{
  "success": true,
  "merchantOrderId": "string",
  "sessionId": "string",
  "shareToken": "string"
}
```

#### Error

```json
{
  "success": false,
  "merchantOrderId": "string",
  "sessionId": "string",
  "errorCode": "string",
  "message": "string"
}
```

***

### Error Codes

| Code                   | Description                     |
| ---------------------- | ------------------------------- |
| `INVALID_REQUEST`      | Missing or invalid fields       |
| `UNAUTHORISED`         | Authentication failed           |
| `SESSION_NOT_FOUND`    | Session does not exist          |
| `SESSION_NOT_ELIGIBLE` | Session cannot be reused        |
| `SHARE_SESSION_FAILED` | Didit share-session call failed |
| `INTERNAL_ERROR`       | Unexpected error                |

***

### End-to-End Flow

1. Merchant completes KYC on Didit
2. Merchant stores `sessionId`
3. Merchant sends `sessionId` to Tylt
4. Tylt calls merchant endpoint
5. Merchant calls Didit `/share/` API
6. Merchant returns `shareToken`
7. Tylt imports and validates session

***

### Outcome

* **Valid & accepted** → User skips KYC
* **Invalid / expired / rejected** → Standard KYC flow

***

### Important Notes

* Only completed Didit sessions are eligible
* `shareToken` is time-limited and single-use
* Merchant must use their own Didit API credentials
* `tyltDiditApplicationId` must be used as `for_application_id`
* Reusable KYC is subject to Tylt compliance checks
* KYC bypass is not guaranteed
* Merchant must ensure user consent for sharing KYC data


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tylt.money/introduction/tylt-crossramp-fiat-crypto-solutions/brazil-brl/reusable-kyc-didit-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.