Customer Accounts with Wise KYC

This guide is intended for Wise Platform partners who are not licensed and able to perform know-your-customer or know-your-business (KYC or KYB) checks in-house or where a reliance model (see note) is not possible. If that is the case then Wise will have to conduct the KYC/KYB checks for you.

The following pages will walk you through the steps to build a journey which redirects your end users to our standard wise.com onboarding flow. Users should have the ability to create a profile, get verified and then be redirected back to your own app.

Alternatively, if you already store some customer KYC/KYB data, we also provide a UI flow with API pre-upload. This means we can allow you to create user profiles and submit data on behalf of your customers to Wise over our API. Users will still need to be redirected to Wise.com to validate and/or supplement the pre-filled data, as well as to complete their verification and onboarding. However, having some of the details pre-populated for them can lead to an improved user experience and also means that more of the user journey can happen within your own UI. This feature is particularly useful for business customers where more data points are required (e.g. UBO and director information).

Wise uses standard OAuth 2.0 protocol for authentication and authorization.

Once our partnership begins, we’ll send you API access credentials for the sandbox environment consisting of a Client ID and a Client Secret. The credentials are needed to either create users over API or complete the authorization_code OAuth 2.0 grant type through which the customer will allow your application access to their account.

The Client secret is a very sensitive piece of data as it could be used to impersonate your institution on the Wise Platform API. It should be handled and stored with the upmost care, seen by as few people as possible and stored in a secure secret storage solution, preferably away from any other Wise data such as user API access tokens.

We also need redirect_url from your technical team which is used to forward users to after successfully granting your application access to their Wise account. Specifying this explicitly makes the integration more secure. This article about OAuth 2.0 framework is a great way to refresh your knowledge about the protocol itself.

We provide two distinct environments, Production and Sandbox, to allow developers to develop, test, and deploy their applications.

Production Environment is the live environment that developers can use to send real-time requests to the Wise Platform API. This environment is intended to be used in the final stages of development when the application is ready for deployment.

Sandbox Environment is the testing environment that developers can use to build and test the application. This environment allows developers to make API requests without affecting the production environment. It is ideal for testing API requests, because it is similar (but not identical) to the production environment.

The Sandbox environment is designed for testing and does not support real money transfers, actual financial controls, or all currency routes available in our Production environment. Endpoints will also have more latency in Sandbox than in Production.

We provide a Simulation API to test money movement flows and other features, supporting the testing of webhooks and their payloads, which otherwise would not be possible.

There are some differences between the Production and Sandbox environments. If you are a partner and you run into issues testing in Sandbox, please fall back on the following features, countries, and currencies, as these are most stable. If there is an issue with one of the listed flows that is reported by a partner, we will open an internal incident and prioritise fixing it.

Please note that your implementation team will give you a test plan during your implementation if you are a partner, and you will need to adhere to that. This is simply a list of what is and isn't available, for reference.

Supported Regions and Currencies in Sandbox

If you are testing a different currency or region in Sandbox and it does not work, please fall back on the following currencies and regions:

The following sections outline the functionality you can test in Sandbox if you are a partner.

Access the API

1. Receive API client credentials from our integration success team.
2. Obtain a client credentials token for your application.
3. Obtain access/refresh tokens from one of our onboarding flows.
4. Refresh an access token from a refresh token.
5. Update keys and certificates for testing mTLS, JWS, and JWE.

Onboard Customers to Sandbox

1. Create personal and business profiles.
2. Create multiple business profiles.
3. Check that a user exists over API.
4. Create a new user over API.
5. Create a new Wise account in the UI and link it via OAuth UI.
6. Disconnect and reconnect Wise accounts.
7. Create a new Wise account via API and claim it with a registration code.
8. Simulate the verification of one of the supported profile types.
9. Receive a verification status completed webhook event.

Send Money

1. Create fixed target and fixed source quotes.
2. Get realistic but not live rates.
3. Create a recipient over the API.
4. Create a quote over the API.
5. Request transfer requirements for the above.
6. Create a transfer from the above recipient and quote.
7. Create a third-party transfer from the above recipient and quote.
8. Create a partner license transfer from the above recipient and quote.
9. Create a batch payment from the above recipients and quotes.
10. Initiate the fund of a transfer with balance or bulk settlement.
11. Subscribe to and receive transfer state change webhook events.
12. Simulate transfer state changes.

Hold Money

1. Create a balance for a supported currency.
2. Convert balance amounts between supported currencies.

