사용자 계정 검증 API

사용자 계정 검증

POST VEGA_VERIFICATION_ACCOUNT_API_PATH

Enclave 환경 변수:

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

각 VASP는 송신 VASP, 수취 VASP 두 역할을 모두 수행해야 합니다.

VASP가 수취 VASP 역할을 할 때, 호출되는 API입니다.

송신자가 송신 VASP에서 출금 시 입력한 수취인의 Address(지갑 주소, 계좌번호) 와 수취인 이름 정보(optional)를 전달받아, 수취 VASP의 소유가 맞는지 확인 요청 시 호출되는 API입니다.

수취인의 이름 정보가 있을 경우, 지갑 주소뿐만 아니라 이름의 매칭 여부도 검증하여 응답합니다.

수취인의 이름 정보가 없을 경우, 지갑 주소만 검증하여 응답하면 됩니다.

응답 시간:

이 사용자 Address 검증 API는 1초 이내에 응답해야 합니다.

구현 정책:

• Beneficiary의 정보는 IVMS101 메시징 포맷에 따라 기입합니다.

• 이 API는 지갑 주소 존재 유무와 지갑 소유주의 이름에 대한 매칭 여부만 확인합니다. KYC 체크나 Sanction Screening 등과 같은 검증은 이 API에서 확인하지 않습니다.

• 이 API는 단일 계좌에 대한 계정 정보를 확인하는 데 사용됩니다. 여러 지갑 주소에 대한 사용자 계정 정보 검증 시에는, 이 API를 N 번 호출하여 사용하도록 합니다.

• 만약 법인 대표자가 여러 명인데, 전달된 법인 대표자 이름이 한 명일 경우 일치하는 대표자가 있으면 VERIFIED를 반환해야 합니다.

Request Header

Field Name	Description
Authorization	Bearer <VEGA_VERIFICATION_AUTHORIZATION_TOKEN>

Request Body

Request Body Examples

• 지갑 주소만 확인

{
  "originatingVaspId": "15952089931162060684",
  "symbol": "ETH",
  "network": "Ethereum",
  "version": "1.0",
  "ivms101": {
    "beneficiary": {
      "accountNumber": ["0x5811001506550d8356a215be229c15b6ef371a9b"]
    }
  }
}

• 지갑 주소와 수취인 이름 확인 (법정 기준 금액 이상 출금하는 경우)

{
  "originatingVaspId": "15952089931162060684",
  "symbol": "ETH",
  "network": "Ethereum",
  "version": "1.0",
  "ivms101": {
    "beneficiary": {
      "beneficiaryPersons": [
        {
          "naturalPerson": {
            "name": {
              "nameIdentifier": [
                {
                  "primaryIdentifier": "Taylor",
                  "secondaryIdentifier": "Robbins",
                  "nameIdentifierType": "LEGL"
                }
              ]
            }
          }
        }
      ],
      "accountNumber": ["0x5811001506550d8356a215be229c15b6ef371a9b"]
    }
  }
}

• 법인고객 지갑 주소만 확인

{
  "originatingVaspId": "15952089931162060684",
  "symbol": "ETH",
  "network": "Ethereum",
  "version": "1.0",
  "ivms101": {
    "beneficiary": {
      "accountNumber": ["0x5811001506550d8356a215be229c15b6ef371a9b"]
    }
  }
}

• 법인고객 지갑 주소와 법인명 및 법인 대표자명 이름 확인 (법정 기준 금액 이상 출금하는 경우)

{
  "originatingVaspId": "15952089931162060684",
  "symbol": "ETH",
  "network": "Ethereum",
  "version": "1.0",
  "ivms101": {
    "beneficiary": {
      "beneficiaryPersons": [
        {
          "legalPerson": {
            "name": {
              "nameIdentifier": [
                {
                  "legalPersonName": "A Company",
                  "legalPersonNameIdentifierType": "LEGL"
                }
              ]
            }
          }
        },
        {
          "naturalPerson": {
            "name": {
              "nameIdentifier": [
                {
                  "primaryIdentifier": "Taylor",
                  "secondaryIdentifier": "Robbins",
                  "nameIdentifierType": "LEGL"
                }
              ]
            }
          }
        }
      ],
      "accountNumber": ["0x5811001506550d8356a215be229c15b6ef371a9b"]
    }
  }
}

