User creation and authentication flows

Creating personal profiles for clients

When clients transfer money their details are validated in the Wise backend using the email address they provide in the application where they enter their details. A process is started in Mambu Process Orchestrator (MPO) to create a user and personal profile for clients that have never had an account created in Wise.

EntryPoint_Personal_Business_User_Profile

The 2.1. [EntryPoint] PERSONAL/BUSINESS User&profile creation process handles this business flow.

Steps to create a personal profile:

Create the user
Create the personal profile
Optional: Create the profile address
Optional: Create the identification document

Process payload

{
     "clientAddress": {
          "country": "RO",
          "city": "Iasi",
          "postCode": "700625",
          "firstLine": "Str.Palat nr.1"
     },
     "clientEmail": "clientemail@email.com",
     "clientFirstName": "John",
     "clientLastName": "Smith",
     "dateOfBirth": "1986-01-01",
     "debtorIBAN": "RO66BACX0000001234567890",
     "detailReference": "The details of this transfer go here",
     "phoneNumber": "+40756765765",
     "identificationDocument": {
          "firstName": "John",
          "lastName": "Smith",
          "type": "IDENTITY_CARD",
          "uniqueIdentifier": "AB1234567",
          "issueDate": "2017-12-31",
          "issuerCountry": "RO",
          "issuerState": "Iasi",
          "expiryDate": "2027-12-31"
     },
     "legalType": "Private",
     "type": "personal",
     "registrationCode":"93233760391469228235708877179491"
}

Parameter	Type	Description	Required
`clientAddress`	object	A JSON object holding the client’s address details.	No
`clientAddress.country`	string	The two letter country code for the address.	No
`clientAddress.city`	string	The name of the city of the address.	No
`clientAddress.postcode`	string	The postcode of the address.	No
`clientAddress.firstLine`	string	The first line of the address.	No
`clientEmail`	string	The client’s email address, which is used to validate the user in the Wise backend.	Yes
`clientFirstName`	string	The client’s first name.	Yes
`clientLastName`	string	The client’s last name.	Yes
`dateOfBirth`	string	The client’s birth date in the format YYYY-MM-DD.	Yes
`debtorIBAN`	string	The client’s IBAN number.	Yes
`detailReference`	string	The details of the transfer.	Yes
`phoneNumber`	string	The client’s phone number, including the country calling code.	Yes
`identificationDocument`	object	A JSON object holding the details of the client’s identification document.	No
`identificationDocument.firstName`	string	The client’s first name in the identification document.	No
`identificationDocument.lastName`	string	The client’s last name in the identification document.	No
`identificationDocument.type`	string	The identification document type: for example, `IDENITY_CARD` or `PASSPORT`	No
`identificationDocument.uniqueIdentifier`	string	The client’s first name in the identification document.	No
`identificationDocument.issueDate`	string	The date when the identification document was issued in the format YYYY-MM-DD.	No
`identificationDocument.issuerCountry`	string	The two letter country code for the country that issued the identification document.	No
`identificationDocument.issuerState`	string	Where this is available, the state, province, district, or region that issued the identification document.	No
`identificationDocument.expiryDate`	string	The date when the identification document will expire in the format YYYY-MM-DD.	No
`legalType`	string	The type of legal entity. This may be `Private` or `Business`.	No
`type`	string	Keep this value `personal`.	Yes
`registrationCode`	string	A unique text code sent by the client. When the `registrationCode` is sent, the value is used in the `[1. Create new user in TW or redirect to login page]` process - instead of automatically generate a new registration code. Please apply the same security standards to handling the registration code as you would for a password. The `registrationCode` must be unique and be at least 32 characters long.	Yes

Invalid token

If the token sent is invalid when a POST call is made to the v1/user/signup/registration_code endpoint in Wise, Wise will send one of the following HTTP codes: 401 Unauthorized or 403 Forbidden with the error message tag invalid_token.

A new token is generated by calling the Wise Retry Mechanism process, which updates the existing token stored in the Wise config state diagram under the TWconfiguration parameter. The expiry time of newly generated token, under the refreshDelay parameter, is stored in a second state diagram in Wise config with references under the twTokenRefresh parameter.