Receive Money into a Balance

1. Simulate a top up of a balance for a supported currency.
2. Subscribe to and receive a balance update webhook event.
3. Retrieve a statement with a simulated top-up present.
4. See sent and received payments in a statement.
5. See balances updated with received transfers.

Receive Money via the SWIFT network

1. Simulate an MT103 message.
2. Subscribe to and receive a balance update webhook event.
3. Retreive a statement with a simulated top-up present.

Order Cards

1. Check card order availability in supported regions.
2. Create a card order.
3. Set a card PIN.
4. Get card order requirements.
5. Retreive a list of card orders.
6. Subscribe to and receive card order state change webhook events.

Manage Cards

1. Retrieve a list of cards.
2. Change the status of a card.
3. Retrieve sensitive details of a card (PAN, PIN, CVV).
4. Subscribe to and receive card state change webhook events.

Manage Spending Controls

1. Add and delete spending limits of the card per card.
2. Manage spending limits of the card per profile.
3. Add spending controls (MCC and currency) to all cards of the application.

Test Card Transactions

1. Retreve a card transaction.
2. Subscribe to and receive card transaction state change webhook events.
3. Simulate a card transaction authorization and clearing for Visa.
4. Simulate a card transaction authorization for Mastercard.

Test Card Transaction Disputes

1. Submit a dispute.
2. Retreive a dispute status.
3. Withdraw a dispute.
4. Subscribe to and receive dispute state change webhook events.

Test Strong Customer Authentication

1. Add PIN as a factor.
2. Add Facetec biometric as a factor.
3. Add device fingerprinting as a factor.
4. Verify an SCA protexted action through PIN, Facetec, or device fingerprinting challenges.

The Sandbox environment has some limitations, specifically that it does not support real money transfers, actual financial controls, or all currency routes available in our Production environment.

If a feature isn't specified in the above lists, it can be assumed that we don't officially support it in Sandbox.

We cannot guarantee all currencies will work the same in Sandbox as Production. If you run into issues, please fall back to the currencies and regions shared above.

In addition, we do not support:

1. Any other UI screen not explicitly stated above.
2. Movement of real money.
3. Notifications by email or phone (2FA code is always 111111).
4. Verification and payment issue flows (including cases and disputes), other than what is required in the supported onboarding flows.
5. Real verification or onboarding rules/fincrime checks (including what evidences we may ask for in different regions) due to compliance constraints.
6. Any deprecated APIs/versions for features covered in above sections.
7. Strong customer authentication with SMS, phone call, and Whatsapp (SCA can be disabled via your client credentials).
8. Direct Debit/ACH funding for USD.
9. Mobile tokenization flows (ex. Google Pay, Apple Pay).
10. 3DS transactions.
11. Simulations of credit transactions for cards.
12. Card manufacturing flows.
13. Live rates.
14. Delivery of refund webhooks.

On iOS devices, you might need to set some WKWebViewConfiguration configurations to initialize the user's device camera. There are points in the Wise KYC onboarding which will require the user to upload or take a photo.

1. Enable (set to true) inline media playback allowsInlineMediaPlayback | Apple Developer Documentation
2. Ensure the user does not have to do any action to start playback by setting this value mediaTypesRequiringUserAction to none or an empty array in swift.

These properties are on the configuration WKWebViewConfiguration | Apple Developer Documentation you set on the WKWebView.

Another note, there seems to be a bug on the WKWebView which means for these settings to apply you must pass them into the WKWebView initialiser. Simply modifying the configuration by accessing the web views property doesn’t seem to apply the configuration properly and won’t work.

On Android devices, you might need to enable camera permissions for the web-view even if the app has the user-permissions. To do this, add the following block of code where the web view is initialised.

webView.webChromeClient = object : WebChromeClient() {
    override fun onPermissionRequest(request: PermissionRequest) {
        request.grant(request.resources)
    }
}

Note, that request.grant() would provide any available permission for the app to the web view. In case the camera permission is denied by the user, they would see an error page. You do have the option to initiate the permission sequence in this callback and go back to the flow if required.

You will build your Wise user experience directly into your mobile and desktop applications, and will build a backend service to support the features it offers. Your user interface should never directly call any authenticated Wise endpoint which requires an API token, this should always be done by your backend system.

Depending on the features and settlement model you will build, there are some different components you will need to build. Please ask your Wise implementation team for advice based on the requirements of your integration.

