About IVMS101 Standard

Official document of IVMS101 specification

  • Visit the link below to download the official IVMS101 specifications.

  • The standard specification might be updated continuously. Keep tracking the change log regularly.

Overview

IVMS101 (InterVASP Messaging Standards 101) provides a standard data model of the originator/beneficiary information handled by the VASPs, in order to satisfy Travel Rules required by FATF.

It was designed for VASPs, regulatory authorities performing VA services, and Travel Rules solution providers.

Currently, various Travel Rules solutions including VerifyVASP have chosen IVMS101 as data format. It will be the minimum requirement enabling interactions among Travel Rules solutions later.

Therefore, development and operation managers of each VASP wishing to connect to VerifyVASP must be well aware of the IVMS101 specification.

Terms

TermsExplanation

beneficiary

An individual or a corporate requested to receive VA

beneficiary VASP

A VASP receiving assets from the originating VASP for a beneficiary. VASP to which a beneficiary belongs.

component

Combined data format composed of more than one reusable factor

constraint

Rules or constraints to be applied to data format, components, or entities

country

A country with an independent government

country subdivision

Administrative districts within a country

data entity

An individual object which can be distinguished from a data model

datatype

Data value format which can be expressed by an element.

element

Data unit with an exact meaning which distinguished the features of data entity

intermediary VASP

Every VASP that receives and re-sends VA between the originating VASP and the beneficiary VASP

legal person

Any corporate body (ex. companies, foundations, partnership, conference)

natural person

An individual who can be uniquely distinguished

originating VASP

A VASP sending assets to the beneficiary VASP from an originator. VASP to which an originator belongs.

originator

An individual or a corporate requesting to send VA

recommendation

FATF recommendation

registration authority

Institutions which register/issue certificates of public corporations in a district. For instance, IRS or financial authorities.

transfer

Transacting virtual assets from one account to the other in lieu of an individual or a corporate body

virtual asset

The digital value which can be traded or transferred digitally, or which can be used to pay or invest. The virtual assets do not include financial assets already treated by FATF or stock assets in digital form.

virtual asset service provider

Service providers which secure and manage virtual assets for individuals or corporate bodies, such as exchanges or wallet providers.

Notations

  • All entities and components of IVMS101 follow the notations of the upper camel case. No spaces between, and the first letter is upper case.

  • All elements of IVMS101 follow the lower camel case notation. No spaces between, and the first letter is lower case.

  • Datatype follows the upper camel case notations.

  • The names of entities, components, or elements do not restrict data format. In other words, a number in a name does not mandate you to use numbers only.

  • All values in the specifications of IVMS101 do not distinguish between upper and lower case unless noted otherwise.

Notation Language

  • Data must use UTF-8 encoding.

  • Unless noted otherwise, data must be expressed in Latin alphabets (A-Z, a-z) and numbers (0-9).

  • In countries that do not use Latin alphabets, one of the following must be used.

    • Transliterate into Latin alphabets.

    • Translate into a more prevalent language internationally.

  • A category whose element name includes 'local' may use the language of the country.

  • The letters below must be transliterated into Latin alphabets using the noted standard.

ScriptStandard

Arabic (Arabic language)

ISO 233-2:1993

Arabic (Persian language)

ISO 233-3:1999

Armenian

ISO 9985:1996

Cyrillic

ISO 9:1995

Devanagari & related Indic

ISO 15919:2001

Han (Hanzi, Kanji, Hanja)

ISO 7098:2015

Hebrew

ISO 259-2:1994

Georgian

ISO 9984:1996

Greek

ISO 843:1997

Kana

ISO 3602:1989

Korean

Revised Romanization of Korean

Thai

ISO 11940-2:2007

Data Type

component (Combined Data Type)

Person type

{
  "naturalPerson": { // [optional] person indicates an individual.
    ... // NaturalPerson type
  },
  "legalPerson": { // [optional] person is a corporate body.
    ... // LegalPerson type
  },
}
  • One of naturalPerson and legalPerson must be present.

NaturalPerson type

{
  "name": { // [required] Name of an individual
    ... // NaturalPersonName type
  },
  "geographicAddress": [ // [Deploy 0 or more] A geographical address of an individual
    { ... } // Address type
  ],
  "nationalIdentification": { // [optional] National Identification Number of an individual
    ... // NationalIdentification type
  },
  "customerIdentification": "xxx", // [optional] customer number of an individual, Text type
  "dateAndPlaceOfBirth": { // [optional] date and place of birth of an individual
    ... // DateAndPlaceOfBirth type
  },
  "countryOfResidence": "KR", // [optional] country of residence of an individual, CountryCode type
  "nationality": "KR" // [optional] nationality of an individual, CountryCode type
}
  • There must be at least one name, and one of the names must be a legal name(LEGL type).

  • An individual (natural person) must have one of the factors below to be distinguished.

    • geographicAddress with GEOG or HOME or BIZZ address type

    • customerNumber

    • nationalIdentification

    • dateAndPlaceOfBirth

  • A country in geographicAddress or countryOfResidence must be entered in 2 letter country code in ‘ISO-3166-1 alpha-2’ standard.

  • geographicAddress must include one of the following combinations

    • at least one addressLine

    • streetName and buildingName

    • streetName and buildingNumber