Field Name	Data Type	Required	Example	Description
originatingVaspId	string	true	"15952089931162060684"	지갑 주소와 수취인의 이름 정보에 대하여 검증 요청한 VASP의 ID
symbol	string	true	"ETH"	VA. Virtual Asset. 가상 자산
network	string	false	"Ethereum"	가상 자산이 배포되어 있는 블록체인 네트워크 이름 (자세한 사항은 '추가 정보' 메뉴 하단의 'network 필드 가이드'를 참조)
version	string	true	"1.0"	IVMS101 포맷의 버전 정보 (현재는 1.0)
ivms101	object	true	-	수취인의 지갑 주소와 수취인의 이름 정보가 IVMS101 메시징 프로토콜 형태로 전달된다.
ivms101.beneficiary	object	true	-	수취인에 대한 정보
ivms101.beneficiary.beneficiaryPersons	array	false	[{"naturalPerson":{"name":{"nameIdentifier":[{"primaryIdentifier":"Taylor","secondaryIdentifier":"Robbins","nameIdentifierType":"LEGL"}]}}}]	수취인 이름에 대한 정보, 법정 기준 금액 이상일 때에만 이 수취인 이름 정보가 전달된다. 이때, 지갑 주소 + 수취인 이름 함께 VASP의 소유 여부를 확인한다.
ivms101.beneficiary.accountNumber	array	true	[”0x5811001506550d8356a215be229c15b6ef371a9a”]	수취인 지갑 주소. 데이터 타입이 Array 이긴 하지만, 단 하나의 지갑 주소만으로 제한한다. 여러 개의 지갑 주소에 대해 VASP 소유 여부를 확인하고 싶다면, 이 API를 N 번 실행하도록 합니다.

• 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

{
  "accountVerificationResult": "VERIFIED",
  "verifiedAt": "2022-03-03T21:52:08.092Z"
}

• 200 OK

{
  "accountVerificationResult": "DENIED",
  "reason": "UNKNOWN-SYMBOL",
  "verifiedAt": "2022-03-03T21:52:08.092Z"
}

Field Name	Data Type	Required	Example	Description
accountVerificationResult	string	true	"DENIED"	지갑 주소와 수취인 이름에 대한 사용자 계정 검증 결과
reason	string	false	"UNKNOWN-ADDRESS"	accountVerificationResult(사용자 계정 검증 결과) 값이 DENIED인 경우에 대한 상세 에러 코드
verifiedAt	string	true	"2022-03-03T21:52:08.092Z"	사용자 계정 검증 수행 시간

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

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

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

    • DENIED: 지갑 주소가 VASP 소유가 아닐 경우, 또는 지갑 주소 + 수취인 이름 정보가 VASP 소유 정보가 아닌 경우, 수취인 정보에 대해 IVMS101 메시지를 잘 못 기입한 경우, 등등 가리킵니다.

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

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

  reason (string)	result (string)	Description
  UNKNOWN-SYMBOL	DENIED	거래소에서 취급하지 않는 심벌일 경우 (VASP가 취급하지 않는 자산일 경우)
  UNKNOWN-NETWORK	DENIED	거래소에서 취급하지 않는 네트워크이거나 네트워크 정보가 불충분한 경우 (심벌은 동일하지만 네트워크가 맞지 않는 경우)
  UNKNOWN-ADDRESS	DENIED	가상 자산 주소가 해당 VASP의 주소가 아닌 경우
  MISMATCHED-NAME	DENIED	수신자의 이름이 송신 VASP에서 보내준 이름과 일치하지 않는 경우
  UNDEFINED-ERROR	DENIED	그 밖에, 따로 정의되어 있지 않은 에러가 발생한 경우

Links

IVMS101 정보 기입 가이드

IVMS101 정보 기입 가이드