Full Examples and Structure Definition

The detail of structure definition is below, the following structure is a full example of IVMS-101.

{
  "ivms101": {
    "OriginatingVASP": {
      "originatingVASP": {
        // required
        "legalPerson": {
          // required, nameIdentifier*, localNameIdentifier, phoneticNameIdentifier
          "name": {
            "nameIdentifier": [
              {
                "legalPersonName": "Originator VASP Company Name - VVVV Inc.",
                "legalPersonNameIdentifierType": "LEGL" // Usually Fixed as LEGL //  for legal person: LEGL, SHRT, TRAD
              }
            ]
          },
          // required, For Company Legal Person use RAID and fill your company ID in nationalIdentifier
          "nationalIdentification": {
            // nationalIdentifierType: ISO20022, ARNU, CCPT, RAID, DRLC, FIIN, TXID, SOCS, IDCD, LEIX, MISC,
            "nationalIdentifierType": "RAID",
            // registrationAuthority: GLEIF code (i.e: 香港公司註冊處核發 Hong Kong Company Registry Approved, For more please check: https://www.gleif.org/en/about-lei/code-lists/gleif-registration-authorities-list)
            "registrationAuthority": "RA000388",
            // countryOfIssuse: two alphabet country code
            "countryOfIssuse": "HK",
            // nationalIdentifier: (i.e: Your Company ID from authroity)
            "nationalIdentifier": "38429049028390482"
          },
          // required
          "geographicAddress": [
            {
              // required
              "country": "HK", // ISO-3166-1 alpha-2 codes
              "townName": "Hong Kong",
              "addressType": "GEOG", // HOME, BIZZ, GEOG
              "addressLine": ["Please fill your address here"],

              // optional:
              "department": "OfficeOfTheCEO",
              "subDepartment": "InternalAudit8562",
              "streetName": "SiliconAlley65",
              "buildingNumber": "J4H6",
              "buildingName": "VirtualTower200",
              "floor": "Floor94",
              "postBox": "CB842",
              "room": "BionicRoom38",
              "postCode": "TT7643",
              "townLocationName": "E-Sector",
              "districtName": "BlockchainDistrict",
              "countrySubDivision": "E-Province"
            }
          ],
          // required
          "countryOfRegistration": "HK"
        }
      }
    },
    "Originator": {
      // required, the user wallet address
      "accountNumber": [
        "1GURHee2JsCkdpxVisjbjAeNhbDbGub8R4" // Max 100 text, ^[a-zA-Z0-9' ]{1,100}$
      ],
      "originatorPersons": [
        {
          "naturalPerson": {
            // optional
            "dateAndPlaceOfBirth": {
              "placeOfBirth": "US", // ISO-3166-1 alpha-2 codes
              "dateOfBirth": "1986-11-21"
            },
            // required
            "name": {
              // have: nameIdentifier (required), localNameIdentifier (required), phoneticNameIdentifier (optional)
              "localNameIdentifier": [
                {
                  // nameIdentifierType: Usually Fixed as LEGL // for natural person: ALIA, BIRT, MAID, LEGL, MISC
                  "nameIdentifierType": "LEGL",
                  // primaryIdentifier: lastname, or lastname + firstname
                  "primaryIdentifier": "サトシ",
                  // primaryIdentifier: firstname, or leave empty if cannot recognize
                  "secondaryIdentifier": "ナカモト"
                }
              ],
              "nameIdentifier": [
                {
                  "nameIdentifierType": "LEGL",
                  "primaryIdentifier": "Satoshi",
                  "secondaryIdentifier": "Nakamoto"
                }
              ],
              "phoneticNameIdentifier": [
                {
                  "nameIdentifierType": "LEGL",
                  "primaryIdentifier": "Satoshi",
                  "secondaryIdentifier": "Nakamoto"
                }
              ]
            },
            // optional
            "geographicAddress": [
              {
                // required (if have):
                "addressType": "GEOG", // HOME, BIZZ, GEOG
                // townName can also be city / town
                "townName": "VirtualTown",
                "addressLine": ["Line489", "Line762"],
                "country": "US", // ISO-3166-1 alpha-2 codes

                // optional:
                "department": "OfficeOfTheCEO",
                "subDepartment": "InternalAudit8562",
                "streetName": "SiliconAlley65",
                "buildingNumber": "J4H6",
                "buildingName": "VirtualTower200",
                "floor": "Floor94",
                "postBox": "CB842",
                "room": "BionicRoom38",
                "postCode": "TT7643",
                "townLocationName": "E-Sector",
                "districtName": "BlockchainDistrict",
                // countrySubDivision is also a country state
                "countrySubDivision": "E-Province"
              }
            ],
            // optional
            "nationalIdentification": {
              // nationalIdentifier, for example Passport number (CCPT), ^[a-zA-Z0-9' ]{1,35}$
              "nationalIdentifier": "1032903940290499SDF3-40DA024",
              // CCPT: Passport, ISO20022, ARNU, CCPT, RAID, DRLC, FIIN, TXID, SOCS, IDCD, LEIX, MISC
              "nationalIdentifierType": "CCPT",
              // registrationAuthority 不填寫，外交部發行的不是法人單位，是政府單位。 don't fill the registrationAuthority, the identity approved by immigration affairs is government department, not legal person
              "countryOfIssuse": "HK"
            },
            // optional, (i.e: customer id from originator service)
            "customerIdentification": "10929392485393",
            // required
            "countryOfResidence": "US"
          }
        }
      ]
    },
    "Beneficiary": {
      "beneficiaryPersons": [
        // required: naturalPerson or legalPerson
        // NOTE: if you send to legalPerson, please fill [{naturalPerson:{}},{legalPerson:{}}] both, the natural person only need to given [{naturalPerson}]
        {
          "legalPerson": {
            // required, nameIdentifier*, localNameIdentifier, phoneticNameIdentifier
            "name": {
              "nameIdentifier": [
                {
                  "legalPersonName": "Paycase Inc",
                  "legalPersonNameIdentifierType": "LEGL" // Usually Fixed as LEGL // for legal person: LEGL, SHRT, TRAD
                }
              ]
            },
            // required, For Company Legal Person use RAID and fill your company ID in nationalIdentifier
            "nationalIdentification": {
              // RAID is means nationalIdentifier is company ID in authority coutnry
              "nationalIdentifierType": "RAID", // ^[a-zA-Z0-9' ]{1,35}$
              // GLEIF code (i.e: 香港公司註冊處核發 Hong Kong Company Registry Approved, For more please check: https://www.gleif.org/en/about-lei/code-lists/gleif-registration-authorities-list)
              "registrationAuthority": "RA000388",
              "countryOfIssuse": "HK",
              // (i.e: Your Company ID from authroity)
              "nationalIdentifier": "38429049028390482" // ISO20022, ARNU, CCPT, RAID, DRLC, FIIN, TXID, SOCS, IDCD, LEIX, MISC
            },
            // optional
            "geographicAddress": [
              // SAME AS Originator's geographicAddress
            ],
            // optional,  (i.e: customer id from originator service)
            "customerIdentification": "0x3E9181d09E56AdEF3bbc8BAb664Ce6B268Bf6e62",
            // optional
            "countryOfRegistration": "HK" // ISO-3166-1 alpha-2 codes
          }
        },
        // required both legalPerson (ex: CEO name) and naturalPerson
        {
          // example fields below, please refer to above naturalPerson structure
          "naturalPerson": {
            "dateAndPlaceOfBirth": {
              "placeOfBirth": "US",
              "dateOfBirth": "1986-11-21"
            },
            "name": {
              "localNameIdentifier": [
                {
                  "nameIdentifierType": "LEGL",
                  "primaryIdentifier": "サトシ",
                  "secondaryIdentifier": "ナカモト"
                }
              ],
              "nameIdentifier": [
                {
                  "nameIdentifierType": "LEGL",
                  "primaryIdentifier": "Satoshi",
                  "secondaryIdentifier": "Nakamoto"
                }
              ]
            },
            "geographicAddress": [
              {
                "addressType": "GEOG",
                "streetName": "Potential Street",
                "buildingNumber": "123",
                "buildingName": "Cheese Hut",
                "postcode": "91361",
                "townName": "Thousand Oaks",
                "countrySubDivision": "California",
                "country": "US"
              }
            ],
            "nationalIdentification": {
              "nationalIdentifier": "1032903940290499SDF3-40DA024",
              "nationalIdentifierType": "CCPT",
              "countryOfIssuse": "HK"
            },
            "customerIdentification": "10929392485393",
            "countryOfResidence": "US"
          }
        }
      ],
      "accountNumber": ["1GURHee2JsCkdpxVisjbjAeNhbDbGub8R4"]
    }
  }
}

