> For the complete documentation index, see [llms.txt](https://docs-kr.verifyvasp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-kr.verifyvasp.com/reference/enclave-api-reference/v1/verification-request-api.md).
# 사용자 검증 요청 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 %}