Create a Legal User (SCA)

Note – SCA triggered for Owners

If UserCategory is OWNER, this endpoint triggers SCA enrollment.

Your platform needs to use the returned PendingUserAction.RedirectUrl (and add an encoded returnUrl query parameter) to redirect the user so they can enroll. Read more about how to redirect them in the SCA session guide.

The RedirectUrl is currently only returned if LegalPersonType is SOLETRADER, but the endpoint should be integrated for the other types.

Note – Country-based restrictions apply to users

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

HeadquartersAddress.Country
LegalRepresentative.Nationality
LegalRepresentative.CountryOfResidence
LegalRepresentativeAddress.Country

Body parameters

Name

string

required

Max. length: 255 characters

The registered legal name of the entity. The Name value should be the one registered with the relevant national authority.

LegalPersonType

string

required

Allowed values: BUSINESS, PARTNERSHIP, ORGANIZATION, SOLETRADER

The type of legal user. For information on which LegalPersonType to use for a particular local legal structure, see the verification requirements.

Caution: Modification of the LegalPersonType may result in a verification downgrade.

LegalRepresentative

object

required

Information about the legal representative declared for the user.

Show properties

FirstName

string

required

Min. length: 1; max. length: 100

The first name of the individual.

LastName

string

required

Min. length: 1; max. length: 100

The last name of the individual.

Birthday

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

string

Format: A valid email address

Required if UserCategory is OWNER for SCA to build a behavioral biometrics profile and as a backup communication channel. Returned null if UserCategory is PAYER.

The individual’s email address.

PhoneNumber

string

