자산 이전 허가 요청

가상 자산의 이전에 대한 허가를 자산을 수신하는 VASP 에 요청합니다

POST /v1/code/transfer/{BeneficiaryVaspEntityId}

가상 자산을 전송하려는 VASP 는 가상 자산을 수신할 VASP 에 자산의 이전 허가를 요청합니다. 자산을 보내려는 VASP 는 요청(request)에 송금인의 개인 정보를 보내고, 자산을 수신하는 VASP 는 송금인의 정보를 확인한 후, 거래를 거절하거나 수취인의 개인 정보와 함께 허가를 통보할 수 있습니다.

요청을 보낸 VASP 는 요청을 보내기 전 또는 응답을 받은 후, 저장한 자산 이전 목록의 상태(status) 를 verified 또는 denied 로 업데이트 합니다.

Path Parameter

• BeneficiaryVaspEntityId: 자산을 수신하는 주소를 소유하는 VASP 의 EntityID 로 반드시 입력해야 합니다.

REQUEST Body Schema: application/jsonRequest

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

• transferId(Required):

  • '자산 이전 허가 요청' 부터는 이후 프로세스가 실행되는 중에 트랜잭션 상태를 추적할 수 있는 고유 아이디가 필요합니다.

  • 요청을 보내는 클라이언트는 반드시 UUID v4 값을 생성해서 보내야 합니다.

• currency(Required): 이전하려는 가상 자산의 심볼입니다.(대소문자를 구분하지 않습니다)

• amount(Required): 이전하려는 가상 자산의 총 볼륨입니다.

• historicalCost(Optional): 이전하려는 가상자산의 취득 원가입니다. (국세청 요구 사항이지만, 아직은 사용하지 않습니다.)

• tradePrice(Required): 법정 화폐로 환산한 가상 자산 전송 금액입니다. 자체 시세 정보가 없는 경우에는 타 VASP의 시세 API 를 사용하여 환산합니다.

• tradeCurrency(Required): 법정 화폐로 환산할 때 사용한 ISO 4217 표준을 따르는 법정 화폐 코드입니다.

❗tradePrice에는 해당 자산의 수량과 가격을 곱하여 법정 화폐로 계산한 값을, tradeCurrency에는 법정 화폐의 종류를 입력해야 합니다. 예를 들어 2 BTC를 이전하는 경우, 그 시점의 가격이 $42,708라고 한다면 총 가격은 42,708*2 = 85,416 달러 입니다. 이 경우 다음과 같이 입력해야 합니다.

"tradePrice": "85416", 
"tradeCurrency": "USD",

• isExceedingThreshold(Required):

  • tradePrice 가 법령에서 지정한 트래블룰 적용 기준을 초과하는지 여부입니다.

  • 해당 필드는 true 또는false로 입력하며, 필드값이 true 일 경우, 요청(request)의Beneficiary 이름을 실제 가상 자산 주소를 소유한 Beneficiary 이름과 비교하게 됩니다.

  • 필드값이 true일 경우, 요청(request)에 Beneficiary이름이 없거나 다를 경우 '거절(deny)' 응답을 보냅니다.

• originatingVasp(Optional, 대소문자 주의): VerifyVASP 로부터 들어오는 요청에 한하여 암호화 영역인 payload 외부에 originatingVASP 객체가 포함되어 있습니다.

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

