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

# Didit PHP SDK: KYC, AML 및 거래 모니터링

> Didit 공식 PHP SDK 빠른 시작 가이드입니다. PSR-18 HTTP 클라이언트로 서버 API를 타입 지정 방식으로 호출하고, webhook 검증과 인증 토큰 확인을 수행합니다.

공식 Didit PHP 라이브러리입니다. PHP 8.1 이상이 필요하며, PSR-18 HTTP 클라이언트라면 어느 것과도 함께 사용할 수 있습니다. 일반적으로 Guzzle을 많이 사용합니다. 모든 SDK에 공통되는 내용은 [서버 SDK 개요](https://docs.didit.me/ko/integration/server-sdks/overview.md)를 참고하세요.

## 설치

```bash theme={null}
composer require didit-protocol/sdk-php guzzlehttp/guzzle
```

패키지는 [Packagist의 `didit-protocol/sdk-php`](https://packagist.org/packages/didit-protocol/sdk-php)입니다. 소스 코드와 변경 로그는 GitHub의 [didit-protocol/sdk-php](https://github.com/didit-protocol/sdk-php)에 있습니다.

[Authentication](#authentication-토큰-검증) 토큰 검증에는 `openssl` 확장도 필요합니다.

## 클라이언트 구성

`new DiditClient()`는 환경 변수에서 `DIDIT_API_KEY`를 읽습니다. 이 값을 재정의하거나, 애플리케이션 범위 호출(케이스, 네트워크, 규제 보고서)에 필요한 조직 ID와 애플리케이션 ID를 설정하려면 명명된 인수를 전달하세요. 요청 필드는 API의 필드 이름을 그대로 사용하는 하나의 배열이며, 응답은 camelCase 속성과 `toArray()`를 제공하는 읽기 전용 객체입니다.

```php theme={null}
<?php

require 'vendor/autoload.php';

use Didit\DiditClient;
use Didit\RequestOptions;

$didit = new DiditClient(
    apiKey: getenv('DIDIT_API_KEY') ?: null,
    organizationId: getenv('DIDIT_ORGANIZATION_ID') ?: null,
    applicationId: getenv('DIDIT_APPLICATION_ID') ?: null,
    timeout: 30.0,
    maxRetries: 2,
);

// Options for a single call.
$decision = $didit->sessions->retrieveDecision(
    '11111111-2222-3333-4444-555555555555',
    [],
    new RequestOptions(timeout: 5.0, maxRetries: 0),
);
echo $decision->status, "\n";
```

## 세션 생성

워크플로의 [인증 세션](https://docs.didit.me/ko/sessions-api/create-session.md)을 생성하고, 사용자를 해당 URL로 이동시키세요.

```php theme={null}
<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

$didit = new DiditClient();

$session = $didit->sessions->create([
    'workflow_id' => '11111111-2222-3333-4444-555555555555',
    'vendor_data' => 'user-123',
    'callback' => 'https://example.com/verification/done',
]);
echo $session->url, "\n";
```

## 결정 확인

사용자가 절차를 마치면(또는 webhook이 도착하면) [결정을 확인](https://docs.didit.me/ko/sessions-api/retrieve-session.md)하세요. 모든 기능 결과는 워크플로 노드당 하나의 항목을 가진 목록입니다.

```php theme={null}
<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

$didit = new DiditClient();

$decision = $didit->sessions->retrieveDecision('11111111-2222-3333-4444-555555555555');
echo $decision->status, "\n";
foreach ($decision->idVerifications ?? [] as $verification) {
    echo $verification->status, "\n";
}
```

## Webhook 검증

원본 본문을 수신된 그대로, 그리고 요청 헤더와 함께 전달하세요. `verify`는 유효하지 않거나 유효 기간이 지난 전송에 대해 `WebhookVerificationException`을 던지며, 그렇지 않으면 타입이 지정된 이벤트를 반환합니다.

```php theme={null}
<?php

require 'vendor/autoload.php';

use Didit\DiditClient;
use Didit\Exception\WebhookVerificationException;
use Didit\Webhooks\Events\StatusUpdatedEvent;
use Psr\Http\Message\MessageInterface;

$didit = new DiditClient();

/** @param array<string, string|list<string>>|MessageInterface $headers */
function handleWebhook(DiditClient $didit, string $rawBody, array|MessageInterface $headers, string $secret): int
{
    try {
        $event = $didit->webhooks->verify($rawBody, $headers, $secret);
    } catch (WebhookVerificationException $e) {
        error_log('rejected: ' . $e->reason);
        return 400;
    }
    if ($event instanceof StatusUpdatedEvent) {
        error_log($event->sessionId . ' ' . $event->status);
    }
    return 200;
}

http_response_code(handleWebhook(
    $didit,
    (string) file_get_contents('php://input'),
    getallheaders(),
    (string) getenv('DIDIT_WEBHOOK_SECRET'),
));
```

Laravel과 Symfony에서는 `$request->getContent()`와 `$request->headers->all()`을 전달하세요. PSR-7 요청을 사용하는 경우에는 요청 객체 자체를 헤더로 전달하세요. 비밀 값을 교체하는 동안에는 두 값을 모두 전달하세요: `[$newSecret, $oldSecret]`. 이벤트와 서명 방식은 [Webhook](https://docs.didit.me/ko/integration/webhooks.md)을 참고하세요.

## 거래 스크리닝

결제, 출금 또는 암호화폐 이체를 [거래 모니터링](https://docs.didit.me/ko/transaction-monitoring/overview.md)에 제출하세요. 응답에는 상태와 위험 점수가 포함됩니다.

```php theme={null}
<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

$didit = new DiditClient();

$transaction = $didit->transactions->create([
    'transaction_id' => 'txn-1001',
    'transaction_category' => 'finance',
    'transaction_details' => ['direction' => 'outbound', 'amount' => 1500.0, 'currency' => 'EUR'],
    'subject' => ['entity_type' => 'individual', 'vendor_data' => 'user-123', 'full_name' => 'Maria Garcia'],
]);
echo $transaction->status, ' ', $transaction->score, "\n";
```

## Authentication 토큰 검증

`Authentication`은 백엔드에서 [Authentication](https://docs.didit.me/ko/authentication/overview.md) 발급자가 서명한 액세스 토큰을 검증하며, 요청마다 Didit을 호출하지 않습니다. 발급자의 키를 요청마다 가져오지 않고 한 번만 가져오도록 PSR-16 캐시를 전달하세요. 또한 코드를 교환하고, 토큰을 갱신하고, 세션을 확인 및 취소하고, 추가 인증을 실행합니다.

> [!NOTE]
>
> 토큰 검증은 애플리케이션의 발급자 및 서명 키를 기준으로 [서버에서 토큰 검증하기](https://docs.didit.me/ko/authentication/tokens-and-jwks.md#서버에서-토큰-검증)의 검사를 수행합니다.

```php theme={null}
<?php

require 'vendor/autoload.php';

use Didit\Authentication\Authentication;
use Didit\Authentication\TokenVerificationException;

// The publishable key (pk_live_... or pk_test_...) carries your issuer URL.
$auth = Authentication::fromPublishableKey('pk_live_...');

function currentUser(Authentication $auth, string $accessToken): ?string
{
    try {
        $claims = $auth->verifyAccessToken($accessToken, audience: 'your-application-id');
    } catch (TokenVerificationException $e) {
        error_log('rejected: ' . $e->reason);
        return null;
    }
    return $claims->sub;
}
```

## 오류

```php theme={null}
<?php

require 'vendor/autoload.php';

use Didit\DiditClient;
use Didit\Exception\ApiStatusException;
use Didit\Exception\NotFoundException;

$didit = new DiditClient();

try {
    $didit->sessions->retrieveDecision('11111111-2222-3333-4444-555555555555');
} catch (NotFoundException $e) {
    echo "no such session\n";
} catch (ApiStatusException $e) {
    echo $e->status, ' ', $e->requestId, "\n";
}
```

## 목록 및 파일

```php theme={null}
<?php

require 'vendor/autoload.php';

use Didit\DiditClient;
use Didit\File;

$didit = new DiditClient();

// Lists page through every result.
foreach ($didit->sessions->list(['status' => 'Approved']) as $session) {
    echo $session->sessionId, "\n";
}

// Uploads take File::fromPath, File::fromBytes or File::fromStream.
$result = $didit->idVerification->verify([
    'front_image' => File::fromPath('id-front.jpg'),
    'back_image' => File::fromPath('id-back.jpg'),
]);
print_r($result->toArray());
```

[API 참조](https://docs.didit.me/ko/api-reference/overview.md)의 서버 엔드포인트 페이지에는 각 작업에 대한 PHP 샘플이 있습니다. 다만 1.0.1 릴리스에 아직 포함되지 않은 엔드포인트와 필드는 예외이며, 이는 [개요](https://docs.didit.me/ko/integration/server-sdks/overview.md)에 명시되어 있습니다.


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