LegalPerson type

{
  "name": { // [required] name of the corporate body
    ... // LegalPersonName type
  },
  "geographicAddress": [ // [Deploy 0 or more] the address of the corporate body
    { ... } // Address type
  ],
  "customerIdentification": "xxx", // [optional] the customer number of the corporate body, Text type
  "nationalIdentification": { // [optional] national identification number of the corporate body
    ... // NationalIdentification type
  },
  "countryOfRegistration": "KR", // [optional] a country of registration of the corporate body
  "dateOfIncorporation": "2019-03-27" // [optional] date of incorporation of the corporate body
}
  • There must be at least one name of a corporate body, and one of the names must be a legal name(LEGL type).

  • A corporate body (legal person) must have one of the factors below to be distinguished.

    • geographicAddress with GEOG or HOME or BIZZ address type

    • customerNumber

    • nationalIdentification

  • A country in geographicAddress or countryOfRegistration must be entered in 2 letter country code in ‘ISO-3166-1 alpha-2’ standard.

  • geographicAddress must include one of the following combinations

    • at least one addressLine

    • streetName and buildingName

    • streetName and buildingNumber

NaturalPersonName type

{
  "nameIdentifier": [ // [Deploy 1 or more] Basic name category
    { ... } // NaturalPersonNameID type
  ],
  "localNameIdentifier": [ // [Deploy 0 or more] Name in local language
    { ... } // LocalNaturalPersonNameID type
  ],
  "phoneticNameIdentifier": [ // [Deploy 0 or more] Name written phonetically
    { ... } // LocalNaturalPersonNameID type
  ]
}
  • At least one name of nameIdentifier must be LEGL (legal name).

LegalPersonName type

{
  "nameIdentifier": [ // [Deploy 1 or more] Basic Name Category
    { ... } // LegalPersonNameID type
  ],
  "localNameIdentifier": [ // [Deploy 0 or more] Name in local language
    { ... } // LocalLegalPersonNameID type
  ],
  "phoneticNameIdentifier": [ // [Deploy 0 or more] Name written phonetically
    { ... } // LocalLegalPersonNameID type
  ]
}
  • At least one name of nameIdentifier must be LEGL (legal name).

NaturalPersonNameID type **** (Same with LocalNaturalPersonNameID)

{
  "primaryIdentifier": "Din", // [required] family name, last name
  "secondaryIdentifier": "James", // [optional] first name, forename
  "nameIdentifierType": "LEGL" // [required] Type of name
}
  • Values as below can be included in nameIdentifierType.

    • ALIA: alias name known prevalently

    • BIRT: Birth name

    • MAID: Name used before marriage

    • LEGL: Legal and official name

    • MISC : Other names that cannot be expressed by the categories above

  • You can enter a full name primaryIdentifier if the name cannot be separated into a first and last name.

LegalPersonNameID type **** (Same with LocalLegalPersonNameID)

{
  "legalPersonName": "Samsung Electronics Co., Ltd.", // [required] Corporate name
  "legalPersonNameIdentifierType": "LEGL" // [required] Type of name
}
  • Values as below can be included in legalPersonNameIdentifierType.

    • LEGL: legal and official name

    • SHRT: shortened name

    • TRAD: a commercial name

Address type

{
  "addressType": "GEOG", // [required] Address type
  "department": "xxx...xxx", // [optional] Department identifier of a large organization or a building
  "subDepartment": "xxx...xxx", // [optional] Subdepartment identifier of a large organization or a building
  "streetName": "xxx...xxx", // [optional] Name of the street
  "buildingNumber": "xxx...xxx", // [optional] Building Number
  "buildingName": "xxx...xxx", // [optional] Name of a building
  "floor": "xxx...xxx", // [optional] Floor in the building
  "postBox": "xxx...xxx", // [optional] postbox number
  "room": "xxx...xxx", // [optional] room number
  "postcode": "xxx...xxx", // [optional] Postal code
  "townName": "xxx...xxx", // [optional] Name of a town
  "townLocationName": "xxx...xxx", // [optional] Name of a specific location in a town
  "districtName": "xxx...xxx", // [optional] name of a district (ex. Gangnam-gu)
  "countrySubDivision": "xxx...xxx", // [optional] name of a state/do (a larger district)
  "addressLine": ["xxx", "xxx"], // [0 to 7] free address to distinguish a specific address
  "country": "KR" // [required] a country of residence
}
  • One of the following combinations must be included

    • At least one addressLine

    • streetName and buildingName

    • streetName and buildingNumber

  • Values as below can be included in addressType.

    • HOME: Home address

    • BIZZ: Business address

    • GEOG : Geographical address

  • If the address is difficult to be divided into smaller categories, the whole address can be entered in a single string of letters in addressLine