Creating personal profiles for existing clients

You can create personal profiles for existing clients. One client cannot have multiple active personal profiles, as creating duplicate profiles will return an error.

Personal Profile Creation

The 2.1.2 [EntryPoint] Personal user profile creation process handles this business flow.

Process payload

{
     "clientAddress": {
          "country": "RO",
          "city": "Iasi",
          "postCode": "700625",
          "firstLine": "Str.Palat nr.1"
     },
     "clientFirstName": "Sam",
     "clientLastName": "Smith",
     "dateOfBirth": "1987-01-10",
     "phoneNumber": "+31649256509",
     "identificationDocument": {
          "firstName": "John",
          "lastName": "SmithSr",
          "type": "IDENTITY_CARD",
          "uniqueIdentifier": "AA299822313",
          "issueDate": "2017-12-31",
          "issuerCountry": "RO",
          "issuerState": "Iasi",
          "expiryDate": "2027-12-31"
     },
     "token": "0f94cb3f-bc16-4fd8-9533-8367fa5ff1c4"
}

Parameter	Type	Description	Required
`clientAddress`	object	A JSON object holding the client’s address details.	No
`clientAddress.country`	string	The two letter country code for the address.	No
`clientAddress.city`	string	The name of the city of the address.	No
`clientAddress.postcode`	string	The postcode of the address.	No
`clientAddress.firstLine`	string	The first line of the address.	No
`clientFirstName`	string	The client’s first name.	Yes
`clientLastName`	string	The client’s last name.	Yes
`dateOfBirth`	string	The client’s birth date in the format YYYY-MM-DD.	Yes
`phoneNumber`	string	The client’s phone number, including the country calling code.	Yes
`identificationDocument`	object	A JSON object holding the details of the client’s identification document.	No
`identificationDocument.firstName`	string	The client’s first name in the identification document.	No
`identificationDocument.lastName`	string	The client’s last name in the identification document.	No
`identificationDocument.type`	string	The identification document type: for example, `IDENITY_CARD` or `PASSPORT`	No
`identificationDocument.uniqueIdentifier`	string	The client’s first name in the identification document.	No
`identificationDocument.issueDate`	string	The date when the identification document was issued in the format YYYY-MM-DD.	No
`identificationDocument.issuerCountry`	string	The two letter country code for the country that issued the identification document.	No
`identificationDocument.issuerState`	string	Where this is available, the state, province, district, or region that issued the identification document.	No
`identificationDocument.expiryDate`	string	The date when the identification document will expire in the format YYYY-MM-DD.	No
`token`	string	The client’s token, which is retrieved in the user creation and login process.	Yes

Update a client’s personal profile

If the client’s personal profile has been verified, there are restrictions on what information can be changed. We recommended that you use the update window to update data.

Update Profile

The 2.1.3. [EntryPoint] Update user profile process handles this business flow.

Process payload

{
   "profileId": "16341931",
   "type": "personal",
   "clientFirstName": "Sam",
   "clientLastName": "Smith",
   "dateOfBirth": "1987-01-10",
   "phoneNumber": "+31649256509",
   "clientAddress": {
      "country": "RO",
      "city": "Iasi",
      "postCode": "700625",
      "firstLine": "Str.Palat nr.1"
  },
  "identificationDocument": {
      "firstName": "John",
      "lastName": "SmithSr",
      "type": "IDENTITY_CARD",
      "uniqueIdentifier": "AA299822313",
      "issueDate": "2017-12-31",
      "issuerCountry": "RO",
      "issuerState": "Iasi",
      "expiryDate": "2027-12-31"
  },
   "token": "0f94cb3f-bc16-4fd8-9533-8367fa5ff1c4"
}

