📘
POST
/v1/beneficiary/transfer

가상자산을 전송하려는 VASP 는 자산을 보내기 전에 수취 VASP 에 '자산 이전 허가' 를 요청합니다. 이 '자산 이전 허가 요청' 을 처리하기 위한 API 를 구현해야 합니다.

👍
이름 승인 로직
이름 검증 로직은 기본값을 False로 두고, 유효한 조건을 만족할 경우에만 True를 반환하는 방향을 권장합니다. 디폴트값을 True로 설정하고 특정 조건에서만 거절하는 방식은 예외 상황 발생 시 의도치 않게 모든 입력을 허용하게 될 가능성이 있어 방어적으로 설계하기 어렵기 때문입니다.

API 동작 명세

암호화된 payload를 자신의 Private Key로 복호화합니다.
이전할 자산 정보와 Originator 정보, OriginatingVASP 정보를 확인하고 이 자산 이전을 허용할지 판단할 수 있습니다. VerifyVASP에서 온 요청은 originatingVASP 객체가 payload 밖에 있습니다. payload -> ivms101 안으로 덮어써 주세요.
Beneficiary에 담겨있는 수취인의 주소 정보가 실제로 수취 가능한 주소인지 확인합니다.
1. 주소 검증 방법은지갑 주소 검증하기 페이지를 참고 해주세요.
Beneficiary에 수취인의 이름이 있을 경우에는 해당 주소의 소유자와 일치하는지도 확인합니다. 이름 정보는 primaryIdentifier만 정의돼 있다면 성과 이름을 모두 포함하는 경우입니다.
1. 이름 검증 방법은IVMS101 페이지의 이름 섹션을 참고 해주세요.
필요하다면 수취 주소에 대해서 Sanction screening 도 수행합니다.
이 내용을 토대로 자산 이전 정보를 DB에 저장하고, status 값을 부여합니다. verified 또는 denied로 지정할 수 있습니다.
요청 메시지의 내용을 확인한 결과를 토대로 응답(response) 메시지를 생성합니다. 이때, Originator, OriginatingVASP, Beneficiary 객체는 요청의 값을 그대로 복사하여 사용하고, BeneficiaryVASP 객체는 수취 VASP의 정보를 기준으로 작성합니다.

Request

📘
Originator 의 개인정보는 2022.3.25 현재 개인인 경우 개인의 이름, 법인인 경우 법인과 대표자의 이름에 대한 정보만 보내기로 합니다.

이름	필수 여부	타입
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 를 사용하여 환산합니다.

tradeCurrency: 법정 화폐로 환산할 때 사용한 ISO 4217 표준을 따르는 법정 화폐 코드입니다. "KRW", "USD", "EUR", "JPY", "CNY", "GBP", "CAD", "AUD", "HKD", "SGD"가 입력 가능하며 그 외의 화폐코드를 사용하게 되면 CodeVASP 팀에게 알려주세요! 자세한 내용은 개발 FAQ페이지를 참고 부탁드립니다.

isExceedingThreshold: tradePrice가 법령에서 지정한 트래블룰 적용 기준을 초과하는지 여부로, true 또는false로 입력하며, 필드값이 true 일 경우, 요청(request)의 Beneficiary 이름을 실제 가상자산 주소를 소유한 Beneficiary 이름과 비교하게 됩니다. 필드값이 true일 경우, 요청(request)에 Beneficiary이름이 없거나 다를 경우 '거절(deny)' 응답을 보냅니다.

originatingVasp: VerifyVASP 로부터 들어오는 요청에 한하여 암호화 영역인 payload 외부에 originatingVASP 객체가 포함되어 있습니다.

-countryOfRegistration: VerifyVASP 요청은 해당 필드값이 포함되지 않습니다.

payload: IVMS101 메시지를 담기 위한 객체입니다. IVMS101 페이지의 타입 섹션을 참고해 주세요.

address: 수신인의 지갑주소를 입력합니다. 타 솔루션사와 연동되어 있는 VASP는 필수로 요청할 수 있으니, 타 프로토콜과의 상호운용 페이지를 참고해주세요.

tag: Tag 혹은 Memo가 존재하는 경우 작성합니다. (예. XRP) 타 솔루션사와 연동되어 있는 VASP는 필수로 요청할 수 있으니, 타 프로토콜과의 상호운용 페이지를 참고해주세요.

network: 하나의 코인이 여러 네트워크 위에 존재 할 때 구분을 위해 작성합니다. 타 솔루션사와 연동되어 있는 VASP는 필수로 요청할 수 있으니, 타 프로토콜과의 상호운용 페이지를 참고해주세요.

{
    "transferId": "string",
    "currency": "string",
    "amount": "string",
    "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: 요청 메시지로 전송한 수취인 이름이 실제 소유자의 이름과 일치하지 않는 경우입니다.

-DOB_MISMATCHED: 요청 메시지로 전송한 생년월일이 실제 소유자의 생년월일과 일치하지 않는 경우입니다. (생년월일이 존재하는 경우에만)

-SANCTION_LIST: 가상자산 주소 또는 소유자가 수취 VASP 의 제재 대상입니다.

-LACK_OF_INFORMATION: 자산 이전을 결정하는데 필요한 정보가 없을 경우입니다.

-UNKNOWN: 그 밖에 다른 이유입니다.

reasonMsg: reasonType 을 설명하는 상세 메시지를 정의합니다.

transferId: '자산 이전 허가 요청' 부터는 이후 프로세스가 실행되는 중에 트랜잭션 상태를 추적할 고유 아이디가 필요합니다. 요청을 보내는 클라이언트에서 UUID 를 생성해서 보냅니다.

beneficiaryVasp: VerifyVASP 로부터 들어오는 응답에 한하여 암호화 영역인 payload 외부에 beneficiaryVASP 객체가 포함되어 있습니다. (대소문자 주의)

payload(Required): IVMS101 메시지가 담긴 객체입니다. 상세 내용은 IVMS101타입 페이지를 참고해주세요.

{
    "result": "string",
    "reasonType": "",
    "reasonMsg": "",
    "transferId": "string",
    "beneficiaryVasp": {},
    "payload": "encrypted ivms101 payload"
}