sep-0009.md

Preamble

SEP: 0009
Title: Standard KYC Fields
Author: stellar.org
Status: Active
Created: 2018-07-27
Updated: 2024-04-22
Version 1.17.0

Simple Summary

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 application.

Encodings

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
country	3	ISO 3166-1 alpha-3
date	10	ISO 8601 date-only format
phone number	varies	E.164
occupation	3	ISCO08

Field Naming Conventions

Where possible we use field names from schema.org. 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:

{
  "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.

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 unless specified differently on mobile_number_format field. It could be hashed in case mobile_number_format is defined as hash
mobile_number_format	string	Expected format of the mobile_number field. E.g.: E.164, hash, etc... In case this field is not specified, receiver should assume it's 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
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
referral_id	string	User's origin (such as an id in another application) or a referral code

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_account_number	string	Number identifying bank account
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
external_transfer_memo	string	A destination tag/memo used to identify a transaction
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).
crypto_address	string	Address for a cryptocurrency account
crypto_memo	string	(deprecated, use external_transfer_memo instead) A destination tag/memo used to identify a transaction

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 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.

Card fields

To pass card (such as credit card) details to the application, the client should pass card details via an object defined below. Note, that it's possible to either pass card details to the application, or the token, representing the card. This token may be fetched from a third-party source prior, for example, it can be a Stripe token, or any other service offering similar functionality may be used. When token is used, application should notify clients about the type of the token that it is expecting to receive. Usually, application would require either token, or set of: number, expiration_date, cvc and holder_name to be provided, but some applications may require extra fields.

Name	Type	Description
card.number	string	Card number
card.expiration_date	date	Expiration month and year in YY-MM format (e.g. 29-11, November 2029)
card.cvc	string	CVC number (Digits on the back of the card)
card.holder_name	string	Name of the card holder
card.network	string	Brand of the card/network it operates within (e.g. Visa, Mastercard, AmEx, etc.)
card.postal_code	string	Billing address postal code
card.country_code	string	Billing address country code in ISO 3166-1 alpha-2 code (e.g. US)
card.state_or_province	string	Name of state/province/region/prefecture is ISO 3166-2 format
card.city	string	Name of city/town
card.address	string	Entire address (country, state, postal code, street address, etc...) as a multi-line string
card.token	string	Token representation of the card in some external payment system (e.g. Stripe)

Changelog

• v1.17.0: Add mobile_number_format field to Natural Person Fields (#1481).
• v1.16.0: Add external_transfer_memo field to Financial Account Fields (#1452).
• v1.15.0: Add fields for card details (#1430).
• v1.14.0: Add referral_id field (#1418).
• v1.13.0: Add crypto related fields to financial account fields section. (#1382)
• v1.12.0: Define financial account fields section. (#1367)
• v1.11.0: Add bank_account_type for describing types of bank accounts. (#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)
• v1.9.0: Add cbu_number and cvu_number to Natural Person KYC fields (#1338)
• v1.8.0: Add proof_of_liveness to Natural Person KYC field (#1323).
• v1.7.0: Add proof_of_income to Natural Person KYC fields (#1310).
• v1.6.0: Add clabe_number to Natural Person KYC fields (#1202).