This page will explain IVMS101's required fields when calling 'Asset Transfer Authorization' API. It's much simple with 'Virtual Asset Address Search', so please refer to the API page.
Understanding IVMS101
IVMS101 features a complex structure, as illustrated above. The provided diagram is merely one example; scenarios vary depending on the classification as 'naturalPerson'/'legalPerson' and the use of 'localNameIdentifier'.
As required fields differ across sending and receiving cases, understanding each scenario thoroughly and entering the necessary details is required.
Although the structure appears complex, effectively handling the four essential elements—'Originator', 'Beneficiary', 'OriginatingVASP', and 'BeneficiaryVASP'—ensures a smooth process. The originating VASP shall incorporate 'Originator', 'Beneficiary', and 'OriginatingVASP' information into the 'payload' as per the IVMS101 standard and dispatch the request. The beneficiary VASP then finalizes the process by adding 'BeneficiaryVASP' details to the received data and issuing a response.
We will now review the key IVMS101 objects for common cases. For guidance on how to complete them, please refer to the IVMS101 Type page.
When Originating(Withdraw)
'Originator': 'naturalPerson'
When the originator is an individual, under the 'name' object, ❗'nameIdentifier' is required❗, whereas 'localNameIdentifier' is optional. Since the 'nameIdentifier' is required, enter blank if there is no matching value.
Typically, the 'nameIdentifier' contains the English name, while the 'localNameIdentifier' holds the Korean name (or other local language names).
However, when communicating between Korean VASPs, it is agreed that the 'nameIdentifier' will contain the Korean name and the 'localNameIdentifier' will contain the English name. Detailed guidelines can be found in the Name(nameIdentifier) notation section.
{
"Originator": {
"originatorPersons": [
{
"naturalPerson": {
"name": {
"nameIdentifier": [
{
"primaryIdentifier": "",
"secondaryIdentifier": "",
"nameIdentifierType": ""
}
],
"localNameIdentifier": [
{
"primaryIdentifier": "로버트 반스",
"secondaryIdentifier": "",
"nameIdentifierType": "LEGL"
}
]
},
"dateAndPlaceOfBirth": {
"dateOfBirth": "1990-01-01",
"placeOfBirth": "LA"
},
"customerIdentification": "customernumber in Max 50 Text",
"countryOfResidence": "US"
}
}
],
"accountNumber": [
"rJChk8e71gxVhyJSr1srzZxWhVisWMMYKZ:tag or memo"
]
},
"Beneficiary": {
},
"OriginatingVASP": {
}
}
'Originator: 'legalPerson'
When the originator is a corporate entity, under the 'originatorPersons' object, ❗both a 'legalPerson' and at least one 'naturalPerson' are required❗. The 'legalPerson' section contains corporate details, while 'naturalPerson' includes the corporate representative(CEO)'s information.
The same applies in this case, under the 'name' object, ❗'nameIdentifier' is required❗, whereas 'localNameIdentifier' is optional. Since the 'nameIdentifier' is required, enter blank if there is no matching value.
If there are multiple corporate representatives, add as many 'naturalPerson' objects as needed to the 'beneficiaryPersons' array.
The 'nameIdentifier' contains the English name, while the 'localNameIdentifier' holds the Korean name (or other local language names).
However, when communicating between Korean VASPs, it is agreed that the 'nameIdentifier' will contain the Korean name and the 'localNameIdentifier' will contain the English name. Detailed guidelines can be found in the Name(nameIdentifier) notation section.
{
"Originator": {
"originatorPersons": [
{
"legalPerson": {
"name": {
"nameIdentifier": [
{
"legalPersonName": "Coinone Inc.",
"legalPersonNameIdentifierType": "LEGL"
}
]
},
"nationalIdentification": {
"nationalIdentifier": "XXXXXXXXXXXXXXXXXXXX",
"nationalIdentifierType": "LEIX"
},
"customerIdentification": "customernumber in Max 50 Text",
"countryOfRegistration": "KR"
}
},
{
"naturalPerson": {
"name": {
"nameIdentifier": [
{
"primaryIdentifier": "",
"secondaryIdentifier": "",
"nameIdentifierType": ""
}
],
"localNameIdentifier": [
{
"primaryIdentifier": "로버트 반스",
"secondaryIdentifier": "",
"nameIdentifierType": "LEGL"
}
]
}
}
},
{
"naturalPerson": {
"name": {
"nameIdentifier": [
{
"primaryIdentifier": "Barnes",
"secondaryIdentifier": "Robert",
"nameIdentifierType": "LEGL"
}
],
"localNameIdentifier": [
{
"primaryIdentifier": "로버트 반스",
"secondaryIdentifier": "",
"nameIdentifierType": "LEGL"
}
]
}
}
}
],
"accountNumber": [
"rJChk8e71gxVhyJSr1srzZxWhVisWMMYKZ:tag or memo"
]
},
"Beneficiary": {
},
"OriginatingVASP": {
}
}
'Beneficiary': 'naturalPerson'
When the beneficiary is an individual, under the 'name' object, ❗'nameIdentifier' is required❗, whereas 'localNameIdentifier' is optional. Since the 'nameIdentifier' is required, enter blank if there is no matching value.
Typically, the 'nameIdentifier' contains the English name, while the 'localNameIdentifier' holds the Korean name (or other local language names).
However, when communicating between Korean VASPs, it is agreed that the 'nameIdentifier' will contain the Korean name and the 'localNameIdentifier' will contain the English name. Detailed guidelines can be found in the Name(nameIdentifier) notation section.
{
"Originator": {
},
"Beneficiary": {
"beneficiaryPersons": [
{
"naturalPerson": {
"name": {
"nameIdentifier": [
{
"primaryIdentifier": "",
"secondaryIdentifier": "",
"nameIdentifierType": ""
}
],
"localNameIdentifier": [
{
"primaryIdentifier": "앨리스 스미스",
"secondaryIdentifier": "",
"nameIdentifierType": "LEGL"
}
]
},
"dateAndPlaceOfBirth": {
"dateOfBirth": "1990-01-01",
"placeOfBirth": "LA"
},
"customerIdentification": "customernumber in Max 50 Text",
"countryOfResidence": "US"
}
}
],
"accountNumber": [
"rHcFoo6a9qT5NHiVn1THQRhsEGcxtYCV4d:tag or memo"
]
},
"OriginatingVASP": {
}
}
'Beneficiary': 'legalPerson'
When the beneficiary is a corporate entity, under the 'originatorPersons' object, ❗both a 'legalPerson' and at least one 'naturalPerson' are required❗. The 'legalPerson' section contains corporate details, while 'naturalPerson' includes the corporate representative(CEO)'s information.
The same applies in this case, under the 'name' object, ❗'nameIdentifier' is required❗, whereas 'localNameIdentifier' is optional. Since the 'nameIdentifier' is required, enter blank if there is no matching value.
If there are multiple corporate representatives, add as many 'naturalPerson' objects as needed to the 'beneficiaryPersons' array.
The 'nameIdentifier' contains the English name, while the 'localNameIdentifier' holds the Korean name (or other local language names).
However, when communicating between Korean VASPs, it is agreed that the 'nameIdentifier' will contain the Korean name and the 'localNameIdentifier' will contain the English name. Detailed guidelines can be found in the Name(nameIdentifier) notation section.
{
"Originator": {
},
"Beneficiary": {
"beneficiaryPersons": [
{
"legalPerson": {
"name": {
"nameIdentifier": [
{
"legalPersonName": "Korbit Inc.",
"legalPersonNameIdentifierType": "LEGL"
}
]
},
"nationalIdentification": {
"nationalIdentifier": "XXXXXXXXXXXXXXXXXXXX",
"nationalIdentifierType": "LEIX"
},
"customerIdentification": "customernumber in Max 50 Text",
"countryOfRegistration": "KR"
}
},
{
"naturalPerson": {
"name": {
"nameIdentifier": [
{
"primaryIdentifier": "",
"secondaryIdentifier": "",
"nameIdentifierType": ""
}
],
"localNameIdentifier": [
{
"primaryIdentifier": "앨리스 스미스",
"secondaryIdentifier": "",
"nameIdentifierType": "LEGL"
}
]
}
}
},
{
"naturalPerson": {
"name": {
"nameIdentifier": [
{
"primaryIdentifier": "Smith",
"secondaryIdentifier": "Alice",
"nameIdentifierType": "LEGL"
}
],
"localNameIdentifier": [
{
"primaryIdentifier": "앨리스 스미스",
"secondaryIdentifier": "",
"nameIdentifierType": "LEGL"
}
]
}
}
}
],
"accountNumber": [
"rHcFoo6a9qT5NHiVn1THQRhsEGcxtYCV4d:tag or memo"
]
},
"OriginatingVASP": {
}
}
OriginatingVASP
The 'OriginatingVASP' object contains information about the sending VASP.
Under 'legalPerson', both 'name' and 'countryOfRegistration' are required, and either 'geographicAddress' or 'nationalIdentification' should also be entered.
When using 'nationalIdentification', it's recommended to include 'registrationAuthority', the details of the issuing body. Download the 'GLEIF Registration Authorities List' from the bottom of the GLEIF website, locate the Authority Code that corresponds with your country and registration type, and input it.
{
"Originator": {
},
"Beneficiary": {
},
"OriginatingVASP": {
"originatingVASP": {
"legalPerson": {
"name": {
"nameIdentifier": [
{
"legalPersonName": "Korbit Inc.",
"legalPersonNameIdentifierType": "LEGL"
}
]
},
"geographicAddress": [
{
"addressType": "GEOG",
"streetName": "Example Street",
"buildingNumber": "123",
"buildingName": "Example Building",
"postcode": "00000",
"townName": "Seoul",
"addressLine": [
"100 Teheran-ro 1-gil, Gangnam-gu",
"10th floor"
],
"countrySubDivision": "N/A",
"country": "KR"
}
],
"nationalIdentification": {
"nationalIdentifier": "EXAMPLE-TAX-ID",
"nationalIdentifierType": "RAID",
"registrationAuthority": "RA000657"
},
"countryOfRegistration": "KR"
}
}
}
}
When Receiving(Deposit)
'BeneficiaryVASP'
The receiving VASP adds their 'BeneficiaryVASP' information to the 'Originator', 'Beneficiary', and 'OriginatingVASP' information contained in the 'Asset Transfer Authorization Request' and sends it back to the originating VASP.
Under 'legalPerson', both 'name' and 'countryOfRegistration' are required, and either 'geographicAddress' or 'nationalIdentification' should also be entered.
When using 'nationalIdentification', it's recommended to include 'registrationAuthority', the details of the issuing body. Download the 'GLEIF Registration Authorities List' from the bottom of the GLEIF website, locate the Authority Code that corresponds with your country and registration type, and input it.
{
"Originator": {
},
"Beneficiary": {
},
"OriginatingVASP": {
},
"BeneficiaryVASP": {
"beneficiaryVASP": {
"legalPerson": {
"name": {
"nameIdentifier": [
{
"legalPersonName": "Coinone Inc.",
"legalPersonNameIdentifierType": "LEGL"
}
]
},
"geographicAddress": [
{
"addressType": "GEOG",
"streetName": "Example Street",
"buildingNumber": "456",
"buildingName": "Example Building",
"postcode": "00000",
"townName": "Seoul",
"addressLine": [
"100 Teheran-ro 1-gil, Gangnam-gu",
"10th floor"
],
"countrySubDivision": "N/A",
"country": "KR"
}
],
"nationalIdentification": {
"nationalIdentifier": "6948624434",
"nationalIdentifierType": "RAID",
"registrationAuthority": "RA000657"
},
"countryOfRegistration": "KR"
}
}
}
}