• payload(Required): IVMS101 메시지를 담기 위한 객체입니다.

  • ivms101(Required): IVMS101 메시지 표준을 따르는 송금인(Originator), 수취인(Beneficiary), 송신 VASP(OriginatorVASP), 수취VASP(BeneficiaryVASP) 등 가상자산 이전에 관여하는 각 주체를 IVMS101 국제 표준에 맞춰서 정의한 객체입니다. '자산 이전 허가 요청' 에서는 Originator 의 이름과 자산 주소, Beneficiary 의 자산 주소, OriginatingVASP 정보가 반드시 포함돼야 하고, Beneficiary 이름은 선택 사항입니다.

    • Originator(Required): 자산을 이전하고자 하는 송금인(개인) 또는 법인 및 대표자에 대한 정보.

      • originatorPersons(Required): naturalPerson(개인), legalPerson(법인) 두 종류의 객체가 있으며, 법인의 경우에는 legalPerson(법인)과 naturalPerson(대표) 정보를 모두 설정해야 합니다. 배열 객체이며, 배열의 각 요소(element)는 naturalPerson 또는 legalPerson 중 하나 만을 정의해야 합니다. 자세한 내용은 본 매뉴얼 위쪽의 IVMS101 표준 항목을 참고해주세요.

        • naturalPerson(Required): 개인에 대한 정보를 설정하기 위한 객체로 name(이름) 정보를 필수로 설정해야 합니다.

          • name(Required):

            • nameIdentifier: 법적 성명을 기입합니다. 국내 VASP 끼리 거래하는 경우는 한글로 기입하고, 해외 VASP 와 거래하는 경우 영문으로 기입합니다. IVMS101 표준 항목을 참고해 주세요.

              • primaryIdentifier: 성명 중 성을 기입합니다. 분리할 수 없는 경우는 성과 이름을 순서대로 함께 표기합니다.

              • secondaryIdentifier: 성명 중 이름을 기입합니다. 성과 이름을 분리할 수 없는 경우는 생략합니다.

              • nameIdentifierType: 'LEGL(legal)' 로 고정됩니다.

            • localNameIdentifier: 해외 VASP 와 거래하는 경우 한글 이름을 추가로 전달하기 위해 정의합니다.

              • primaryIdentifier: 한글 표기 성명 중 성을 기입합니다. 분리할 수 없는 경우 성과 이름을 순서대로 함께 표기합니다.

              • secondaryIdentifier: 한글 표기 성명 중 이름을 기입합니다. 분리할 수 없는 경우는 생략합니다.

              • nameIdentifierType: 'LEGL'(legal) 로 고정됩니다.

          • customerIdentification(Optional): 자산을 전송하는 송금인을 VASP에서 식별 가능한 식별자 (UID 또는 IDX)

        • legalPerson(Optional): 법인에 대한 정보를 설정하기 위한 객체로 name 객체를 필수로 설정해야 합니다.

          • name(Required):

            • nameIdentifier: 법인의 등록 상 명칭을 기입합니다. 국내 VASP 끼리 거래하는 경우는 한글 또는 영문으로 기입하고, 해외 VASP 와 거래하는 경우 영문으로 기입합니다.

              • legalPersonName: 법인명을 기입합니다.

              • legalPersonNameIdentifierType: 'LEGL'(legal) 로 고정됩니다.

          • customerIdentification(Optional): 자산을 전송하는 송금인을 VASP에서 식별 가능한 식별자 (UID 또는 IDX)

      • accountNumber(Required): 자산을 전송하는 지갑 주소입니다. tag 나 memo 값이 필요한 경우는 ':' 로 구분해서 하나의 문자열로 만듭니다.

    • Beneficiary(Required): 자산을 수신 받는 수취인(개인) 또는 법인 및 대표자에 대한 정보를 기입합니다. 요청(request)을 보낼 때, Beneficiary 정보를 함께 기입하여 보내야 하며, ①이름과 ②지갑 주소로 구성되어 있습니다. 지갑 주소 정보는 필수입니다. 이름 정보는 tradePrice가 트래블룰 적용 기준을 초과할 경우, 필수로 설정해야하고, 초과하지 않을 경우 옵션입니다. ※ 이름 정보는 'isExceedingThreshold'가 true일 때 Required, 'isExceedingThreshold'가 false일 때 Optional입니다.

      • beneficiaryPersons(Required): Beneficiary 상위 객체에는 반드시 beneficiaryPersons라는 하위 객체가 포함되어야 합니다. beneficiaryPersons는 originatorPersons와 구조가 동일합니다. beneficiaryPersons 하위에는 naturalPerson 또는 legalPerson로 나눌 수 있습니다. 수취 VASP는 입력한 이름과 실제 수취인의 이름을 비교했을 때, 이름이 다를 경우 거절(denied) 응답을 보냅니다.

        • naturalPerson(Required or Optional): 개인에 대한 정보를 설정하기 위한 객체이며, 'isExceedingThreshold'가 true일 경우 Required, 'isExceedingThreshold'가 false일 경우 Optional입니다.

        • legalPerson(Required or Optional): 법인에 대한 정보를 설정하기 위한 객체이며, 'isExceedingThreshold'가 true일 경우 Required, 'isExceedingThreshold'가 false일 경우 Optional입니다.

      • accountNumber(Required): 자산을 수신하는 지갑 주소입니다. tag 나 memo 값이 필요한 경우는 ':' 로 구분해서 하나의 문자열로 만듭니다.

    • OriginatingVASP(Required): 자산을 전송하려는 송신 VASP 정보입니다.

      • originatingVASP(Required):

        • legalPerson(Required): 자산을 전송하려는 VASP의 법인 정보입니다.

          • name(Required):

            • nameIdentifier: 국제 표기법을 따르는 영문 이름 정보입니다.

              • legalPersonName: 영문 법인명입니다.

              • legalPersonNameIdentifierType: 'LEGL'(legal) 로 고정됩니다.

          • geographicAddress(Optional): 법인의 등록 서류상 소재지입니다. 법인 주소 또는 법인 등록 번호 중 하나는 반드시 입력해야 합니다.

            • addressType: 'GEOG' 로 입력합니다.

            • townName: 시/도 이름을 입력합니다.

            • addressLine: townName 하위 주소를 문자열의 배열 형식으로 입력합니다.

            • country: ISO-3166-1 alpha-2 에서 정하는 2글자 국가 코드입니다. 예) KR, JP, US 등

          • nationalIdentification(Optional): 국가의 인증을 받은 법인 식별 번호, 즉 사업자등록번호 입니다. 법인 주소 또는 등록 번호 중 하나는 반드시 입력해야 합니다.

            • nationalIdentifier: 사업자등록번호

            • nationalIdentifierType: 'RAID'(Registration authority identifier)

            • registrationAuthority: 'RA000657' (대한민국 국세청 RA 식별번호)

          • countryOfRegistration(Required): 등록 국가. ISO-3166-1 alpha-2 에서 정하는 2글자 국가 코드입니다. 예) KR, JP, US 등

