MPS is strengthening the data it collects to complete the KYC (natural persons) and KYB (legal persons) of your users, and to secure sensitive actions with Strong Customer Authentication (SCA).
The fields listed on this page are optional today. A future release will make them mandatory. In the API reference, they are flagged with a red soon required label.
Nothing changes for your integration todayAll the fields below are already accepted by the API. Calls that do not send them keep working exactly as before. A dedicated changelog entry will announce the switch. We recommend sending these fields now so that the switch is transparent for you.
How to read this page
| Label | Meaning |
|---|---|
| Soon required | Optional today, will always be mandatory. |
| Soon required if … | Optional today, will be mandatory when the condition is met. |
| Required if … | Conditional rule already in force today. Listed here because it applies to fields that become mandatory. |
1. Person data (KYC / KYB)
Endpoints concerned
| Endpoint | Operation | Where the fields go |
|---|---|---|
POST /platforms/{platformUUID}/users | User creation | person object |
POST /platforms/{platformUUID}/users/USERUUID | User update | person object |
POST /platforms/{platformUUID}/users/USERUUID/persons | Create persons | each item of persons |
POST /platforms/{platformUUID}/users/USERUUID/persons/{personUUID} | Person update | request body |
Once the change is live, these fields will be required to complete the user's KYC/KYB and to validate the user's wallet.
1.1 Fields for all persons (natural and legal)
| Field | Type | Rule |
|---|---|---|
country_of_origin | string (ISO 3166-1 alpha-2) | Soon required |
annual_revenue | enum | Soon required |
financial_capacity | enum | Soon required |
source_of_funds | enum | Soon required |
origin_of_funds_other | string | Soon required if source_of_funds is other_or_not_disclosed |
is_intermediated_by_third_party | boolean | Soon required |
Accepted values
annual_revenue- Natural:
natural_inf_30000,natural_30001_50000,natural_50001_75000,natural_75001_100000,natural_100001_150000,natural_sup_150000 - Legal:
legal_inf_100000,legal_100001_500000,legal_500001_2000000,legal_2000001_10000000,legal_10000001_50000000,legal_sup_50000000
- Natural:
financial_capacity- Natural:
natural_inf_50000,natural_50001_100000,natural_100001_250000,natural_250001_500000,natural_500001_1000000,natural_sup_1000000 - Legal:
legal_inf_50000,legal_50001_250000,legal_250001_1000000,legal_1000001_5000000,legal_5000001_20000000,legal_sup_20000000
- Natural:
source_of_funds:salary_or_professional_income,personal_savings_or_available_funds,capital_income,asset_sale,inheritance_or_donation,external_financing,capital_contribution_or_fundraising,other_or_not_disclosed
1.2 Address (address object)
address object)| Field | Type | Rule |
|---|---|---|
number | string | Soon required |
road_type | string | Soon required |
road_name | string (max 255) | Soon required |
Already required todayWhen an
addressobject is sent,city,postal_codeandcountryare already required, andregionis required ifcountryisUS,CAorMX.
1.3 Tax residence
A person can declare up to three tax countries (suffixes _1, _2, _3). The first one becomes mandatory.
| Field | Type | Rule |
|---|---|---|
tax_country_code_1 | string (ISO 3166-1 alpha-2) | Soon required |
tin_code_1 | string | Soon required |
no_tin_reason_1 | string | Natural: soon required, only if tin_code_1 is empty. Legal: required if tax_country_code_1 is set and tin_code_1 is empty |
is_primary_1 | boolean | Soon required |
Rules already in force today for the second and third tax countries (n = 2 or 3):
tax_country_code_nis required iftin_code_n,no_tin_reason_noris_primary_nis set.tin_code_nis required iftax_country_code_nis set andno_tin_reason_nis empty.no_tin_reason_nis required iftax_country_code_nis set andtin_code_nis empty.- Only one tax country can be flagged as primary.
1.4 Natural persons only (Persons::Natural)
Persons::Natural)| Field | Type | Rule |
|---|---|---|
birth_city | string | Soon required |
birth_province | enum | Soon required if country_of_origin is US, CA or MX |
civility | enum | Soon required |
phone_number | string | Soon required |
professional_situation | string | Soon required |
user_signatory | boolean | Soon required |
fatca_crs_data.us_citizen_or_resident | boolean | Soon required |
Roles inside a legal person (role_data object)
| Field | Type | Rule |
|---|---|---|
role_data.roles | array | Soon required |
role_data.ubo_prct | number | Soon required if roles contains ubo |
role_data.ubo_by_control | boolean | Soon required if roles contains ubo |
role_data.ubo_is_indirect | boolean | Soon required if roles contains ubo |
UBO rules already in force today
- A UBO must hold at least 25% (
ubo_prct) or be UBO by control (ubo_by_control: true).- The total of
ubo_prctacross the persons of a user cannot exceed 100.ubo_prctorubo_by_controlcannot be sent for a person who does not have theuborole.
1.5 Legal persons only (Persons::Legal)
Persons::Legal)| Field | Type | Rule |
|---|---|---|
legal_classification_code | string | Soon required |
activity_classification_code | string | Soon required |
registration_date | date | Soon required |
registration_number | string | Soon required |
siret | string | Soon required if category is 0 (solo proprietor) or 1 (company) |
rna | string | Soon required if category is 2 (association) |
FATCA / CRS classification (fatca_crs_data object)
| Field | Type | Rule |
|---|---|---|
us_legal_us_person | boolean | Soon required |
is_fatca_fi | boolean | Soon required |
is_registered_fatca_fi | boolean | Soon required if is_fatca_fi is true |
giin | string | Soon required if is_registered_fatca_fi is true |
is_nffe_fatca_active | boolean | Soon required |
is_nffe_fatca_passive | boolean | Soon required |
is_crs_fi | boolean | Soon required |
is_nffe_crs | boolean | Soon required |
Send real JSON booleans
fatca_crs_databooleans must be sent astrue/false, not as strings ("true") or numbers (1). Other types are rejected today.
1.6 Example — natural person update
POST /platforms/{platformUUID}/users/USERUUID/persons/{personUUID}
{
"country_of_origin": "FR",
"annual_revenue": "natural_30001_50000",
"financial_capacity": "natural_50001_100000",
"source_of_funds": "salary_or_professional_income",
"is_intermediated_by_third_party": false,
"tax_country_code_1": "FR",
"tin_code_1": "1234567890",
"is_primary_1": true,
"birth_city": "Paris",
"civility": "mrs",
"phone_number": "+33607080910",
"professional_situation": "21E5",
"fatca_crs_data": {
"us_citizen_or_resident": false
}
}2. Strong Customer Authentication (SCA) context
MPS is rolling out SCA on sensitive actions. Today the SCA context is accepted but not enforced: a missing or invalid context is recorded but does not block the call.
| Endpoint | How to send the SCA context |
|---|---|
POST /platforms/{platformUUID}/users/USERUUID/external_accounts | context object in the body |
POST /platforms/{platformUUID}/users/USERUUID/external_accounts/{uuid} | context object in the body |
POST /platforms/{platformUUID}/users/USERUUID/external_accounts/{uuid}/deactivate | context object in the body |
POST /platforms/{platformUUID}/pay_outs | context object in the body |
POST /platforms/{platformUUID}/users/USERUUID/strong_auth/reset/{factor} | context object in the body |
GET /platforms/{platformUUID}/users/USERUUID/accounts/{uuid} | X-SCA-Context header |
The consent token placed in the context is obtained with POST /platforms/{platformUUID}/users/USERUUID/strong_auth/secret_code/verify, by sending the optional authentication_data object (reason + details) that describes the action to authorize.
What will change when SCA is enforced
- The
contextfield (or theX-SCA-Contextheader) will become required on the endpoints above.- A missing or invalid SCA context will return
401 Unauthorized.
The full flow, the supported reasons and their required details are described in the Strong Customer Authentication guide.