Parameter	Type	Description	Required
`profileId`	string	The client’s profile ID, which is retrieved in the user creation and login process.	Yes
`type`	string	Keep this value `personal`.	Yes
`clientFirstName`	string	The client’s first name.	Yes
`clientLastName`	string	The client’s last name.	Yes
`dateOfBirth`	string	The client’s birth date in the format YYYY-MM-DD.	Yes
`phoneNumber`	string	The client’s phone number, including the country calling code.	Yes
`clientAddress`	object	A JSON object holding the client’s address details.	No
`clientAddress.country`	string	The two letter country code for the address.	No
`clientAddress.city`	string	The name of the city of the address.	No
`clientAddress.postcode`	string	The postcode of the address.	No
`clientAddress.firstLine`	string	The first line of the address.	No
`identificationDocument`	object	A JSON object holding the details of the client’s identification document.	No
`identificationDocument.firstName`	string	The client’s first name in the identification document.	No
`identificationDocument.lastName`	string	The client’s last name in the identification document.	No
`identificationDocument.type`	string	The identification document type: for example, `IDENITY_CARD` or `PASSPORT`	No
`identificationDocument.uniqueIdentifier`	string	The client’s first name in the identification document.	No
`identificationDocument.issueDate`	string	The date when the identification document was issued in the format YYYY-MM-DD.	No
`identificationDocument.issuerCountry`	string	The two letter country code for the country that issued the identification document.	No
`identificationDocument.issuerState`	string	Where this is available, the state, province, district, or region that issued the identification document.	No
`identificationDocument.expiryDate`	string	The date when the identification document will expire in the format YYYY-MM-DD.	No
`token`	string	The client’s token, which is retrieved in the user creation and login process.	Yes

Creating a business profile

In order for a client to create a business profile, they need to have an existing personal profile. Steps to create a personal and business profile:

Create the user
Optional: Create the business profile
Optional: Create the business profile’s addresses
Optional: Add the business directors' details
Optional: Add the business’s ultimate beneficial owners details

The 2.1. [EntryPoint] PERSONAL/BUSINESS User & profile creation process handles this business flow.

Process payload

{
    "name": "Jassi Wealth",
    "businessCategory": "Financial Services",
    "businessSubCategory": "Investment",
    "companyType": "Other",
    "descriptionOfBusiness": "Jassi Wealth is a boutique investment firm that caters to high net-worth indivuduals in Iasi, Romania.",
    "registrationNumber": "12345678",
    "businessAddress": {
        "country": "RO",
        "city": "Iasi",
        "postCode": "700625",
        "firstLine": "Str.Xulescu nr.3"
    },
    "businessDirectors": [
        {
            "firstName": "Joe",
            "lastName": "Smith",
            "dateOfBirth": "1982-05-20",
            "countryOfResidenceIso3Code": "usa"
        },
        {
            "firstName": "James",
            "lastName": "Doe",
            "dateOfBirth": "1981-12-07",
            "countryOfResidenceIso3Code": "gbr"
        }
    ],
     "businessUltimateBeneficialOwners": [
        {
            "name": "Joe Smith",
            "dateOfBirth": "1982-05-20",
            "countryOfResidenceIso3Code": "deu",
            "addressFirstLine": "5 Karl-Liebknecht Strasse",
            "postCode": "10115",
            "ownershipPercentage": 30
        },
        {
            "name": "James Doe",
            "dateOfBirth": "1982-05-20",
            "countryOfResidenceIso3Code": "nld",
            "addressFirstLine": "55 Piet Heinkade",
            "postCode": "1019",
            "ownershipPercentage": 70
        }
    ],
    "type": "business",
    "webpage": "www.businessurl.com"
}