The nameIdentifierType is commonly set to 'LEGL'.
primaryIdentifier is lastName, secondaryIdentifier is firstName.
For primaryIdentifier, secondaryIdentifier. If the name cannot be separated, please fill firstName and lastName together (1. firstName 2. lastName).
firstName: givenName, lastName: familyName.
For the current version of IVMS specification, only the root level has first capital naming (e.g: Beneficiary, BeneficiaryVASP, Originator, OriginatingVASP).

In addition:

registrationAuthority

registrationAuthority is GLEIF code that you could find in GLEIF list: https://www.gleif.org/en/about-lei/code-lists/gleif-registration-authorities-list
registrationAuthority available for legalPerson, but the identity approved by immigration affairs is government department, not legal person.

nameIdentifierType (naturalPersonNameType)

ALIA (Alias name): A name other than the legal name by which a natural person is also known.
BIRT (Name at birth): The name given to a natural person at birth.
MAID (Maiden name): The original name of a natural person who has changed their name after marriage.
LEGL (Legal name): The name that identifies a natural person for legal, official or administrative purposes.
MISC (Unspecified): A name by which a natural person may be known but which cannot otherwise be categorized or the category of which the sender is unable to determine.

legalPersonNameIdentifierType (legalPersonNameType)

LEGL (Legal name): Official name under which an organisation is registered.
SHRT (Short name): Specifies the short name of the organisation.
TRAD (Trading name): Name used by a business for commercial purposes, although its registered legal name, used for contracts and other formal situations, may be another.

