> ## 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으로 구현하세요.

Didit Authentication의 검증된 신원 확인은 사용자가 본인임을 증명하도록, 선택한 시점에 요청합니다. 계정을 만들기 전과 지급처럼 민감한 작업을 하기 전에 다시 요청합니다.
앱은 확인 결과와 선택한 검증된 클레임(예: `over_18` 또는 검증된 이름)을 사용자의 토큰으로 받으며, 사용자의 문서나 사진은 받지 않습니다.

설정은 콘솔의 **Authentication > Verified identity**에서 하거나, [`verified/`](#api로-설정하기) API로 할 수 있습니다.

![Didit Business Console의 Verified identity 페이지. 가입 시 확인 수준과 가격, 민감한 작업 전 단계별 인증 규칙이 표시되어 있습니다.](https://mintcdn.com/didit-0f962782/RpqZjIB1GnUPdMTN/images/authentication/console-verified-identity.png?fit=max\&auto=format\&n=RpqZjIB1GnUPdMTN\&q=85\&s=98544caeedf5ffaf68484cace19f9b3f)

Authentication > Verified identity: 가입 시 확인과 민감한 작업 전 규칙.

## 작동 방식

모든 확인은 귀사 애플리케이션의 인증 세션으로 실행되며, 사용자의 `vendor_data`로 생성됩니다.
즉, 해당 세션은 귀사의 인증 내역에 표시되고 같은 사용자의 로그인 및 거래 기록과 함께 나타납니다. 다른 인증과 마찬가지로 수동 검토 대상이 되며, 그 인증의 요금이 청구됩니다.

| 확인 | 사용자가 하는 일 | 정가 |
| - | - | - |
| 라이브니스 | 셀피를 한 장 촬영하고 라이브니스 여부를 확인합니다. | \$0.10 |
| 셀피 로그인 | 셀피를 촬영하면 Didit이 이미 보유한 해당 사용자의 얼굴과 대조합니다. | \$0.10 |
| 전체 신분증 인증 | 신분증을 스캔하고 셀피를 촬영합니다: 문서, 라이브니스, 얼굴 대조. | \$0.33 |

Didit은 각 확인을 기본 워크플로로 실행하거나, 해당 확인을 위해 선택한 귀사의 워크플로 중 하나로 실행합니다.
모든 인증 요금은 [요금](https://docs.didit.me/ko/getting-started/pricing.md)에서 확인하실 수 있습니다.

## 회원가입 시

회원가입을 완료하려면 사용자가 통과해야 하는 수준을 선택하세요:

| 수준 | 값 | 의미 |
| - | - | - |
| 인증 없음 | `none` | 이메일, 전화번호 또는 패스키가 있으면 누구나 가입할 수 있습니다. 기본값입니다. |
| 라이브니스 감지 | `liveness` | 실제 사람이 가입합니다. 셀피 한 장을 촬영해 라이브니스를 확인합니다. |
| 전체 신분증 인증 | `full_id` | 계정이 생성되기 전에 문서 확인, 라이브니스 감지, 얼굴 대조를 수행합니다. |

새 수준은 그 이후에 가입하는 사용자에게만 적용되며, 기존 계정에는 적용되지 않습니다.

호스팅 페이지에서는 Didit이 회원가입 중에 사용자를 인증 절차로 안내합니다.
직접 만든 화면에서는 회원가입 호출이 `verification_required`와 함께 30분 동안 유효한 `verification_url`을 반환합니다. 사용자를 해당 URL로 안내하세요.
Didit은 인증이 승인된 후에만 로그인 코드를 발급합니다.

## 민감한 작업 전 추가 인증

추가 인증은 작업의 위험도가 충분히 높을 때만 사용자에게 다시 본인 확인을 요청합니다.
규칙을 켜면 앱은 민감한 작업을 실행하기 전에 Didit에 해당 규칙이 적용되는지 문의합니다.

![셀피로 본인임을 확인하라고 요청하는 추가 인증 화면이 표시된 휴대폰](https://mintcdn.com/didit-0f962782/RpqZjIB1GnUPdMTN/images/authentication/step-up-preview.png?fit=max\&auto=format\&n=RpqZjIB1GnUPdMTN\&q=85\&s=dd5087d0ba5f20b49bbd4252149ef8ca)

추가 인증에서 셀피를 요청할 때 사용자에게 보이는 화면입니다.

| 규칙 | 요청 시점 | 기본 확인 방식 |
| - | - | - |
| `payout` | 출금 또는 이체 금액이 설정한 임계값(예: 해당 통화 기준 500)을 넘을 때. 다른 통화로 하는 출금은 항상 확인합니다. | 셀피 로그인 |
| `device` | 사용자의 이전 세션 중 어느 것에서도 사용하지 않은 기기에서 출금이 이루어질 때. | 셀피 로그인 |
| `bank` | 사용자가 은행 계좌를 추가하거나 변경할 때. | 전체 신분증 인증 |
| `contact` | 사용자가 이메일 주소나 전화번호를 변경할 때. | 라이브니스 |

각 규칙의 확인 방식은 라이브니스, 셀피 로그인, 전체 신분증 인증 중에서 변경할 수 있습니다.
여러 규칙이 동시에 적용되면 Didit은 가장 강한 확인 방식을 요청합니다.
Didit이 아직 사용자의 얼굴 정보를 가지고 있지 않으면 셀피 로그인은 전체 신분증 인증으로 바뀝니다.

### 추가 인증 요청하기

앱은 사용자의 액세스 토큰과 함께 `POST {issuer}/step-up/`을 호출하거나 SDK의 `stepUp()` 메서드를 사용합니다.

```bash theme={null}
curl --fail-with-body "${DIDIT_AUTH_ISSUER}/step-up/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "payout", "amount": "900.00", "currency": "USD", "return_to": "https://app.example.com/payouts/confirm"}'
```

| 필드 | 규칙 |
| - | - |
| `action` | `payout`, `bank` 또는 `contact`. 출금 또는 이체에는 `device` 규칙도 적용됩니다. |
| `amount` | `payout`에는 필수이며, 소수점 이하 두 자리까지 입력할 수 있습니다. |
| `currency` | ISO 4217 코드입니다. 기본값은 출금 규칙의 통화입니다. |
| `return_to` | 사용자가 인증을 마친 후 돌아갈 위치입니다. 규칙이 적용되면 등록한 [리디렉션 URL](https://docs.didit.me/ko/authentication/overview.md#리디렉션-url) 중 하나여야 합니다. |

* `200 {"required": false}`: 적용되는 규칙이 없으므로 작업을 진행하면 됩니다.
* `201`과 `verification_url`: 사용자를 해당 URL로 보냅니다. 추가 인증은 30분 동안 유효합니다(`expires_in: 1800`).

### 백엔드에서 결과 읽기

사용자는 `step_up=<id>&status=approved`가 추가된 `return_to`로 돌아오지만, 이 쿼리 값만으로는 인증이 완료되었음을 증명할 수 없습니다.
백엔드는 `GET {issuer}/step-up/{step_up_id}/`를 같은 세션의 액세스 토큰과 함께 호출하여 추가 인증 상태를 읽고, `status`가 `approved`일 때만 작업을 진행해야 합니다.

| 상태 | 의미 |
| - | - |
| `pending` | 사용자가 아직 확인을 마치지 않았습니다. |
| `approved` | 사용자가 통과했습니다. 작업을 진행하면 됩니다. |
| `review` | 확인 결과가 귀사 팀의 검토를 기다리고 있습니다. |
| `declined` | 사용자가 통과하지 못했습니다. `verification_url`이 계속 작동하는 동안에는 최종 결과가 아닙니다. 사용자가 다시 시도할 수 있으며, 추가 인증은 `pending` 상태로 돌아갑니다. |
| `expired` | 30분이 지났습니다. 새 추가 인증을 생성하세요. |
| `superseded` | 다른 확인이 이를 대체했거나, 결과가 이 추가 인증에 해당하지 않습니다. 새로 생성하세요. |

추가 인증은 어떤 경우에도 실패 시 작업을 허용하지 않습니다. 인증을 사용할 수 없으면 작업은 계속 차단된 상태로 유지됩니다.
SDK 쪽 구현은 [JavaScript](https://docs.didit.me/ko/authentication/quickstarts/javascript.md#단계별-인증-및-재인증), [Next.js](https://docs.didit.me/ko/authentication/quickstarts/nextjs.md#민감한-작업-전-추가-인증), [iOS](https://docs.didit.me/ko/authentication/quickstarts/ios.md#민감한-작업-전-추가-인증) 퀵스타트에서 확인할 수 있고, 전체 계약 내용은 [API 레퍼런스](https://docs.didit.me/ko/authentication/api-reference/create-step-up.md)에 있습니다.

## 앱이 받는 항목

사용자의 토큰에 포함할 검증된 클레임을 선택합니다.

| 클레임 | 값 |
| - | - |
| `over_18`, `over_21` | 검증된 생년월일 기준으로 사용자가 18세 또는 21세 이상인지 여부입니다. |
| `given_name`, `family_name` | 검증된 이름과 성입니다. |
| `birthdate` | 신분증에 기재된 생년월일이며, 형식은 `YYYY-MM-DD`입니다. |
| `nationality` | ISO 3166-1 alpha-2 코드입니다. |
| `country` | 신분증 발급 국가의 ISO 3166-1 alpha-2 코드입니다. |
| `document_verified` | 신분증 인증이 완료되었는지 여부입니다. |
| `liveness` | 라이브니스 검사를 통과했는지 여부입니다. |

액세스 토큰과 ID 토큰은 이 클레임을 `verified`에 담으며, 사용자가 통과한 가장 높은 수준은 `level`에 담습니다. 그 값은 `liveness`, `liveness_face_match` 또는 `full_id`입니다. 사용자가 어떤 검사도 통과하지 못했다면 `{}`이며, `GET /session/`은 `null`을 반환합니다.

```json theme={null}
{
  "verified": {
    "level": "full_id",
    "over_18": true,
    "given_name": "Alex",
    "country": "ES"
  }
}
```

* 세션 중에 승인된 검사는 5분 이내에 다음 토큰 갱신 시 토큰에 반영됩니다.
* 토큰을 가진 모든 주체는 이 클레임을 읽을 수 있으며, 여기에는 프런트엔드도 포함됩니다. 따라서 앱에 필요한 개인 클레임만 선택하십시오.
* 앱은 클레임만 받으며, 신분증 문서, 셀피, 얼굴 데이터는 받지 않습니다.

## API로 설정하기

애플리케이션의 [인증 관리 API](https://docs.didit.me/ko/authentication/set-up-by-api.md)에 있는 `verified/` endpoint의 `GET`과 `PATCH`는 콘솔과 같은 설정을 읽고 변경합니다.

```bash theme={null}
curl --fail-with-body --request PATCH "${MANAGEMENT_BASE}verified/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signup_level": "liveness",
    "rules": [
      {"rule": "payout", "enabled": true, "method": "selfie", "threshold": "500.00", "currency": "USD"},
      {"rule": "bank", "enabled": true, "method": "full_id"}
    ],
    "claims": ["over_18", "given_name", "country"]
  }'
```

| 필드 | 값 |
| - | - |
| `signup_level` | `none`, `liveness` 또는 `full_id`. |
| `rules` | 변경하는 규칙마다 항목 하나씩. `rule`(`payout`, `device`, `bank` 또는 `contact`), `enabled`, `method`(`liveness`, `selfie` 또는 `full_id`)를 지정하며, `threshold`와 `currency`는 `payout`에만 해당합니다. |
| `claims` | 토큰에 포함할 클레임입니다. 위 표에서 선택합니다. |
| `workflows` | 선택 사항입니다. `liveness`, `selfie` 또는 `full_id`에 사용할 자체 워크플로 ID를 입력하거나, Didit 기본값을 사용하려면 `null`을 입력합니다. |

생략한 규칙은 현재 설정을 그대로 유지합니다.


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