사용자 검증 API

사용자 검증 API

POST VEGA_VERIFICATION_API_PATH

Enclave 환경 변수:

VEGA_VERIFICATION_API_PATH 변수에, 사용자 검증 API 엔드포인트를 명시합니다.

VASP는 Originating VASP, Beneficiary VASP 두 역할을 모두 수행하게 되는데, 이 API는 VASP가 Beneficiary VASP 역할을 할 때 호출되는 API입니다.

Originating VASP에서 출금을 진행하기 전에 Beneficiary(수신자)에 대한 검증 요청 시 호출되는 API입니다.

  • API에서 처리해야 할 내용은 아래와 같습니다.

    • Beneficiary의 이름을 확인합니다.

    • Beneficiary의 address(계좌번호 또는 지갑 주소)를 확인합니다.

    • KYC 인증 여부를 확인합니다.

    • AML 인증 여부를 확인합니다.

    • Originator(송신인)에 대한 STR monitoring이나 sanction screening을 수행합니다.

    • 전달받은 송신인, 수신인의 개인 정보에 대해, VASP 자체적으로 추가적인 필터링이나 검증 작업을 진행하여도 됩니다.

사용자 검증이 정상적으로 끝났다면, Beneficiary에 대한 추가 개인 정보를 IVMS101 메시징 포맷으로 반환합니다.

응답 시간:

이 사용자 검증 요청 API는 최대 5초 이내에 응답해야 합니다.

구현 정책:

  • 사용자 검증 API 구현 시, Beneficiary Name 검증에 대한 가이드입니다.

    • 전송할 가상 자산 금액이 법령에서 정한 금액보다 작을 경우 트래블룰 대상이 아니므로 VerifyVASP를 통한 검증은 필수 사항이 아닙니다.

    • 하지만, 모든 출금 요청에 VerifyVASP를 통해 처리하고자 한다면, 법령에서 정한 금액이 넘는 경우와 그렇지 않은 경우 이 모두를 동일한 수준으로 사용자 검증을 하기에는 무리가 있습니다.

    • Beneficiary VASP에서는, 법령이 정한 금액 보다 작은 경우(isExceedingThreshold 값이 false인 경우)에는 Beneficiary의 이름에 대한 매칭 검증을 수행하지 않도록 합니다.

  • 사용자 검증 API 구현 시, Originating VASP가 요청한 정보(requiredBeneficiaryInfo)는 모두 기입해야 합니다.

    • Originating VASP가 요청한 정보가 없거나 정보를 제공하기를 원하지 않으면, verificationResult를 DENIED로, reason을 UNAVAILABLE-INFORMATION으로 반환합니다.

    • Originating VASP가 요청하지 않은 정보는 기입하지 않습니다. 오직 요청한(requiredBeneficiaryInfo에 있는) 정보만 기입합니다.

    • Beneficiary account number는 수정하지 않고 그대로 반환해야 합니다. 지갑 주소를 변경하면 오입금이 발생할 수 있습니다. 만약 입금 주소가 잘못된 경우에는 DENIED 결과를 반환해야 합니다.

  • 사용자 검증 API에서 Originator에 대한 검증 시, 필요한 개인 정보가 부족한 경우에는 다음과 같이 처리합니다.

    • verificationResult를 DENIED로 반환하고, reason에는 LACK-OF-INFORMATION로 반환합니다. 그리고, message 필드에 어떤 정보가 부족한지 개인 정보 코드 목록을 반환합니다.

Request Header

Request Body

