사용자 계정 검증 요청 API

사용자 계정 검증

POST http://<enclave-endpoint>/v1/verifications/account

Originator가 입력한 Beneficiary의 Address (지갑 주소 또는 계좌번호)와 수취인 이름이, Beneficiary VASP 소유인지 확인 요청하는 API입니다.

Originating VASP에서 출금 시, Originating VASP에서 수취 지갑 주소와 수취인 이름(optional)을 전달합니다.

Beneficiary VASP에서 만약에 수취인 이름 값이 있을 경우, 법령에서 정해진 금액 이상의 출금으로 보고, 지갑 주소 + 성명 조합으로 검증하여 응답합니다.

수취인 이름 값이 없을 경우에는 기준 금액 미만인 것으로 보고 지갑 주소만 검증하여 응답합니다.

Request Body

Request Body Examples

• 지갑 주소만 확인

{
  "keyType": "PerVasp",
  "beneficiaryVaspId": "27372039731940770",
  "symbol": "ETH",
  "network": "Ethereum",
  "payload": {
    "version": "1.0",
    "ivms101": {
      "beneficiary": {
        "accountNumber": ["0x5811001506550d8356a215be229c15b6ef371a9b"]
      }
    }
  }
}

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

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

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

{
  "keyType": "PerVasp",
  "beneficiaryVaspId": "27372039731940770",
  "symbol": "ETH",
  "network": "Ethereum",
  "payload": {
    "version": "1.0",
    "ivms101": {
      "beneficiary": {
        "accountNumber": ["0x5811001506550d8356a215be229c15b6ef371a9b"]
      }
    }
  }
}

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

{
  "keyType": "PerVasp",
  "beneficiaryVaspId": "27372039731940770",
  "symbol": "ETH",
  "network": "Ethereum",
  "payload": {
    "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	Description
keyType	string	true	개인 정보 암호화에 사용할 Beneficiary VASP의 Public Key 타입을 지정합니다.
beneficiaryVaspId	string	true	Beneficiary VASP ID
symbol	string	true	가상 자산
network	string	false	가상 자산이 배포되어 있는 블록체인 네트워크 이름 (자세한 사항은 '추가 정보' 메뉴 하단의 'network 필드 가이드'를 참조)
payload	object	true	Beneficiary에 대한 정보(지갑 주소와 수취인의 이름 정보)를 IVMS101 형태로 전달합니다.
payload.version	string	true	IVMS101 메시지 포맷에 대한 버전.
payload.ivms101	object	true	Beneficiary에 대한 정보를 IVMS101 형태로 전달합니다. IVMS101 메시지 프로토콜 참조. IVMS101 메시지 가이드 문서 참조.

Response Body

성공 케이스

Response Body Examples

• 200 OK

{
  "accountVerificationResult": "VERIFIED",
  "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-03T18:19:20.092Z"	사용자 계정 검증 확인 시간

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

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

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

    • DENIED: 지갑 주소와 수취인 이름을 모르는 경우 (VASP가 소유하지 않은 경우)를 가리킵니다.

• 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	그 밖에, 따로 정의되어 있지 않은 에러가 발생한 경우
  BLACKLISTED	DENIED	수신자가 블랙리스트인 경우
  UNVERIFIED-KYC	DENIED	수신자가 KYC 검증되지 않은 경우

에러 케이스

필수 파라미터를 입력하지 않은 경우

Response Body Examples

• 400 Bad Request

{
  "code": "MISSING-VASP",
  "message": "`beneficiaryVaspId` is required."
}

잘못된 파라미터를 입력한 경우

Response Body Examples

• 400 Bad Request

{
  "code": "INVALID-KEY-TYPE",
  "message": "`keyType` is invalid value."
}

beneficiaryVaspId에 VerifyVASP에 회원 가입하지 않은 VASP의 ID를 입력한 경우

Response Body Examples

• 400 Bad Request

{
  "code": "ALLIANCE-NOT-FOUND",
  "message": "Alliance is not found in given vendor"
}

beneficiaryVaspId에 VerifyVASP에 회원 가입은 했지만 active 상태가 아닌 VASP의 ID를 입력한 경우

Response Body Examples

• 400 Bad Request

{
  "code": "ALLIANCE-NOT-ACTIVE",
  "message": "Alliance is not active now"
}

잘못된, 혹은 수취 VASP에서 취급하지 않는 자산의 Symbol을 입력한 경우

Response Body Examples

• 200 OK

{
  "accountVerificationResult": "DENIED",
  "reason": "UNKNOWN-SYMBOL",
  "verifiedAt": "2022-03-03T12:46:34.085Z"
}

여러 네트워크에 배포된 자산에 대해 network 필드가 누락되었거나 수신 VASP에서 취급하는 네트워크가 아닌 경우

Response Body Examples

• 200 OK

{
  "accountVerificationResult": "DENIED",
  "reason": "UNKNOWN-NETWORK",
  "message": "'network' is necessary",
  "verifiedAt": "2022-03-03T12:46:34.085Z"
}

잘못된 지갑 주소를 입력한 경우

Response Body Examples

• 200 OK

{
  "accountVerificationResult": "DENIED",
  "reason": "UNKNOWN-ADDRESS",
  "verifiedAt": "2022-03-03T12:47:05.817Z"
}

이름이 일치하지 않는 경우

Response Body Examples

• 200 OK

{
  "accountVerificationResult": "DENIED",
  "reason": "MISMATCHED-NAME",
  "verifiedAt": "2022-03-03T12:47:37.456Z"
}