Accessing Customer Accounts

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

We can provide this option to banks where we can create a trusted reliance or outsourcing model on your KYC processes.

Below is a sequence diagram showing this flow.

New user onboarding sequence

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.

New users have to accept the Wise Terms and Conditions as part of their sign-up process, which should be available for them to read as a link to our website.

At a high level there are two steps to gaining access to an existing Wise account.

  • Obtain an authorization code
  • Exchange the authorization code for API tokens

There are two possible ways to get an authorization code — by opening the Wise website,

  • Having the user login and agree to connect accounts and then redirect back to your app.
  • By us sending an email to the end user with a link to log in 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.

Redirecting to the Wise website

The standard website redirection flow is as follows:

  • Your app redirects the user to Wise authorization web page.
  • The user logs in to Wise.
  • The user agrees to provide access to partner application.
  • The user is redirected back to your pre-configured redirect_url, including an authorization code you can use to generate user tokens. e.g.[CODE]&profileID=[PROFILE_ID]

These steps are explained in more detail below.

1. Your banking app redirects user to Wise authorization web page

Your website or app opens the following url in the user's browser - environment information

2. The user logs in to Wise

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.

3. The user agrees to grant access, and we forward them to your redirect_url

Once a user gives your application authorization to connect to Wise and access their data, the user is redirected back to your redirect_url with a generated code query string value. For example[CODE]&profileID=[PROFILE_ID]

Your website or service can then use this code to obtain the access token to act on behalf of the user account described in the Exchange an authorization code for API Tokens section

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.

The redirect_uri has to be preconfigured before it can be used. The value used should be equal to the value preconfigured, including the query parameters.

Wise sends an email to the customer to give them an authorization code

If the website based flow is not possible for you then you can request for Wise to email the customer with a link for them to get an authorization code. This enables the user linking flow but avoids having to redirect the user to an external website.

The flow is more cumbersome for a user, this should only be used as a last resort. To enable this flow, you must send the sendAuthorizationCodeAsEmail parameter as true when Creating a User

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 log in to their Wise account, grant access, and are presented the code.
  • The user can then enter the authorization code in to your app.
  • Your backend exchanges the authorization code for access tokens.
Users may skip important steps when attempting to access the customer account. If the user wishes to link into the Wise account again, you will need to ensure an appropriate flow.

Exchange an authorization code for API tokens

The final step is to use the authorization code and exchange it for customer tokens API Reference.

Actions after linking an account

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 <strong>date of birth</strong> 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.

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

Existing TW user onboarding sequence