Request Body Examples
  {
    "verificationUuid": "4bc03a8f-5679-4358-815c-906aae5557f4",
    "assetInfo": {
      "symbol": "ETH",
      "network": "Ethereum",
      "amount": "0.024",
      "isExceedingThreshold": true,
      "tradePrice": "2193200",
      "tradeCurrency": "KRW",
      "tradeISODatetime": "2022-02-06T23:13:43.513Z"
    },
    "requiredBeneficiaryInfo": "ACCOUNT_NUMBER,NATURAL_PERSON_NAME",
    "originatingVaspId": "123456789098765",
    "version": "1.0",
    "ivms101": {
      "originator": {
        "originatorPersons": [
          {
            "naturalPerson": {
              "name": {
                "nameIdentifier": [
                  {
                    "primaryIdentifier": "James",
                    "secondaryIdentifier": "Din",
                    "nameIdentifierType": "LEGL"
                  }
                ]
              }
            }
          }
        ],
        "accountNumber": [
            "0x5811001506550d8356a215be229c15b6ef371a9a"
        ]
      },
      "beneficiary": {
        "beneficiaryPersons": [{
          "naturalPerson": {
            "name": {
              "nameIdentifier"; [{
                "primaryIdentifier": "James",
                "nameIdentifierType": "LEGL"
              }]
            }
          }
        }],
        "accountNumber": ["0xb0bFf9721871e22653358956cf59a5FdBF3D752F"]
      }
    }
  }

  • assetInfo.network 필드는 필수가 아닙니다 (Optional). 여러 블록체인 네트워크에 배포된 가상 자산 (ex. USDT의 경우 이더리움, BSC, 솔라나 등 여러 네트워크에 배포)에 대해 상대 VASP가 network 필드 없이 나에게 호출하는 경우 다음과 같이 응답할 수 있습니다.

    • Network 필드가 필수인 경우: result는 'DENIED'로, reason은 'UNKNOWN-NETWORK'로 반환할 수 있습니다. 물론 상대 VASP에서 network 필드 지원을 구현하지 않았으면 거래 성공률이 낮아집니다.

    • Network 필드가 옵션인 경우: 상대 VASP가 생략한 network 필드를 내가 취급하는 network로 가정하고 검증한 결과를 반환할 수 있습니다. 다만, 상대 VASP와 네트워크가 다를 경우 가상 자산이 오전송 될 수 있습니다.

  • 위 두 가지 중 어떤 응답을 반환할지는 각 VASP에서 스스로 결정할 수 있습니다. 예를 들어 상대 VASP 별로 다르게 정책을 가져갈 수도 있습니다. 각 VASP 별 상황을 고려하여 구현하시기 바랍니다.

Response Body

Response Body Examples

  • 200 OK

{
  "result": "VERIFIED",
  "reason": "OK",
  "message": "",
  "ivms101": {
    "beneficiary": {
      "beneficiaryPersons": [
        {
          "naturalPerson": {
            "name": {
              "nameIdentifier": [
                {
                  "primaryIdentifier": "James",
                  "nameIdentifierType": "LEGL"
                }
              ],
              "localNameIdentifier": [
                {
                  "primaryIdentifier": "김재원",
                  "nameIdentifierType": "LEGL"
                }
              ]
            },
            "geographicAddress": [
              {
                "addressType": "GEOG",
                "townName": "Yeoksam-dong",
                "addressLine": ["14 Teheran-ro 4-gil, Gangnam-gu", "4th floor"],
                "country": "KR"
              }
            ],
            "nationalIdentification": {
              "nationalIdentifier": "12345-67890",
              "nationalIdentifierType": "IDCD"
            },
            "customerIdentification": "1234569999",
            "dateAndPlaceOfBirth": {
              "dateOfBirth": "1985-03-14",
              "placeOfBirth": "Nonsan"
            },
            "countryOfResidence": "KR"
          }
        }
      ],
      "accountNumber": ["0xb0bFf9721871e22653358956cf59a5FdBF3D752F"]
    }
  }
}

  • 200 OK

{
  "result": "DENIED",
  "reason": "UNVERIFIED-KYC"
}

: 사용자 검증 결과는 다음과 같은 형태로 반환해야 합니다.

  • result 필드에는 다음과 같은 값이 들어갈 수 있습니다.

    • “VERIFIED”, ”DENIED”, ”ERROR” 중 한 개의 값을 갖습니다.

    • VERIFIED: 검증이 성공적으로 끝난 경우, 사용자에게 아무런 문제가 없음을 의미합니다.

    • DENIED: 지갑 주소는 맞지만 사용자(송신인 포함)에게 문제가 발견된 경우 (e.g. lack of KYC credential)

    • ERROR: 기타 다른 에러가 발생한 경우

  • reason 필드에는 다음과 같은 값이 들어갈 수 있습니다.

    • 단, 사용자 검증 요청에 대한 결과 result 필드의 값이 DENIED 일 때에만 유효합니다.

    • message 필드에는, 아래 표에 설명된 값을 string으로 전달합니다. (하단 표 내용 참조)

Links

IVMS101 포맷 정의

IVMS101 정보 기입 가이드

사용자 개인 정보 종류 코드

  • Request Body의 requiredBeneficiaryInfo 필드의 값은 아래 링크 정보를 참조합니다.

  • Response Body의 에러 코드 reason 필드의 값이 LACK-OF-INFORMATION 인 경우, message 필드의 값은 아래 링크 정보를 참조합니다.

PreviousVASP API ReferenceNext사용자 계정 검증 API

Last updated