PUT
/
v2.01
/
{ClientId}
/
sca
/
users
/
natural
/
{UserId}
{
    "UserCategory": "PAYER",
    "TermsAndConditionsAccepted": false,
    "Tag": "New tag"
}

{
    "FirstName": "Alex",
    "LastName": "Smith",
    "Birthday": null,
    "Nationality": null,
    "CountryOfResidence": null,
    "Occupation": null,
    "IncomeRange": null,
    "ProofOfIdentity": null,
    "ProofOfAddress": null,
    "Capacity": "NORMAL",
    "PhoneNumber": null,
    "PhoneNumberCountry": null,
    "Address": {
        "AddressLine1": "3 rue de la Cité",
        "AddressLine2": "Appartement 7",
        "City": "Paris",
        "Region": "Île-de-France",
        "PostalCode": "75004",
        "Country": "FR"
    },
    "PendingUserAction": null,
    "Id": "user_m_01JF7AP1M46TR0JH7WBGPWK7D7",
    "Tag": "New tag",
    "CreationDate": 1734339135,
    "PersonType": "NATURAL",
    "Email": "alex.smith@example.com",
    "KYCLevel": "LIGHT",
    "TermsAndConditionsAccepted": false,
    "TermsAndConditionsAcceptedDate": null,
    "UserCategory": "PAYER",
    "UserStatus": "ACTIVE"
}

Caution – Modification may trigger SCA re-enrollment

If UserCategory is OWNER, modifying the following values changes UserStatus to PENDING_USER_ACTION and requires re-enrollment in SCA using the returned PendingUserAction.RedirectUrl:

  • Email
  • PhoneNumber
  • PhoneNumberCountry

Caution – Modification may cause KYC/B verification downgrade

If KYCLevel is REGULAR, modifying the following values triggers a verification downgrade to LIGHT:

  • FirstName
  • LastName
  • Birthday
  • Nationality

Note – Country-based restrictions apply to users

Due to Mangopay’s country restrictions, it is not possible to use blocked countries as the following:

  • Nationality
  • CountryOfResidence
  • Address.Country

​
Body parameters

​
TermsAndConditionsAccepted
boolean
required

Whether the user has accepted Mangopay’s terms and conditions (as defined by your contract, see the T&Cs guide for details).

Must be true if UserCategory is OWNER.

​
FirstName
string

Min. length: 1; max. length: 100

The first name of the individual.

​
LastName
string

Min. length: 1; max. length: 100

The last name of the individual.

​
Birthday
timestamp

Required if UserCategory is OWNER. Returned null if UserCategory is PAYER.

The date of birth of the individual.

Note: This is a Unix timestamp in UTC. Ensure you convert your timezone to UTC to avoid midnight being interpreted as the day before.

​
Nationality
string

Format: Two-letter country code (ISO 3166-1 alpha-2 format)

Required if UserCategory is OWNER. Returned null if UserCategory is PAYER.

The nationality of the individual.

​
CountryOfResidence
string

Format: Two-letter country code (ISO 3166-1 alpha-2 format)

Required if UserCategory is OWNER. Returned null if UserCategory is PAYER.

The country of residence of the individual.

​
Occupation
string

Max. length: 255 characters

Returned null if UserCategory is PAYER.

The occupation of the individual.

​
IncomeRange
integer

Allowed values: 1, 2, 3, 4, 5, 6

Returned null if UserCategory is PAYER.

The bracket indicating the income of the individual. The brackets are:

  • 1: < 18K
  • 2: 18K - 30K
  • 3: 30K - 50K
  • 4: 50K - 80K
  • 5: 80K - 120K
  • 6: > 120K
​
Tag
string

Max. length: 255 characters

Custom data that you can add to this object.

​
Email
string

Format: A valid email address

The individual’s email address.

Caution: If UserCategory is OWNER, modifying this value means the user will be required to re-enroll the new value in SCA via the PendingUserAction.RedirectUrl. For more details see the SCA guides.

​
PhoneNumber
string

Format: International E.164 standard (prefixed by plus sign and country code) or local format

The individual’s phone number. The local format (recommended) requires PhoneNumberCountry to ensure correct formatting.

If present, the phone number forms part of card transaction data that is passed to issuers to improve authentication rates.

For users with UserCategory OWNER , the phone number is used to pre-populate the SCA session for them to confirm and receive an SMS OTP. If the individual modifies the phone number during the session, this data is not updated in the API.

​
PhoneNumberCountry
string

Format: Two-letter country code (ISO 3166-1 alpha-2 format)

Required if the PhoneNumber is provided in local format (recommended), to render the value in the E.164 standard.

​
Address
object

The postal address of the user.

​
Responses

{
    "FirstName": "Alex",
    "LastName": "Smith",
    "Birthday": null,
    "Nationality": null,
    "CountryOfResidence": null,
    "Occupation": null,
    "IncomeRange": null,
    "ProofOfIdentity": null,
    "ProofOfAddress": null,
    "Capacity": "NORMAL",
    "PhoneNumber": null,
    "PhoneNumberCountry": null,
    "Address": {
        "AddressLine1": "3 rue de la Cité",
        "AddressLine2": "Appartement 7",
        "City": "Paris",
        "Region": "Île-de-France",
        "PostalCode": "75004",
        "Country": "FR"
    },
    "PendingUserAction": null,
    "Id": "user_m_01JF7AP1M46TR0JH7WBGPWK7D7",
    "Tag": "New tag",
    "CreationDate": 1734339135,
    "PersonType": "NATURAL",
    "Email": "alex.smith@example.com",
    "KYCLevel": "LIGHT",
    "TermsAndConditionsAccepted": false,
    "TermsAndConditionsAcceptedDate": null,
    "UserCategory": "PAYER",
    "UserStatus": "ACTIVE"
}

{
    "UserCategory": "PAYER",
    "TermsAndConditionsAccepted": false,
    "Tag": "New tag"
}

Was this page helpful?

Create a Natural User (SCA)Categorize a Natural User