Parameter	Type	Description	Required
`name`	string	The name of the business.	Yes
`businessCategory`	string	The category type of the business, such as `Financial Services` or `Other`.	Yes
`businessSubCategory`	string	The subcategory type of the business, such as `Investment` or `Other`. The subcategory should be different from the category.	Yes
`companyType`	string	Allowed values: `LIMITED`, `PARTNERSHIP`, `SOLE_TRADER`, `LIMITED_BY_GUARANTEE`, `LIMITED_LIABILITY_COMPANY`,`FOR_PROFIT_CORPORATION`, `NON_PROFIT_CORPORATION`, `LIMITED_PARTNERSHIP`, `LIMITED_LIABILITY_PARTNERSHIP`, `GENERAL_PARTNERSHIP`, `SOLE_PROPRIETORSHIP`, `PRIVATE_LIMITED_COMPANY`, `PUBLIC_LIMITED_COMPANY`,`TRUST`, or `OTHER`.	Yes
`descriptionOfBusiness`	string	A short description of the what the business does.	Yes
`registrationNumber`	string	The business’s registration number.	Yes
`businessAddress`	object	A JSON object holding the business’s address details.	No
`businessAddress.country`	string	The two letter country code for the address.	No
`businessAddress.city`	string	The name of the city of the address.	No
`businessAddress.postcode`	string	The postcode of the address.	No
`businessAddress.firstLine`	string	The first line of the address.	No
`businessDirectors`	array	An array containing JSON objects for each business director’s details.	No
`businessDirectors[].firstName`	string	The first name of a business director.	No
`businessDirectors[].lastName`	string	The last name of a business director.	No
`businessDirectors[].dateOfBirth`	string	The birth date of a business director.	No
`businessDirectors[].countryOfResidenceIso3Code`	string	The three letter country code of a business director’s residence.	No
`businessUltimateBeneficialOwners`	array	An array containing JSON objects for each of the business’s ultimate beneficial owners.	No
`businessUltimateBeneficialOwners.name`	string	The full name of an ultimate beneficial owner.	No
`businessUltimateBeneficialOwners.dateOfBirth`	string	The birth date of an ultimate beneficial owner.	No
`businessUltimateBeneficialOwners.countryOfResidenceIso3Code`	string	The three letter country code of an ultimate beneficial owner’s residence.	No
`businessUltimateBeneficialOwners.firstLine`	string	The first line of an ultimate beneficial owner’s address.	No
`businessUltimateBeneficialOwners.postcode`	string	The postcode of an ultimate beneficial owner’s address.	No
`businessUltimateBeneficialOwners.ownershipPercentage`	integer	The percentage of the business owned by an ultimate beneficial owner. Must be between 0 and 100.	No
`type`	string	Keep this value `business`.	Yes
`webpage`	string	The URL of the business’s website.	Yes

Update a business profile user

If a business profile’s user has been verified, there are restrictions on what information can be changed. We recommended that you use the update window to update data.

The 2.1.3. [EntryPoint] Update user profile process handles this business flow.

Process payload

{
      "profileId": "16342006",
     "type": "business",
     "name": "Jassi Wealth",
     "businessCategory": "Financial Services",
     "businessSubCategory": "Investment",
     "companyRole": "Owner",
     "companyType": "Other",
     "descriptionOfBusiness": "Jassi Wealth is a boutique investment firm that caters to high net-worth indivuduals in Iasi, Romania.",
     "registrationNumber": "12345678",
     "webpage": "www.businessurl.com",
     "token": "0f94cb3f-bc16-4fd8-9533-8367fa5ff1c4",
     "businessAddress": {
          "country": "RO",
          "city": "Iasi",
          "postCode": "700625",
          "firstLine": "Str.Xulescu nr.3"
     },
     "businessDirectors": [
        {
            "firstName": "Joe",
            "lastName": "Smith",
            "dateOfBirth": "1982-05-20",
            "countryOfResidenceIso3Code": "usa"
        },
        {
            "firstName": "James",
            "lastName": "Doe",
            "dateOfBirth": "1981-12-07",
            "countryOfResidenceIso3Code": "gbr"
        }
    ],
     "businessUltimateBeneficialOwners": [
        {
            "name": "Joe Smith",
            "dateOfBirth": "1982-05-20",
            "countryOfResidenceIso3Code": "deu",
            "addressFirstLine": "5 Karl-Liebknecht Strasse",
            "postCode": "10115",
            "ownershipPercentage": 30
        },
        {
            "name": "James Doe",
            "dateOfBirth": "1982-05-20",
            "countryOfResidenceIso3Code": "nld",
            "addressFirstLine": "55 Piet Heinkade",
            "postCode": "1019",
            "ownershipPercentage": 70
        }
    ]
}