Format: International E.164 standard (preceded 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.

CompanyNumber

string

Required if UserCategory is OWNER and LegalPersonType is BUSINESS. Returned null if UserCategory is PAYER.

The registration number of the entity, assigned by the relevant national authority. For information on the expected format for a specific country, see the Company number guide. To validate the format of a number before submitting documents for verification, use POST Validate the format of User data.

HeadquartersAddress

object

Required if UserCategory is OWNER. Child parameters returned null if UserCategory is PAYER.

The legally registered address of the entity’s administrative center.

Show properties

AddressLine1

string

required

Max. length: 255 characters

The first line of the address.

AddressLine2

string

Max. length: 255 characters

The second line of the address.

City

string

required

Max. length: 255 characters

The city of the address.

Region

string

Max. length: 255 characters

Required if Country is US, CA, or MX.

The region of the address.

PostalCode

string

required

Max. length: 255 characters

The postal code of the address. The postal code can contain the following characters: alphanumeric, dashes, and spaces.

Country

string

required

The country of the address.

LegalRepresentativeAddress

object

The address of the entity’s legal representative.

Show properties

AddressLine1

string

required

Max. length: 255 characters

The first line of the address.

AddressLine2

string

Max. length: 255 characters

The second line of the address.

City

string

required

Max. length: 255 characters

The city of the address.

Region

string

Max. length: 255 characters

Required if Country is US, CA, or MX.

The region of the address.

PostalCode

string

required

Max. length: 255 characters

The postal code of the address. The postal code can contain the following characters: alphanumeric, dashes, and spaces.

Country

string

required

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

The country of the address.

Tag

string

Max. length: 255 characters

Custom data that you can add to this object.

string

required

Format: A valid email address

The email address for the entity.

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.

UserCategory

string

required

Allowed values: PAYER, OWNER

The category of the user:

PAYER – User who can only make pay-ins to their wallets and transfers to other wallets (as well as refunds for pay-ins and transfers).
OWNER – User who can also receive transfers to their wallets. Owners are able to request KYC verification, which if successful gives them the KYCLevel of REGULAR and the ability to request payouts.

Responses

200

400 - First name or last name identified as fake

{
    "Message": "The data you provided does not comply with our anti-fraud policy",
    "Type": "fraud_policy",
    "Id": "51876239-4814-422e-8f4b-6986520414bb#1750420019",
    "Date": 1750420020,
    "errors": null
}

Read more about Mangopay’s AML rule preventing fake names →

400 - Restricted country

{
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Id": "733c8dbc-2770-4cc4-80d4-63d684cff38c#1750669115",
    "Date": 1750669116,
    "errors": {
        "HeadquartersAddress.Country": "The HeadquartersAddress.Country used is blocked"
    }
}

Read more about country restrictions →

400 - Invalid email

{
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Id": "864a164a-cbb9-4e9d-b140-2b83c720e729",
    "Date": 1690291065.0,
    "errors": {
        "LegalRepresentative.Email": "The field Email must match the regular expression '([a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*)@(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?'."
    }
}

400 - LegalRepresentative.Email required if OWNER

{
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Id": "c55c3a1e-b581-414b-97be-4c8915127f3b",
    "Date": 1751881331.0,
    "errors": {
        "LegalRepresentative.Email": "'Email' must not be empty."
    }
}

403 - TermsAndConditionsAccepted must be true if OWNER

{
  "Message": "User must accept the terms and conditions before account creation or modification.",
  "Type": "user_hasnt_accepted_terms_and_conditions",
  "Id": "dbbc752b-6f9f-4248-a4bb-04ee0ba7b4b7",
  "Date": 1730810728,
  "errors": null
}

{
    "Name": "Alex Smith",
    "LegalPersonType": "SOLETRADER",
    "LegalRepresentative": {
        "FirstName": "Alex",
        "LastName": "Smith",
        "ProofOfIdentity": null,
        "Birthday": null,
        "Nationality": null,
        "CountryOfResidence": null,
        "Email": "alex.smith@example.com",
        "PhoneNumber": "0611111111",
        "PhoneNumberCountry": "FR"
    },
    "ProofOfRegistration": null,
    "ShareholderDeclaration": null,
    "Statute": null,
    "CompanyNumber": null,
    "PendingUserAction": null,
    "HeadquartersAddress": {
        "AddressLine1": null,
        "AddressLine2": null,
        "City": null,
        "Region": null,
        "PostalCode": null,
        "Country": null
    },
    "LegalRepresentativeAddress": {
        "AddressLine1": "3 rue de la Cité",
        "AddressLine2": "Appartement 7",
        "City": "Paris",
        "Region": "Île-de-France",
        "PostalCode": "75004",
        "Country": "FR"
    },
    "Id": "user_m_01JF7FKVP51PS3TYKCN79VZZ8M",
    "Tag": "Created using the Mangopay API Postman collection",
    "CreationDate": 1734344306,
    "PersonType": "LEGAL",
    "Email": "alex.smith.services@example.com",
    "KYCLevel": "LIGHT",
    "TermsAndConditionsAccepted": false,
    "TermsAndConditionsAcceptedDate": null,
    "UserCategory": "PAYER",
    "UserStatus": "ACTIVE"
}

{
    "UserCategory": "PAYER",
    "TermsAndConditionsAccepted": false,
    "LegalPersonType": "SOLETRADER",
    "Name": "Alex Smith",
    "Email": "alex.smith.services@example.com",
    "LegalRepresentative": {
        "FirstName": "Alex",
        "LastName": "Smith",
        "Email": "alex.smith@example.com",
        "PhoneNumber": "0611111111",
        "PhoneNumberCountry": "FR"
    },
    "LegalRepresentativeAddress": {
        "AddressLine1": "3 rue de la Cité",
        "AddressLine2": "Appartement 7",
        "City": "Paris",
        "Region": "Île-de-France",
        "PostalCode": "75004",
        "Country": "FR"
    },
    "Tag": "Created using the Mangopay API Postman collection"
}

Overview

User management

User verification

Wallets

Cards

Card pay-ins

Banking pay-ins

APM pay-ins

Transfers

Refunds

Disputes

Payouts

FX conversions

Transactions

Echo

Helpers

Platform account

Create a Legal User (SCA)

Body parameters

Responses

Overview

User management

User verification

Wallets

Cards

Card pay-ins

Banking pay-ins

APM pay-ins

Transfers

Refunds

Disputes

Payouts

FX conversions

Transactions

Echo

Helpers

Platform account

​Body parameters

​Responses

Body parameters

Responses