Accessing Customer Accounts

In order to perform actions on behalf of a customer you need to create a new or link an existing Wise account.

If a user doesn't already have a Wise account then you can create one for them. The signup with registration code feature lets you create new users directly via an API call. You will send via API all of the data Wise needs to serve these users in your region, meaning users have their accounts created without ever leaving your banking app, making a very streamlined flow.

You will define a registration_code for the user that act similarly to a password, although is limited in scope to be used only by your integration over the API. You exchange this value for user tokens, as described in the detailed documentation above. This code can be used to regenerate tokens should they become invalid, so you should save it in your database to allow this. Due to the password-like nature of this data we recommend to store it encrypted at rest for security.

Below is a sequence diagram showing this flow.

If you attempt to create a user that already has a Wise account they will always need to be redirected to the account linking flow, you can detect this at the point you attempt to create the user based on the API response of 409 conflict. See the detailed guide under the endpoint documentation for more details.

Verification Documents

In certain integrations, we may require additional documentation regardless of our ability to rely on the partners KYC information. For example, in Brazil, we require the CPF value for a profile to allow us to report to the central bank in Brazil.

If you are creating accounts and a verification document is required, please see the Create an identification document for a profile API reference to pass the correct type and uniqueIdentifier.

In order to perform actions on behalf of an existing Wise customer the user has to login and give consent. We then redirect them back to your app.

The standard website redirection flow is as follows:

1. Your app redirects the user to Wise authorization web page.
2. The user logs in to Wise.
3. The user agrees to give your application access to one of their Wise profiles.
4. Wise redirects the user back to your back to your app.
5. Your app exchanges the authorization code for API tokens.

These steps are explained in more detail below.

You can also have a look at the code sample of how to implement that flow.

Your website or app opens Wise authorization page in the user's browser.

On mobiles apps you should not use legacy WebView components to show the authorization page to the users because they are not secure and will not allow users to log in to Wise with Google, which is an option used by many of our users. Your app should instead open the device's full browser app or use the newer iOS and Android features to show isolated web pages within apps in a secure way, namely a SafariViewController or a ChromeCustomTab, respectively.

Our usual log in screens are presented to the user if they are not already logged in on the browser being used. If enabled for a user they will also be prompted to go through our two-factor authentication procedure.

The Wise user will create or select a profile that will be linked with your application. Wise profiles are the personal or business entities which will be involved in money transfers and other Wise activities.

Once the authorization process is complete, your app will be authorized to perform actions on the selected profile. Access to other profiles associated with the Wise user must be separately authorized.

Once a user gives your application authorization to connect to Wise and access their data, they will be redirected back to your redirect URL with some additional query parameters.

If you are building your Wise integration as a native mobile phone app then the redirect URL should be able to handle returning the user to the correct place in the app, using a "deep link" based on a custom URL scheme defined by your mobile app.

Your website or service can use the authorization code to obtain API tokens to act on behalf of the user account as described in the generate a User Token section.

When errors occur during authorization request handling, we display error details on our web pages. The user may also see a link back to your application, with error and error_description parameters in the URL instead of code. Your callback URL handler should be prepared to accept such "error" requests.

Upon linking to an existing Wise account you need to ensure that you have connected to an account that represents the same natural person or business. To do this for personal profiles please check the date of birth of the connected wise profile matched the date of birth you hold for that customer in your platform. For businesses the comparison required changes with the region you are servicing, please discuss the best approach with your implementation team.

We also offer an alternative way to to retrieve an authorization code – by us sending an email to the end user with a link to login to Wise and the user then manually typing a code in to your app.

The redirection flow is always preferred as it requires no manual user actions. In some cases it is not possible to securely open the Wise website within your app, in which case the email flow can be used. Before using the email flow please discuss the implications with your implementation teams.

In the event of a 409 response(the user already has a Wise account) the flow should be as follows:

• Wise emails the customer a link to log in and generate an authorization code.
• The user opens their email app and clicks the link in the email. They login to their Wise account, grant access, and are presented the code.
• The user can then enter the authorization code in to your app.
• Your app can then use this code to generate a User Token.

Below is an end-to-end sequence diagram for connecting to an existing Wise user.