> For the complete documentation index, see [llms.txt](https://docs.tylt.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tylt.money/tylt-crossramp-fiat-crypto-solutions/brazil-brl/reusable-kyc-didit-integration.md).

# 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