{
  "transferId": "string",
  "currency": "string",
  "amount": "string",
  "historicalCost": "",
  "tradePrice": "1000001",
  "tradeCurrency": "KRW",
  "isExceedingThreshold": "true",
  "originatingVasp": {
  },
  "payload": {
    "ivms101": {
      "Originator": {
        "originatorPersons": [
          // 개인일 경우 배열의 첫번째 요소에 naturalPerson 하나만 입력
          {
            "naturalPerson": {
              "name": {
                "nameIdentifier": [
                  {
                    "primaryIdentifier": "Barnes",
                    "secondaryIdentifier": "Robert",
                    "nameIdentifierType": "LEGL"
                  }
                ],
                "localNameIdentifier": [
                  {
                    "primaryIdentifier": "로버트 반스",
                    "secondaryIdentifier": "",
                    "nameIdentifierType": "LEGL"
                  }
                ]
              },
              "customerIdentification": "customernumber in Max 50 Text"
            }
          },
          // 또는 법인일 경우 배열의 첫번째 요소에 legalPerson 을 입력하고,
          // 두번째 요소부터 naturalPerson(대표자) 정보를 입력
          {  // 법인 정보
            "legalPerson": {
              "name": {
                "nameIdentifier": [
                  {
                    "legalPersonName": "(주)코인원",
                    "legalPersonNameIdentifierType": "LEGL"
                  }
                ]
              },
              "customerIdentification": "customernumber in Max 50 Text"
            }
          },
          {  // 법인의 대표자
            "naturalPerson": {
              "name": {
                "nameIdentifier": [
                  {
                    "primaryIdentifier": "Barnes",
                    "secondaryIdentifier": "Robert",
                    "nameIdentifierType": "LEGL"
                  }
                ],
                "localNameIdentifier": [
                  {
                    "primaryIdentifier": "로버트 반스",
                    "secondaryIdentifier": "",
                    "nameIdentifierType": "LEGL"
                  }
                ]
              }
            }
          }
        ],
        "accountNumber": ["rJChk8e71gxVhyJSr1srzZxWhVisWMMYKZ:tag or memo"]  // 전송 고객의 지갑 주소:Tag or memo
      },
      "Beneficiary" : {
        "beneficiaryPersons": [
          {
            "naturalPerson": {
              "name": {
                "nameIdentifier": [
                  {
                    "primaryIdentifier": "Smith",
                    "secondaryIdentifier": "Alice",
                    "nameIdentifierType": "LEGL"
                  }
                ],
                "localNameIdentifier": [
                  {
                    "primaryIdentifier": "앨리스 스미스",
                    "secondaryIdentifier": "",
                    "nameIdentifierType": "LEGL"
                  }
                ]
              }
            }
          }
        ],
        "accountNumber": ["rHcFoo6a9qT5NHiVn1THQRhsEGcxtYCV4d:tag or memo"] // 수신 고객의 지갑 주소:Tag or memo
      },
      "OriginatingVASP": {
        "originatingVASP": {
          "legalPerson": {
            "name": {
              "nameIdentifier": [
                {
                  "legalPersonName": "Korbit Inc.",
                  "legalPersonNameIdentifierType": "LEGL"
                }
              ]
            },
            "geographicAddress": [
              {
                "addressType":"GEOG",
                "townName":"Seoul",
                "addressLine": ["100 Teheran-ro 1-gil, Gangnam-gu", "10th floor"],
                "country":"KR"
              }
            ],
            "nationalIdentification": {
              "nationalIdentifier": "사업자번호",
              "nationalIdentifierType": "RAID",
              "registrationAuthority": "RA000657"
            },
            "countryOfRegistration": "KR"
          }
        }
      }
    }
  }
}

