diff --git a/ecosystem/sep-0009.md b/ecosystem/sep-0009.md index 17ed90ecd..20683dd75 100644 --- a/ecosystem/sep-0009.md +++ b/ecosystem/sep-0009.md @@ -6,120 +6,157 @@ Title: Standard KYC Fields Author: stellar.org Status: Active Created: 2018-07-27 -Updated: 2023-02-10 -Version 1.11.0 +Updated: 2023-06-30 +Version 1.12.0 ``` ## Simple Summary -This SEP defines a list of standard KYC and AML fields for use in Stellar ecosystem protocols. Issuers, banks, and other entities on Stellar should use these fields when sending or requesting KYC / AML information with other parties on Stellar. This is an evolving list, so please suggest any missing fields that you use. +This SEP defines a list of standard KYC, AML, and financial account-related fields for use in Stellar ecosystem +protocols. Applications on Stellar should use these fields when sending or requesting KYC, AML, or financial +account-related information with other parties on Stellar. This is an evolving list, so please suggest any missing +fields that you use. -This is a list of possible fields that may be necessary to handle many different use cases, there is no expectation that any particular fields be used for a particular application. The best fields to use in a particular case is determined by the needs of the KYC or AML application. +This is a list of possible fields that may be necessary to handle many different use cases, there is no expectation that +any particular fields be used for a particular application. The best fields to use in a particular case is determined by +the needs of the application. ## Encodings -ISO encodings are used for fields wherever possible. The table below lists the encodings used for different types of information. +ISO encodings are used for fields wherever possible. The table below lists the encodings used for different types of +information. -Field Type | Number of characters | Format / Encoding ------------|----------------------|------------------ -language | 2 | [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) -country | 3 | [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) -date | 10 | [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date-only format -phone number | varies | [E.164](https://en.wikipedia.org/wiki/E.164) -occupation | 3 | [ISCO08](https://en.wikipedia.org/wiki/International_Standard_Classification_of_Occupations) +| Field Type | Number of characters | Format / Encoding | +| ------------ | -------------------- | -------------------------------------------------------------------------------------------- | +| language | 2 | [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) | +| country | 3 | [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) | +| date | 10 | [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date-only format | +| phone number | varies | [E.164](https://en.wikipedia.org/wiki/E.164) | +| occupation | 3 | [ISCO08](https://en.wikipedia.org/wiki/International_Standard_Classification_of_Occupations) | ## Field Naming Conventions -Where possible we use field names from [schema.org](https://schema.org/Person). Words are separated with underlines as that convention has previously been established in Stellar protocols. +Where possible we use field names from [schema.org](https://schema.org/Person). Words are separated with underlines as +that convention has previously been established in Stellar protocols. ### Dot Notation Field names should always be used as strings. For example: + ```json { - "organization.name": "Stellar Development Foundation" + "organization.name": "Stellar Development Foundation" } ``` -The dot notation is _not_ an indication that the fields described should be contained in a nested object under a top-level key. - -## KYC / AML Fields - -### Natural Person KYC fields - -Name | Type | [Format](#encodings) | Description ------|------|----------------------|------------ -`family_name` or `last_name` | string | | Family or last name -`given_name` or `first_name` | string | | Given or first name -`additional_name` | string | | Middle name or other additional name -`address_country_code` | string | ISO 3166-1 alpha-3 country code | country code for current address -`state_or_province` | string | | name of state/province/region/prefecture -`city` | string | | name of city/town -`postal_code` | string | | Postal or other code identifying user's locale -`address` | string | | Entire address (country, state, postal code, street address, etc...) as a multi-line string -`mobile_number` | string | E.164 phone number| Mobile phone number with country code, in E.164 format -`email_address` | string | | Email address -`birth_date` | date | | Date of birth, e.g. `1976-07-04` -`birth_place` | string | | Place of birth (city, state, country; as on passport) -`birth_country_code` | string | ISO 3166-1 alpha-3 country code | ISO Code of country of birth -`bank_account_number` | string | | Number identifying bank account -`bank_account_type` | string | | `checking` or `savings` -`bank_number` | string | | Number identifying bank in national banking system (routing number in US) -`bank_phone_number` | string | | Phone number with country code for bank -`bank_branch_number` | string | | Number identifying bank branch -`clabe_number` | string | | Bank account number for Mexico -`tax_id` | string | | Tax identifier of user in their country (social security number in US) -`tax_id_name` | string | | Name of the tax ID (`SSN` or `ITIN` in the US) -`occupation` | number | | Occupation ISCO code -`employer_name` | string | | Name of employer -`employer_address` | string | | Address of employer -`language_code` | string | ISO 639-1 language code | primary language -`id_type` | string | | `passport`, `drivers_license`, `id_card`, etc... -`id_country_code` | string | ISO 3166-1 alpha-3 country code | country issuing passport or photo ID as ISO 3166-1 alpha-3 code -`id_issue_date` | date | | ID issue date -`id_expiration_date` | date | | ID expiration date -`id_number` | string | | Passport or ID number -`photo_id_front` | binary | | Image of front of user's photo ID or passport -`photo_id_back` | binary | | Image of back of user's photo ID or passport -`notary_approval_of_photo_id` | binary | | Image of notary's approval of photo ID or passport -`ip_address` | string | | IP address of customer's computer -`photo_proof_residence` | binary | | Image of a utility bill, bank statement or similar with the user's name and address -`sex` | string | | `male`, `female`, or `other` -`proof_of_income` | binary | | Image of user's proof of income document -`proof_of_liveness` | binary | | video or image file of user as a liveness proof -`cbu_number` | string | | Clave Bancaria Uniforme (CBU) or Clave Virtual Uniforme (CVU). The unique key for every bank account in Argentina used for receiving deposits. -`cbu_alias` | string | | The alias for a Clave Bancaria Uniforme (CBU) or Clave Virtual Uniforme (CVU). - -### Organization KYC fields - -Name | Type | [Format](#encodings) | Description ------|------|---|---------- -`organization.name` | string | | Full organization name as on the incorporation papers -`organization.VAT_number` | string | | Organization VAT number -`organization.registration_number` | string | | Organization registration number -`organization.registration_date` | string | | Date the organization was registered -`organization.registered_address` | string | | Organization registered address -`organization.number_of_shareholders` | number | | Organization shareholder number -`organization.shareholder_name` | string | | Can be an organization or a person and should be queried recursively up to the ultimate beneficial owners (with KYC information for natural persons such as above) -`organization.photo_incorporation_doc` | binary | | Image of incorporation documents -`organization.photo_proof_address` | binary | | Image of a utility bill, bank statement with the organization's name and address -`organization.address_country_code` | string | ISO 3166-1 alpha-3 country code | country code for current address -`organization.state_or_province` | string | | name of state/province/region/prefecture -`organization.city` | string | | name of city/town -`organization.postal_code` | string | | Postal or other code identifying organization's locale -`organization.director_name` | string | | Organization registered managing director (the rest of the information should be queried as an individual using the fields above) -`organization.website` | string | | Organization website -`organization.email` | string | | Organization contact email -`organization.phone` | string | | Organization contact phone - -### Addresses - -Address formatting varies widely from country to country and even within each country. See [here](https://stackoverflow.com/questions/11160192/how-to-parse-freeform-street-postal-address-out-of-text-and-into-components) for details. Rather than attempting to create a field for each possible part of an address in every country, this protocol takes a middle of the road approach. Address fields that are fairly universal can be encoded with the `country_code`, `state_or_province`, `city`, and `postal_code` fields. Full addresses, however, should be encoded as a single multi-line string in the `address` field. This allows any address in the world to be represented with a limited number of fields. If address parsing is necessary, parsing will be easier since the country, city, and postal code are already separate fields. + +The dot notation is _not_ an indication that the fields described should be contained in a nested object under a +top-level key. + +## Natural Person Fields + +| Name | Type | Description | +| ----------------------------- | ------ | ------------------------------------------------------------------------------------------- | +| `family_name` or `last_name` | string | Family or last name | +| `given_name` or `first_name` | string | Given or first name | +| `additional_name` | string | Middle name or other additional name | +| `address_country_code` | string | country code for current address | +| `state_or_province` | string | name of state/province/region/prefecture | +| `city` | string | name of city/town | +| `postal_code` | string | Postal or other code identifying user's locale | +| `address` | string | Entire address (country, state, postal code, street address, etc...) as a multi-line string | +| `mobile_number` | string | Mobile phone number with country code, in E.164 format | +| `email_address` | string | Email address | +| `birth_date` | date | Date of birth, e.g. `1976-07-04` | +| `birth_place` | string | Place of birth (city, state, country; as on passport) | +| `birth_country_code` | string | ISO Code of country of birth | +| `bank_account_number` | string | Number identifying bank account | +| `tax_id` | string | Tax identifier of user in their country (social security number in US) | +| `tax_id_name` | string | Name of the tax ID (`SSN` or `ITIN` in the US) | +| `occupation` | number | Occupation ISCO code | +| `employer_name` | string | Name of employer | +| `employer_address` | string | Address of employer | +| `language_code` | string | primary language | +| `id_type` | string | `passport`, `drivers_license`, `id_card`, etc... | +| `id_country_code` | string | country issuing passport or photo ID as ISO 3166-1 alpha-3 code | +| `id_issue_date` | date | ID issue date | +| `id_expiration_date` | date | ID expiration date | +| `id_number` | string | Passport or ID number | +| `photo_id_front` | binary | Image of front of user's photo ID or passport | +| `photo_id_back` | binary | Image of back of user's photo ID or passport | +| `notary_approval_of_photo_id` | binary | Image of notary's approval of photo ID or passport | +| `ip_address` | string | IP address of customer's computer | +| `photo_proof_residence` | binary | Image of a utility bill, bank statement or similar with the user's name and address | +| `sex` | string | `male`, `female`, or `other` | +| `proof_of_income` | binary | Image of user's proof of income document | +| `proof_of_liveness` | binary | video or image file of user as a liveness proof | + +## Financial Account Fields + +These fields should be used to request or provide information about off-chain financial accounts. Because both natural +persons and organizations can use the same types of financial accounts, these fields can be used to request or provide +information about natural persons or organizations. The `organization.` prefix should be used when requesting or +providing fields related to an organization. + +Note that some of these fields are generic, such as `bank_number`, which could potentially be used to identify a bank in +any country, and some fields are specific to a given country, such as `cbu_number`, which contains a bank number in +addition to other pieces of information. In order to optimize for the user's experience, it is recommended that +applications use fields that are the most familiar, which are often specific to a given country or financial system. + +| Name | Type | Description | +| -------------------- | ------ | ------------------------------------------------------------------------------ | +| `bank_account_type` | string | `checking` or `savings` | +| `bank_number` | string | Number identifying bank in national banking system (routing number in US) | +| `bank_phone_number` | string | Phone number with country code for bank | +| `bank_branch_number` | string | Number identifying bank branch | +| `clabe_number` | string | Bank account number for Mexico | +| `cbu_number` | string | Clave Bancaria Uniforme (CBU) or Clave Virtual Uniforme (CVU). | +| `cbu_alias` | string | The alias for a Clave Bancaria Uniforme (CBU) or Clave Virtual Uniforme (CVU). | + +## Organization Fields + +| Name | Type | Description | +| -------------------------------------- | ------ | -------------------------------------------------------------------------------- | +| `organization.name` | string | Full organization name as on the incorporation | +| `organization.VAT_number` | string | Organization VAT number | +| `organization.registration_number` | string | Organization registration | +| `organization.registration_date` | string | Date the organization was registered | +| `organization.registered_address` | string | Organization registered address | +| `organization.number_of_shareholders` | number | Organization shareholder number | +| `organization.shareholder_name` | string | Can be an organization or a person | +| `organization.photo_incorporation_doc` | binary | Image of incorporation documents | +| `organization.photo_proof_address` | binary | Image of a utility bill, bank statement with the organization's name and address | +| `organization.address_country_code` | string | country code for current address | +| `organization.state_or_province` | string | name of state/province/region/prefecture | +| `organization.city` | string | name of city/town | +| `organization.postal_code` | string | Postal or other code identifying organization's locale | +| `organization.director_name` | string | Organization registered managing director | +| `organization.website` | string | Organization website | +| `organization.email` | string | Organization contact email | +| `organization.phone` | string | Organization contact phone | + +## Addresses + +Address formatting varies widely from country to country and even within each country. See +[here](https://stackoverflow.com/questions/11160192/how-to-parse-freeform-street-postal-address-out-of-text-and-into-components) +for details. Rather than attempting to create a field for each possible part of an address in every country, this +protocol takes a middle of the road approach. Address fields that are fairly universal can be encoded with the +`country_code`, `state_or_province`, `city`, and `postal_code` fields. Full addresses, however, should be encoded as a +single multi-line string in the `address` field. This allows any address in the world to be represented with a limited +number of fields. If address parsing is necessary, parsing will be easier since the country, city, and postal code are +already separate fields. ## Changelog -* `v1.11.0`: Add `bank_account_type` for describing types of bank accounts. ([#1344](https://github.com/stellar/stellar-protocol/pull/1344)) -* `v1.10.0`: Remove `cvu_number`, update `cbu_number` to also accept CVU numbers, and add `cbu_alias` to Natural Person KYC fields ([#1339](https://github.com/stellar/stellar-protocol/pull/1339)) -* `v1.9.0`: Add `cbu_number` and `cvu_number` to Natural Person KYC fields ([#1338](https://github.com/stellar/stellar-protocol/pull/1338)) -* `v1.8.0`: Add `proof_of_liveness` to Natural Person KYC field ([#1323](https://github.com/stellar/stellar-protocol/pull/1323)). -* `v1.7.0`: Add `proof_of_income` to Natural Person KYC fields ([#1310](https://github.com/stellar/stellar-protocol/pull/1310)). -* `v1.6.0`: Add `clabe_number` to Natural Person KYC fields ([#1202](https://github.com/stellar/stellar-protocol/pull/1202)). +- `v1.12.0`: Define financial account fields section. ([#1367](https://github.com/stellar/stellar-protocol/pull/1367)) +- `v1.11.0`: Add `bank_account_type` for describing types of bank accounts. + ([#1344](https://github.com/stellar/stellar-protocol/pull/1344)) +- `v1.10.0`: Remove `cvu_number`, update `cbu_number` to also accept CVU numbers, and add `cbu_alias` to Natural Person + KYC fields ([#1339](https://github.com/stellar/stellar-protocol/pull/1339)) +- `v1.9.0`: Add `cbu_number` and `cvu_number` to Natural Person KYC fields + ([#1338](https://github.com/stellar/stellar-protocol/pull/1338)) +- `v1.8.0`: Add `proof_of_liveness` to Natural Person KYC field + ([#1323](https://github.com/stellar/stellar-protocol/pull/1323)). +- `v1.7.0`: Add `proof_of_income` to Natural Person KYC fields + ([#1310](https://github.com/stellar/stellar-protocol/pull/1310)). +- `v1.6.0`: Add `clabe_number` to Natural Person KYC fields + ([#1202](https://github.com/stellar/stellar-protocol/pull/1202)).