수신하는 VASP에게 가상자산의 이전에 대한 허가를 요청합니다
가상자산을 전송하려는 VASP는 가상자산을 수신할 VASP에 자산의 이전 허가를 요청합니다. 자산을 보내려는 VASP는 요청(request)에 송금인의 개인 정보를 보내고, 자산을 수신하는 VASP는 송금인의 정보를 확인한 후, 거래를 거절하거나 수취인의 개인 정보와 함께 허가를 통보할 수 있습니다.
요청을 보낸 VASP는 요청을 보내기 전 또는 응답을 받은 후, 저장한 자산 이전 목록의 상태(status)를 verified 또는 denied로 업데이트 합니다.
❗️IVMS101 표준은 객체가 복잡하기에 CODE-Cipher를 이용하길 권고 드립니다. 내부 보안상의 사유로 부득이하게 사용하지 못할 경우 가이드의 IVMS101 표준 항목을 자세히 읽어 주세요.
❗️동기 방식으로 작동하는 API로 요청 후 즉시 응답을 받을 수 있습니다.
Path Parameter
| 이름 | 필수 여부 | 타입 | 설명 |
|---|---|---|---|
| BeneficiaryVaspEntityId | 필수 | string | 수신 지갑을 소유하는 VASP의 entityId |
Request
송금인(Originator)의 개인정보는 2024.8.7 이후 개인인 경우 개인의 이름과 생년월일, 법인인 경우 법인과 대표자의 이름에 대한 정보만 보내기로 합니다.
| 이름 | 필수 여부 | 타입 |
|---|---|---|
| transferId | 필수 | string |
| currency | 필수 | string |
| amount | 필수 | string |
| historicalCost | 옵션 | string |
| tradePrice | 필수 | string |
| tradeCurrency | 필수 | string |
| isExceedingThreshold | 필수 | string |
| originatingVasp | 옵션 | string |
| payload | 필수 | string |
| address | 옵션 | string |
| tag | 옵션 | string |
| network | 옵션 | string |
transferId: '자산 이전 허가 요청' 부터는 이후 프로세스가 실행되는 중에 트랜잭션 상태를 추적할 수 있는 고유 아이디가 필요합니다. 요청을 보내는 클라이언트는 반드시 UUID v4 값을 생성해서 보내야 합니다.
currency: 이전하려는 가상자산의 심볼로 대소문자를 구분하지 않습니다.
amount: 이전하려는 가상자산의 총 볼륨입니다.
historicalCost: 이전하려는 가상자산의 취득 원가입니다. (국세청 요구 사항이지만, 아직은 사용하지 않습니다.)
tradePrice: 법정 화폐로 환산한 가상자산 전송 금액입니다. 자체 시세 정보가 없는 경우에는 타 VASP의 시세 API 를 사용하여 환산합니다. 아래의 'tradePrice' 계산법을 참고해 주세요
tradeCurrency: 법정 화폐로 환산할 때 사용한 ISO 4217 표준을 따르는 법정 화폐 코드입니다. "KRW", "USD", "EUR", "JPY", "CNY", "GBP", "CAD", "AUD", "HKD", "SGD"가 입력 가능하며 그 외의 화폐코드를 사용하게 되면 CODE 팀에게 알려주세요! 자세한 내용은 개발 FAQ페이지를 참고 부탁드립니다.
isExceedingThreshold: tradePrice가 법령에서 지정한 트래블룰 적용 기준을 초과하는지 여부로, true 또는false로 입력하며, 필드값이 true 일 경우, 요청(request)의 Beneficiary 이름을 실제 가상자산 주소를 소유한 Beneficiary 이름과 비교하게 됩니다. 필드값이 true일 경우, 요청(request)에 Beneficiary이름이 없거나 다를 경우 '거절(deny)' 응답을 보냅니다.
originatingVasp: VerifyVASP 로부터 들어오는 요청에 한하여 암호화 영역인 payload 외부에 originatingVASP 객체가 포함되어 있습니다.
-countryOfRegistration: VerifyVASP 요청은 해당 필드값이 포함되지 않습니다.
payload: IVMS101 메시지를 담기 위한 객체입니다. IVMS101 Request 페이지를 참고해서 작성해주세요.
address: 수신인의 지갑주소를 입력합니다. 타 솔루션사와 연동되어 있는 VASP는 필수로 요청할 수 있으니, 타 프로토콜과의 상호운용 페이지를 참고해주세요.
tag: Tag 혹은 Memo가 존재하는 경우 작성합니다. (예. XRP) 타 솔루션사와 연동되어 있는 VASP는 필수로 요청할 수 있으니, 타 프로토콜과의 상호운용 페이지를 참고해주세요.
network: 하나의 코인이 여러 네트워크 위에 존재 할 때 구분을 위해 작성합니다. 타 솔루션사와 연동되어 있는 VASP는 필수로 요청할 수 있으니, 타 프로토콜과의 상호운용 페이지를 참고해주세요.
'tradePrice' 계산법
'tradePrice'에는 해당 자산의 수량과 가격을 곱하여 법정 화폐로 계산한 값을, tradeCurrency에는 법정 화폐의 종류를 입력해야 합니다. 예를 들어 2 BTC를 이전하는 경우, 그 시점의 가격이 $42,708라고 한다면 총 가격은 42,708*2 = 85,416 달러 입니다. 이 경우 다음과 같이 입력해야 합니다.
"tradePrice": "85416",
"tradeCurrency": "USD",
{
"transferId": "681f27dd-43e4-4ea3-9bcc-607426d6349f",
"currency": "btc",
"amount": "2",
"historicalCost": "",
"tradePrice": "1000001",
"tradeCurrency": "KRW",
"isExceedingThreshold": "true",
"originatingVasp": {},
"payload": "encrypted ivms101 payload"
}
Response
| 이름 | 필수 여부 | 타입 |
|---|---|---|
| result | 필수 | string |
| reasonType | 옵션 | string |
| reasonMsg | 옵션 | string |
| transferId | 필수 | string |
| beneficiaryVasp | 옵션 | string |
| payload | 필수 | string |
result: 가상자산의 이전 허가 결과입니다.
-verified: 허가된 경우 반환됩니다.
-denied: 자산 이전을 거부한 경우 반환됩니다. reasonType 값으로 상세 내용을 구분할 수 있습니다.
reasonType: result 필드 값이 denied 인 경우 이 필드가 추가 됩니다.
-NOT_FOUND_ADDRESS: 가상자산 주소를 찾을 수 없는 경우입니다.
-NOT_SUPPORTED_SYMBOL: 거래할 수 없는 화폐 심볼입니다.
-NOT_KYC_USER: 수신 주소의 소유자가 KYC 인증을 진행하지 않은 경우입니다.
-INPUT_NAME_MISMATCHED: 요청 메시지로 전송한 수취인 이름이 실제 소유자의 이름과 일치하지 않는 경우입니다.
-SANCTION_LIST: 가상자산 주소 또는 소유자가 수취 VASP 의 제재 대상입니다.
-LACK_OF_INFORMATION: 자산 이전을 결정하는데 필요한 정보가 없을 경우입니다.
-UNKNOWN: 그 밖에 다른 이유입니다.
reasonMsg: reasonType 을 설명하는 상세 메시지를 정의합니다.
transferId: '자산 이전 허가 요청' 부터는 이후 프로세스가 실행되는 중에 트랜잭션 상태를 추적할 고유 아이디가 필요합니다. 요청을 보내는 클라이언트에서 UUID 를 생성해서 보냅니다.
beneficiaryVasp: VerifyVASP 로부터 들어오는 응답에 한하여 암호화 영역인 payload 외부에 beneficiaryVASP 객체가 포함되어 있습니다. (대소문자 주의)
payload(Required): IVMS101 메시지가 담긴 객체입니다. 상세 내용은 IVMS101 Response 페이지를 참고해주세요.