Response

200 OK

RESPONSE SCHEMA: application/json

• result(Required): 가상 자산의 이전 허가 결과입니다.

  • verified: 허가된 경우 반환됩니다.

  • denied: 자산 이전을 거부한 경우 반환됩니다. reasonType 값으로 상세 내용을 구분할 수 있습니다.

• reasonType(Optional): result 필드 값이 denied 인 경우 이 필드가 추가 됩니다.

  • NOT_FOUND_ADDRESS: 가상 자산 주소를 찾을 수 없는 경우입니다.

  • NOT_SUPPORTED_SYMBOL: 거래할 수 없는 화폐 심볼입니다.

  • NOT_KYC_USER: 수신 주소의 소유자가 KYC 인증을 진행하지 않은 경우입니다.

  • INPUT_NAME_MISMATCHED: 요청 메시지로 전송한 수취인 이름이 실제 소유자의 이름과 일치하지 않는 경우입니다.

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

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

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

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

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

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

• payload(Required): IVMS101 메시지를 담기 위한 객체입니다.

  • ivms101(Required): IVMS101 메시지 표준을 따르는 송금인(Originator), 수취인(Beneficiary), 송신 VASP(OriginatorVASP), 수취 VASP(BeneficiaryVASP) 등 가상자산 이전에 관여하는 각 주체를 IVMS101 국제 표준에 맞춰 정의한 객체입니다. 응답(response) 객체에서는 Originator, OriginatingVASP 정보는 요청(request)의 데이터를 복사하고, Beneficiary, BeneficiaryVASP 데이터가 추가됩니다.

    • Originator(Required): 자산을 전송하고자 하는 송금인(개인) 또는 법인 및 대표자에 대한 정보입니다. 요청의 값을 그대로 복사해서 사용합니다.

    • Beneficiary(Required): 자산을 수신하는 수취인(개인) 또는 법인 및 대표자에 대한 정보입니다. 응답(response)에서는 이름과 자산 주소를 기입해서 보내야 합니다.

      • beneficiaryPersons(Required): 상위 객체인 Beneficiary 객체에 반드시 포함되어야 하며 구조는 originatorPersons 와 같으므로 요청의 originatorPersons 설명을 참고해 주세요.

        • naturalPerson(Required): 개인에 대한 정보를 설정하기 위한 객체로 name(이름) 정보를 필수로 설정해야 합니다.

        • legalPerson(Optional): 법인에 대한 정보를 설정하기 위한 객체로 name(이름) 정보를 필수로 설정해야 합니다.

      • accountNumber(Required): 자산을 수신하는 지갑 주소입니다. tag 나 memo 값이 필요한 경우는 ':' 로 구분해서 하나의 문자열로 만듭니다.

    • OriginatingVASP(Required): 자산을 전송하려는 송신 VASP 정보로 요청의 값을 그대로 복사해서 사용합니다.

    • BeneficiaryVASP(Required): 자산을 수신하는 수취 VASP 정보입니다. 구조는 OriginatingVASP 와 같으므로 요청의 OriginatingVASP 설명을 참고해 주세요.

