# 사용자 검증 요청 API
## 사용자 검증 요청
`POST` `http:///v1/verifications`
> Beneficiary VASP로 beneficiary에 대해 검증 요청하는 API입니다.
>
> 이 API는 비동기 방식으로 동작하기 때문에, 검증 결과를 알기 위해서는 응답으로 받은 **verificationUuid**를 통해 검증 이력을 지속적으로 조회하거나, Callback VASP API를 구현하여 콜백을 통해 확인할 수 있습니다.
## Request Body
Request Body Examples
```json
{
"keyType": "PerVerification",
"beneficiaryVaspId": "16384656509591635927",
"assetInfo": {
"symbol": "BTC",
"network": "Bitcoin",
"amount": "0.024",
"tradePrice": "100",
"tradeCurrency": "KRW",
"tradeISODatetime": "2022-04-20T05:59:42.506Z",
"isExceedingThreshold": true
},
"requiredBeneficiaryInfo": "ACCOUNT_NUMBER,NATURAL_PERSON_NAME",
"payload": {
"version": "1.0",
"ivms101": {
"originator": {
"originatorPersons": [
{
"naturalPerson": {
"name": {
"nameIdentifier": [
{
"primaryIdentifier": "James",
"secondaryIdentifier": "Din",
"nameIdentifierType": "LEGL"
}
]
}
}
}
],
"accountNumber": ["1P8j2mhMszoC7P69oqZF2n8fLK3TL3wFgJ"]
},
"beneficiary": {
"beneficiaryPersons": [
{
"naturalPerson": {
"name": {
"nameIdentifier": [
{
"primaryIdentifier": "Robbins",
"secondaryIdentifier": "Taylor",
"nameIdentifierType": "LEGL"
}
]
}
}
}
],
"accountNumber": ["1G3qCGKP5dQtQ7secCPTCDPU9Wfjp9x3Hb"]
}
}
}
}
```
| Field Name | Data Type | Required | Description |
| ------------------------------ | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| keyType | string | true | 개인정보 암호화에 사용할 Public Key 타입.
”PerVasp”, “PerEoa”, “PerVerification” 이 세 가지 타입 중 하나를 선택 가능합니다. default는 PerVasp
BeneficiaryVASP는 OriginatingVASP가 선택한 Key Type에 따른 Public Key를 제공해야 합니다.
|
| beneficiaryVaspId | string | true | 수신 VASP의 VASP ID |
| requiredBeneficiaryInfo | string | true | 송신 VASP에서 수신자를 검증하기 위해 필요한 수신자에 대한 개인 정보 필드 목록, 쉼표(,)로 구분한다 (코드는 하단을 참조) |
| assetInfo.symbol | string | true | 가상 자산 심벌 |
| assetInfo.network | string | false | 가상 자산이 배포되어 있는 블록체인 네트워크 이름 (자세한 사항은 '추가 정보' 메뉴 하단의 'network 필드 가이드'를 참조) |
| assetInfo.amount | string | true | 가상 자산 전송량 |
| assetInfo.isExceedingThreshold | boolean | true | 법령에서 정해진 금액 이상의 출금인지에 대한 여부를 표시하는 flag 필드 |
| assetInfo.tradeCurrency | string | true | 법정 화폐로 환산할 때 사용한 법정 화폐 코드 (ISO 4217 기준) |
| assetInfo.tradePrice | string | true | 법정 화폐로 환산된 가상 자산 전송 금액. 자체 시세 정보가 없는 경우에는 타 거래소의 시세 API를 사용하여 환산 |
| assetInfo.tradeISODatetime | string | true | 법정 화폐로 환산할 때 사용된 시세 기준 시간 |
| payload | object | true | Originator와 Beneficiary에 대한 정보를 IVMS101 형태로 전달합니다. |
| payload.version | string | true | IVMS101 메시지 포맷에 대한 버전. |
| payload.ivms101 | object | true | Originator와 Beneficiary에 대한 정보를 IVMS101 형태로 전달한다. IVMS101 메시지 프로토콜 참조. IVMS101 메시지 가이드 문서 참조. |
## Response Body
### 성공 케이스
Response Body Examples
* 200 OK
```json
{
"verificationUuid": "8557f2b2-985e-431f-8d52-75c2e5a01e46",
"createdAt": "2022-04-20T05:59:45.306Z"
}
```
| Field Name | Data Type | Required | Description |
| ---------------- | --------- | -------- | -------------- |
| verificationUuid | string | true | 사용자 검증 요청 ID |
| createdAt | string | true | 사용자 검증을 요청한 시각 |
* 기존의 사용자 검증 결과를 알기 위해서는 2가지 방법이 있습니다.
* `polling` 방식으로 사용자 검증 결과 조회 API를 호출하여 사용자 검증 결과를 가져옵니다.
* `Callback API`를 구현하고 그 endpoint URL을 Enclave 서버의 환경 변수로 입력하여, 사용자 검증 결과가 리포트되었을 때 callback 호출을 받습니다.
### 에러 케이스
#### 필수 파라미터를 입력하지 않은 경우
Response Body Examples
* 400 Bad Request
```json
{
"code": "MISSING-REQUIRED-BENEFICIARY-INFO",
"message": "`requiredBeneficiaryInfo` is required."
}
```
#### 잘못된 파라미터를 입력한 경우
Response Body Examples
* 400 Bad Request
```json
{
"code": "INVALID-REQUIRED-BENEFICIARY-INFO",
"message": "'requiredBeneficiaryInfo' is required 'ACCOUNT_NUMBER'"
}
```
#### beneficiaryVaspId에 VerifyVASP에 회원 가입하지 않은 VASP의 ID를 입력한 경우
Response Body Examples
* 400 Bad Request
```json
{
"code": "ALLIANCE-NOT-FOUND",
"message": "Alliance is not found in given vendor"
}
```
#### beneficiaryVaspId에 VerifyVASP에 회원 가입은 했지만 active 상태가 아닌 VASP의 ID를 입력한 경우
Response Body Examples
* 400 Bad Request
```json
{
"code": "ALLIANCE-NOT-ACTIVE",
"message": "Alliance is not active now"
}
```
#### 응답 시간이 초과되었을 경우
Response Body Examples
* 408 Request Timeout
```json
{
"code": "REQUEST-TIMEOUT",
"message": "timeout of 5000ms exceeded"
}
```
## Links
### 사용자 개인 정보 종류 코드
* `Request Body`의 **requiredBeneficiaryInfo** 필드의 값은 아래 링크 정보를 참조합니다.
{% content-ref url="/pages/7eieRI1CXQP64lZeluEk" %}
[IVMS101 사용자 개인 정보 종류 코드](/reference/ivms101/ivms101-personal-info-codes.md)
{% endcontent-ref %}
---
# 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-kr.verifyvasp.com/reference/enclave-api-reference/v1/verification-request-api.md?ask=
```
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.