You should expose an API internally for your web and mobile clients to call to provide the required Wise features. Your backend system will manage both communication to the Wise Platform API and internal operations such as querying user KYC data to send to Wise, checking a user has sufficient funds to make the requested transfer and triggering the payment of funds to Wise when a user confirms a transfer.

You should also store a copy of certain data relating to Wise to decrease latency and increase resiliency when users review previous transfers they have made or recipients they sent funds to. The extent of what you store will depend on your integration, but we recommend to store at a minimum:

• Quotes that have been used to create transfers
• Transfer records including ID and status
• Recipient IDs, names and account summary data

The goal is to store locally in your platform all the data you need to drive your UI, such that calling our API is not required when reviewing historic data.

You should subscribe to our webhooks to keep this data up to date.

This section discusses some edge cases that you should test and handle before going live with your integration.

Email changed at Wise

If a user changes their email address, all tokens to the user account are revoked. In this case the bank will receive a 403 when attempting to generate an access_token and as such should follow the same process as described in the "Token Expiry" section below and start the sign-up flow from the beginning.

In this case, if the user has changed their email address at Wise, it is possible the user will end up with a new Wise account using their old email address still held by the bank, or they might link their bank account to a different already existing Wise account under the old email address.

Token Expiry

It is also possible that a user's refresh token will become invalid. This could happen for a number of reasons, for example:

• The refresh token's validity period expires (usually set at 10 years or more)
• The user revokes the access of your application to their account.
• The user enables enhanced security on their Wise account.
• Wise revokes a token due to a suspected security breach of the token or your client secret.

Due to this possibility your application should handle the scenario where you fail to generate a new access token from the refresh token. Correctly handling this depends on how you originally gained access to the user.

An existing user granted your application access to the account

If you were granted access by an existing user then you should send the user through the same flow as you initially did to generate tokens described in "Connecting to an Existing Wise account" below. You will then have new access and refresh tokens generated which you can now store and use as before.

When you are submitting an email which already exists amongst our users then an attempt to create a new one will fail. In that case you should follow the standard website redirection flow.

1. Make your integration bulletproof

• Implement basic retry mechanism to handle potential failures or network interruptions
• Implement duplicate prevention mechanism to avoid duplicate payments. Verify that UUID is uniquely generated for each individual payment and its value is kept same in case of retrying.
• Implement basic logging to help out in debugging and problem solving, if needed.
• Check that you can handle all possible transfer states during polling of transfer info.
• Handle the potential issues described in Edge Case Handling above
• Required data fields for recipients and transfers vary for different currencies. Please explore Recipient Account Requirements and Transfer Requirements
• Some good recipient currencies to test are:
  • CAD - has several fields in a field group.
  • USD - the country field has refreshRequirementsOnChange.
  • JPY - the bank field has refreshRequirementsOnChange.
  • KRW - has a field using a date component type.

2. Set up security for LIVE environment

• Make sure you have received and successfully decrypted Live API credentials, storing them securely.
• Ensure access tokens and refresh tokens are also stored securely and only exposed to authorized persons.
• Make sure your server has TLS version 1.2 or higher.
• Implement a mechanism to obtain new access token upon expiration.

3. Do some testing in LIVE

• Launch LIVE integration to a limited set of your customers and test all currency routes you will offer end-to-end.
• We recommend launching a limited set of currencies initially to limit the scope of potential issues, please seek guidance from the Wise team.
• Test successful flow and bounce back flow (where funds cannot be delivered).
• All set. Switch it on.

4. Monitor API Status

• You can always track our API status here.

There are different ways to build your user experience, especially when it comes to the sequence of steps in the payment flow, but we have a recommended order. We strongly recommend you follow this flow as it has been tuned by the Wise team to be the simplest to understand for the customer and the easiest to build using the APIs defined below.

We are happy to help you to design and build a great experience for your customers using our experience so please don't hesitate to get in touch if you need advice, especially if you want to deviate from the recommended flow.

Your Wise user experience

There are two main user flows that must be built in order to integrate with Wise.

The user onboarding flow

There are two ways to access the Wise Platform API depending on if you customer already has a Wise account or not. You should handle both cases in your integration.

Flowchart

This flowchart describes the different scenarios you will encounter and how you should handle them.

You need to go through this flow only once for each customer before they can set up their first transfer.

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 of the bank account in your platform. 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.

The transfer flow

To create transfers on behalf of users you need these building blocks:

• Refresh User's Access Token
• Create Quote
• Create Recipient Account
• Create Transfer
• Fund Transfer