DateAndPlaceOfBirth type

{
  "dateOfBirth": "YYYY-MM-DD", // [required] Date of birth
  "placeOfBirth": "Gangnam-gu Seoul" // [required] place of birth(town, city, state, country, etc)
}

NationalIdentification type

{
  "nationalIdentifier": "198723-8971987", // [required] National Identification Number
  "nationalIdentifierType": "SOCS", // [required] Type of identification number
  "countryOfIssue": "KR", // [optional] Country issued
  "registrationAuthority": "RA0000099" // [optional] institution code of the institution
}
  • The values below can be included in nationalIdentifierType.

    • ARNU: Foreigner's number (number issued to foreigners by a government to identify him/her)

    • CCPT: Passport number

    • RAID: (Only corporate bodies) Business registration number given by authorities

    • DRLC: Driver's license number

    • FIIN: Foreign investor number (Number allocated to foreign investors)

    • TXID: Number given by taxation authorities

    • SOCS: Social Security Number, or National Identification Number

    • IDCD: ID card number allocated by national institutions

    • LEIX: (Only corporate bodies)global corporate body identification number allocated according to ISO 17442 standard, LEI code

    • MISC: Other national identification number

  • In countryOfIssue, you must enter 2 letter country code defined in ‘ISO-3166-1 alpha-2’ standard.

  • In registrationAuthority, you must enter the code of issuing institution managed by the ‘Global Legal Entity Identifier Foundation (GLEIF).’

    • (’RA’ + eight letter code composed of 6 numbers)

  • Corporate bodies must satisfy all of the conditions below.

    • In nationalIdentifierType, one of ‘RAID’, ‘LEIX’, ‘TXID, ‘MISC’ must be entered.

    • If nationalIdentifierType is not ‘LEIX,’ you must enter ‘registrationAuthority’.

    • If nationalIdentifierType is ‘LEIX,’ you must not enter 'registrationAuthority.’

    • Do not enter countryOfIssue category. (Only for individuals)

    • If nationalIdentifierType is ‘LEIX,’ 20 letter LEIX code must be entered in ‘nationalIdentifier.’

IntermediaryVASP type

{
  "intermediaryVASP": { // [required] Information about an intermediary VASP
    ... // Person type
  },
  "sequence": 0 // [required] Shows how many VASPs are before the intermediary VASP
  • sequence value starts from 0 to the last intermediary VASP sequentially.

Data Model

The whole IVMS101 data is largely composed of 6 data entities.

{
  "Originator": { // [required] Originator information
    ... // Originator model
  },
  "Beneficiary": { // [required] Beneficiary Information
    ... // Beneficiary model
  },
  "OriginatingVASP": { // [optional] Originating VASP Information
    ... // OriginatingVASP model
  },
  "BeneficiaryVASP": { // [optional] Beneficiary VASP Information
    ... // BeneficiaryVASP model
  },
  "TransferPath": { // [optional] Intermediary VASP Information
    ... // TransferPath model
  },
  "PayloadMetadata": { // [optional] Other metadata
    ... // PayloadMetadata model
  }
}

Originator model

{
  "originatorPersons": [ // [Deploy 1 or more] Originator information
    { ... } // Person type
  ],
  "accountNumber": [ // [Deploy 0 or more] Identifier of the account used in transaction(ex. wallet address)
    "xxxxxxx" // Text type
  ]
}
  • accountNumber is case-sensitive.

Beneficiary model

{
  "beneficiaryPersons": [ // [Deploy 1 or more] Beneficiary information
    { ... } // Person type
  ],
  "accountNumber": [ // [Deploy 0 or more] Identifier of the account used in transaction(ex. wallet address)
    "xxxxxxx" // Text type
  ]
}
  • accountNumber is case-sensitive.

OriginatingVASP model

{
  "originatingVASP": { // [optional] Originating VASP information
    ... // Person type
  }
}
  • Currently, the originating VASP information is automatically filled in the VV central server during the verification request process.

  • Thus, the originatingVASP category does not have to be included in ivms101 structure.

BeneficiaryVASP model

{
  "beneficiaryVASP": { // [optional] Beneficiary VASP information
    ... // Person type
  }
}
  • Currently, the beneficiary VASP information is automatically filled in the VV central server during the verification request process.

  • Thus, the beneficiaryVASP category does not have to be included in ivms101 structure.

TransferPath model

{
  "transferPath": [ // [Deploy 0 or more] Intermediary VASP information
    { ... } // IntermediaryVASP type
  ]
}
  • Currently, VV does not support TransferPath setting.

PayloadMetadata model

{
  "transliterationMethod": [
    // [Deploy 0 or more] a way to change local characters into Latin alphabet
    "kore"
  ]
}
  • In transliterationMethod, enter ways to change non-Latin characters (like Hangul) into Latin alphabets. You can use one below:

Last updated