Parameter	Type	Description	Required
`profileId`	string	The client’s profile ID, which is retrieved in the user creation and login process.	Yes
`type`	string	Keep this value `business`.	Yes
`name`	string	The name of the business.	Yes
`businessCategory`	string	The category type of the business, such as `Financial Services` or `Other`.	Yes
`businessSubCategory`	string	The subcategory type of the business, such as `Investment` or `Other`. The subcategory should be different from the category.	Yes
`companyRole`	string	The role that the user being updated has in the business.	Yes
`companyType`	string	Allowed values: `LIMITED`, `PARTNERSHIP`, `SOLE_TRADER`, `LIMITED_BY_GUARANTEE`, `LIMITED_LIABILITY_COMPANY`,`FOR_PROFIT_CORPORATION`, `NON_PROFIT_CORPORATION`, `LIMITED_PARTNERSHIP`, `LIMITED_LIABILITY_PARTNERSHIP`, `GENERAL_PARTNERSHIP`, `SOLE_PROPRIETORSHIP`, `PRIVATE_LIMITED_COMPANY`, `PUBLIC_LIMITED_COMPANY`,`TRUST`, or `OTHER`.	Yes
`descriptionOfBusiness`	string	A short description of the what the business does.	Yes
`registrationNumber`	string	The business’s registration number.	Yes
`webpage`	string	The URL of the business’s website.	Yes
`token`	string	The client’s token, which is retrieved in the user creation and login process.	Yes
`businessAddress`	object	A JSON object holding the business’s address details.	No
`businessAddress.country`	string	The two letter country code for the address.	No
`businessAddress.city`	string	The name of the city of the address.	No
`businessAddress.postcode`	string	The postcode of the address.	No
`businessAddress.firstLine`	string	The first line of the address.	No
`businessDirectors`	array	An array containing JSON objects for each business director’s details.	No
`businessDirectors[].firstName`	string	The first name of a business director.	No
`businessDirectors[].lastName`	string	The last name of a business director.	No
`businessDirectors[].dateOfBirth`	string	The birth date of a business director.	No
`businessDirectors[].countryOfResidenceIso3Code`	string	The three letter country code of a business director’s residence.	No
`businessUltimateBeneficialOwners`	array	An array containing JSON objects for each of the business’s ultimate beneficial owners.	No
`businessUltimateBeneficialOwners.name`	string	The full name of an ultimate beneficial owner.	No
`businessUltimateBeneficialOwners.dateOfBirth`	string	The birth date of an ultimate beneficial owner.	No
`businessUltimateBeneficialOwners.countryOfResidenceIso3Code`	string	The three letter country code of an ultimate beneficial owner’s residence.	No
`businessUltimateBeneficialOwners.firstLine`	string	The first line of an ultimate beneficial owner’s address.	No
`businessUltimateBeneficialOwners.postcode`	string	The postcode of an ultimate beneficial owner’s address.	No
`businessUltimateBeneficialOwners.ownershipPercentage`	integer	The percentage of the business owned by an ultimate beneficial owner. Must be between 0 and 100.	No

Using the update window

The update window allows you to update the following profile information:

Client and business details.
Address details.
For business profiles, director and owner information and more.

Open Update Window

The 2.7. [EntryPoint] Open update window - v2 process handles this business flow.

Process payload

{
     "profileId": "14733",
     "token": "e0581691-4e43-474f-88c9-f2583027608b"
}

Parameter	Type	Description	Required
`profileId`	string	The client’s profile ID, which is retrieved in the user creation and login process.	Yes
`token`	string	The client’s token, which is retrieved in the user creation and login process.	Yes

Close the update window

This action closes the window for updating a business or personal profile.

Close Update Window

The 2.8. [EntryPoint] Close update window - v2 process handles this business flow.

Process payload

{
     "profileId": "14733",
     "token": "e0581691-4e43-474f-88c9-f2583027608b"
}

