Get & validate customer bank account

This is an integration guide for Get & Validate Customer Bank Account.

Complete API documentation is available at: API Reference

If you feel something is missing, or have any questions don't hesitate to contact us.

Properties

accountReference: This is a reference to a bank account. This can be used in other parts of the platform to perform payouts, or get details about the bank account such as country, name of the owner etc.

fetchAccountsSessionId: This is a reference of a fetch bank account session. It can be used to get the bank account references from a session.

Integration flow

Step 1: Initiating a customer bank account fetching session

Fetch the url to the iframe from the Payer API. API reference can be found here

Before loading the iframe url, attach the following query parameters to it:

• personal_number - The personal number of the customer to fetch bank accounts from. Only Swedish personal numbers are supported. The personal number must be provided in 12-digit format, otherwise the personal number will not be pre-filled. If pre-filling of personal number is not wanted, pass any non valid personal number, e.g. personal_number=0.
• locale - Language country pair, ex. sv_SE (ISO-639 Language Codes and ISO-3166 Country Codes)
• redirect (optional) - true/false. If you want the iframe to pass the result by redirecting the web page instead of posting the result as an event on the window. If not provided, false is set. Setting this parameter to true is the preferred way when integrating bank account fetching in a mobile app.

Load the url in an iframe (or WebView if integrating in a mobile app) and wait for the result to be communicated.

Step 2: Extracting the fetchAccountsSessionId

When the user finishes their selection of bank and authentication the result will be communicated in the following ways, depending on how the redirect parameter is set.

If redirect is set to false

The result is communicated as an event on your window with the name message. To listen for the event, add an event listener:

window.addEventListener('message', (event) => {

    // Handle event here

});

The result will be found in event.data.

If fetching was successful, it will contain the string fetch-bankaccounts-event:{fetchAccountsSessionId}. fetchAccountsSessionId is used when fetching information about the bank accounts from the Payer API.

If fetching was unsuccessful, it will contain the stringfetch-bankaccounts-error:{error}.

If redirect is set to true

The result is communicated as the web page redirecting. Information about the result can be extracted from the url.

If fetching was successful, the web page will redirect to {iframeUrl}/success?fetchAccountsSessionId={fetchAccountsSessionId}. fetchAccountsSessionId is used when fetching information about the bank accounts from the Payer API.

If fetching was unsuccessful, the web page will redirect to {iframeUrl}/error?error={error}&errorCode={errorCode}

Error handling

As noted above, if fetching was unsuccessful, an error will be signalled. In the redirect case, an errorCode is also provided, containing more detailed information about the error. For most types of errors there will only be one corresponding errorCode. But for some errors, there's multiple possible errorCodes.

Step 3 - Using the fetchAccountsSessionId to get account information

With the fetchAccountsSessionId you can fetch information about the recently fetched bank accounts. API reference can be found here.

The API will return a list of bank accounts with masked account numbers. If you wish to use a bank account in any subsequent call to the Payer API, e.g. Payout Experience, take note of the accountReference.

The session reference can be used to fetch bank accounts multiple times, but only before the customer completed another session to fetch bank accounts with the same bank. Therefore, if a persistent identifier for the account is required, always store the accountReference.