nationalIdentifierType

ARNU: Alien registration number (a number issued by the government to foreigners to identify them)
CCPT: passport number
RAID: (body corporate only) Business registration number provided by the authority
DRLC: Driver's License Number
FIIN: Foreign Investor Number (number assigned to foreign investors)
TXID: Number given by the tax authority
SOCS: Social Security Number or National Identification Number
IDCD: Identity card number assigned by a state agency
LEIX: (Legal entities only) Global legal entity identification number, LEI code assigned in accordance with the ISO 17442 standard
MISC: ID card number from other countries

Others

Other fields for more over,these are not necessary for the payloads:

localNameIdentifier: for non-English name of identity person, full name separated into primary and secondary identifier using local characters.

{
  "primaryIdentifier": "김",
  "secondaryIdentifier": "김지수",
  "nameIdentifierType": "LEGL" // IVMS101: ALIA, BIRT, MAID, LEGL, MISC
}

phoneticNameIdentifier: Alternate representation of a name that corresponds to the manner the name is pronounced.

{
  "primaryIdentifier": "Kim",
  "secondaryIdentifier": "Jisoo",
  "nameIdentifierType": "LEGL" // IVMS101: ALIA, BIRT, MAID, LEGL, MISC
}

transferPath (IntermediaryVasp): The transfer path refers to the intermediary VASP(s) participating in a serial chain that receive(s) and retransmit(s) a VA transfer on behalf of the originating VASP and the beneficiary VASP, or another intermediary VASP, together with their corresponding sequence number.
```
{
  "transferPath": [
    // IntermediaryVasp
    {
      "intermediaryVasp": {
        // legalPerson of vasp },
        "sequence": 0 // count from 0 to 9007199254740991L
      }
    }
  ]
}
```
payloadMetadata (TransliterationMethodCode): Data describing the contents of the payload. TransliterationMethodCode is the method used to map from a national system of writing to Latin script.
```
{
  "payloadMetadata": [
    "kore" // ISO 15924, arab, aran, armn, cyrl, deva, geor, grek, hani, hebr, kana, kore, thai, othr
  ]
}
```

For ISO 15924, the available enum is: arab, aran, armn, cyrl, deva, geor, grek, hani, hebr, kana, kore, thai, othr.

arab, Arabic (Arabic language) ISO 233-2:1993
aran, Arabic (Persian language) ISO 233-3:1999
armn, Armenian ISO 9985:1996
cyrl, Cyrillic ISO 9:1995
deva, Devanagari & related Indic ISO 15919:2001
geor, Georgian ISO 9984:1996
grek, Greek ISO 843:1997
hani, Han (Hanzi, Kanji, Hanja) ISO 7098:2015
hebr, Hebrew ISO 259-2:1994
kana, Kana ISO 3602:1989
kore, Korean Revised Romanization of Korean
thai, Thai ISO 11940-2:2007
othr, Script other than those listed above Unspecified

For example: 한국어 (hangug-eo), the method is "kore".