Parameter	Type	Description	Required
`profileId`	string	The client’s profile ID, which is retrieved in the user creation and login process.	Yes
`token`	string	The client’s token, which is retrieved in the user creation and login process.	Yes

Retrieving user profiles

This action allows you to get a list of profiles belonging to user.

User Profiles list

The 2.1.1 [Entry Point] Get user profiles - v1 process handles this business flow.

Process payload

{
     "token": "e0581691-4e43-474f-88c9-f2583027608b"
}

Parameter	Type	Description	Required
`token`	string	The client’s token, which is retrieved in the user creation and login process.	Yes

Retrieving account requirements

The purpose of the GET /v1/quotes/{{quoteId}}/account-requirements endpoint is to identify which fields are required to create a valid recipient for different currencies. The endpoint returns a list of required fields for creating a valid recipient account.

Account Requirements

The 3.1.1 [EntryPoint] Get account requirements - v1process handles this business flow.

Process payload

{
     "quoteId":"cc14e18d-1bf7-4f55-a350-6271bdefc485",
     "token": "e0581691-4e43-474f-88c9-f2583027608b"
}

Parameter	Type	Description	Required
`quoteId`	string	The quote ID, which is retrieved in the quote creation process.	Yes
`token`	string	The client’s token, which is retrieved in the user creation and login process.	Yes

Creating account requirements

The purpose of the POST /v1/quotes/{{quoteId}}/account-requirements is to identify which fields are required to create a valid recipient for different currencies.

Create Account Requirements

The 3.1.3 [EntryPoint] Post account requirements - v1 process handles this business flow.

Process payload

{
     "quoteId":"cc14e18d-1bf7-4f55-a350-6271bdefc485",
     "searchRequiredFields": {
          "type": "iban",
          "details": {
               "email": "swissguy@mail.com",
               "legalType": "Private",
               "IBAN": "CH1589144313794187662",
               "town": "Zürich",
               "postCode": 8037,
               "address": {
                    "country": "CH"
               }
          }
     },
     "token": "e03099b8-2905-46a3-8f15-811b7cbd0091",
     "language":"he"
}

Parameter	Type	Description	Required
`quoteId`	string	The quote ID, which is retrieved in the quote creation process.	Yes
`searchRequiredFields`	object	An object holding the required fields.	Yes
`searchRequiredFields.type`	string	There are many different variations of bank account details needed depending on recipient target currency. For example: GBP — sort code and account number; BGN, CHF, DKK, EUR, GEL, GBP, NOK, PKR, PLN, RON, SEK — IBAN; USD — routing number, account number, account type; INR — IFSC code, account number; and more.	Yes
`searchRequiredFields.details`	object	An object holding the details of the required fields.	Yes
`searchRequiredFields.details.email`	string	An email address.	Yes
`searchRequiredFields.details.legalType`	string	The legal type of the entity, can be `Private` or `Business`.	Yes
`searchRequiredFields.details.IBAN`	string	An IBAN number.	Yes
`searchRequiredFields.details.town`	string	The town or city.	Yes
`searchRequiredFields.details.postCode`	integer	The postal code.	Yes
`searchRequiredFields.details.address country`	string	The two letter country code for the country.	Yes
`token`	string	The client’s token, which is retrieved in the user creation and login process.	Yes
`language`	string	The language code, which can be found in Wise’s Language Support page.	Yes

User authentication

Wise user validation is done based on email address. If a user with the same email address already exists in the system, the MPO User creation process will respond with a 409 User already exists error. The UI app should pick this error up and redirect the user to the authorization web page. The user can then log into Wise and provide access. The redirect page contains a code that is used to generate the token for the user. This code represents the entry payload for the process that retrieves the token.

Token_from_code

The 2.2. [EntryPoint] Create token for existing user from code process handles this business flow.

Process payload

{
    "code": "kZ9pTK"
}

Parameter	Type	Description	Required
`code`	string	Authorization code provided to you upon redirect back from the authorization flow.	Yes

For more information, see the Authentication and access section of the Wise documentation.

Sender Flows