{
  "result": "string",
  "reasonType": "",
  "reasonMsg": "",
  "transferId": "string",
  "beneficiaryVasp": {
  },
  "payload": {
    "ivms101": {
      "Originator": {
        "originatorPersons": [
          // 개인일 경우 배열의 첫번째 요소에 naturalPerson 하나만 입력
          {
            "naturalPerson": {
              "name": {
                "nameIdentifier": [
                  {
                    "primaryIdentifier": "로버트 반스",
                    "secondaryIdentifier": "",
                    "nameIdentifierType": "LEGL"
                  }
                ]
              },
              "customerIdentification": "customernumber in Max 50 Text"
            }
          },
          // 법인일 경우 배열의 첫번째 요소에 legalPerson 을 입력하고,
          // 두번째 요소부터 naturalPerson(대표자) 정보를 입력
          {  // 법인 정보
            "legalPerson": {
              "name": {
                "nameIdentifier": [
                  {
                    "legalPersonName": "(주)코인원",
                    "legalPersonNameIdentifierType": "LEGL"
                  }
                ]
              },
              "customerIdentification": "customernumber in Max 50 Text"
            }
          },
          {  // 법인의 대표자
            "naturalPerson": {
              "name": {
                "nameIdentifier": [
                  {
                    "primaryIdentifier": "로버트 반스",
                    "secondaryIdentifier": "",
                    "nameIdentifierType": "LEGL"
                  }
                ]
              }
            }
          }
        ],
        "accountNumber": ["rJChk8e71gxVhyJSr1srzZxWhVisWMMYKZ:tag or memo"]  // 송금 고객의 지갑 주소:Tag or memo
      },
      "Beneficiary": {
        "beneficiaryPersons": [
          // 개인일 경우 배열의 첫번째 요소에 naturalPerson 하나만 입력
          {
            "naturalPerson": {
              "name": {
                "nameIdentifier": [
                  {
                    "primaryIdentifier": "로버트 반스",
                    "secondaryIdentifier": "",
                    "nameIdentifierType": "LEGL"
                  }
                ]
              },
              "customerIdentification": "customernumber in Max 50 Text"
            }
          },
          // 법인일 경우 배열의 첫번째 요소에 legalPerson 을 입력하고,
          // 두번째 요소부터 naturalPerson(대표자) 정보를 입력
          {  // 법인 정보
            "legalPerson": {
              "name": {
                "nameIdentifier": [
                  {
                    "legalPersonName": "(주)코인원",
                    "legalPersonNameIdentifierType": "LEGL"
                  }
                ]
              },
              "customerIdentification": "customernumber in Max 50 Text"
            }
          },
          {  // 법인의 대표자
            "naturalPerson": {
              "name": {
                "nameIdentifier": [
                  {
                    "primaryIdentifier": "로버트 반스",
                    "secondaryIdentifier": "",
                    "nameIdentifierType": "LEGL"
                  }
                ]
              }
            }
          }
        ],
        "accountNumber": [ "rHcFoo6a9qT5NHiVn1THQRhsEGcxtYCV4d:tag or memo" ] // 수신 고객의 지갑 주소:Tag or memo
      },
      "OriginatingVASP": {
        "originatingVASP": {
          "legalPerson": {
            "name": {
              "nameIdentifier": [
                {
                  "legalPersonName": "Korbit Inc.",
                  "legalPersonNameIdentifierType": "LEGL"
                }
              ]
            },
            "geographicAddress": [
              {
                "addressType":"GEOG",
                "townName":"Seoul",
                "addressLine": ["100 Teheran-ro 1-gil, Gangnam-gu", "10th floor"],
                "country":"KR"
              }
            ],
            "nationalIdentification": {
              "nationalIdentifier": "사업자번호",
              "nationalIdentifierType": "RAID",
              "registrationAuthority": "RA000657"
            },
            "countryOfRegistration": "KR"
          }
        }
      },
      "BeneficiaryVASP": {
        "beneficiaryVASP": {
          "legalPerson": {
            "name": {
              "nameIdentifier": [
                {
                  "legalPersonName": "Coinone Inc.",
                  "legalPersonNameIdentifierType": "LEGL"
                }
              ]
            },
            "geographicAddress": [
              {
                "addressType":"GEOG",
                "townName":"Seoul",
                "addressLine": ["100 Teheran-ro 1-gil, Gangnam-gu", "10th floor"],
                "country":"KR"
              }
            ],
            "nationalIdentification": {
              "nationalIdentifier": "6948624434",
              "nationalIdentifierType": "RAID",
              "registrationAuthority": "RA000657"
            },
            "countryOfRegistration": "KR"
          }
        }
      }
    }
  }
}