Getting Started

With just three API calls, you can access the verification report for your end-user:

1. Create a Widget link for one-time account information access
2. Exchange an authorization code for an access token
3. Fetch the verification report

1. Flow Initiation

To start the verification process, make the following API call:

Endpoint

POST /onetime/account-verification

{
  "redirect_uri": "https://my-app.example.com/callback",
  "language": "en",
  "name": "Ahmad Al-Faisal",
  "account": "SA4420000001234567891234",
  "readout": []
}

 

Parameters

• redirect_uri (Required): The address to which the user will be redirected after completing the verification process.
• name (Required): The full name of the account holder as registered with your application.

Optional Parameters:

• language: Defines the language used in the Widget. Use ar for Arabic, en for English, or other supported language codes.
• account: The IBAN of the bank account for verification. If provided, the Widget will preselect the bank and account, requiring the user only to enter their bank credentials and authorize access with Strong Customer Authentication.
• readout: Options such as ACCOUNTS and TRANSACTIONS allow you to fetch additional account and transaction data.

{
  "location": "https://misconnect.example.com/?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJo...",
  "id": "3ca31c37-986a-454e-ad64-8e97143c86bc"
}

 

Forward the User

Forward the user to the location provided in the API response.

The Widget UI will guide your end-user through the process of connecting their bank account. The user can either interactively select an account in the UI from the list of available accounts or, if the account field is provided, the Widget will automatically select the bank and account for verification. MIS Connect will fetch the user's account data and look for the account-holder's name.

2. Exchange Authorization Code

After a user successfully goes through the flow, they are redirected to the redirect_uri provided in your initial request to create the Widget link. The following query parameters will be automatically added by us:

• state: The value provided by you during flow initiation. You can use this to identify which user is now being redirected to the redirect_uri and reinstantiate the state of your website accordingly.
• success: Indicates whether or not the flow was successfully completed by the user.
• code: The authorization code to be exchanged for an access token to gain access to the financial data of the user. It is only returned if the user successfully completed the flow and is valid for one hour.
• cancel: Indicates whether or not the flow was canceled by the user. Only present if the user actually canceled the flow and not in other error cases.

https://example.com/callback?code=eyJhbGciO...&state=7fe78733&success=true

Requesting an access token

{
  "grant_type": "authorization_code",
  "code": "eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...",
  "redirect_uri": "https://my-app.example.com/callback"
}

{
  "access_token": "AoFmNJLDTW8jQtGSJ1iZeeoLiwNZ2ihz3iiCHGpuvE439nppuY...",
  "expires_in": 3600,
  "scope": "accounts=ro balance=ro transactions=ro offline",
  "token_type": "Bearer",
  "refresh_token": "RTfI2WNyK78NozupDH9ai8GPRbjjdVsXPPt..."
}

You have to provide the returned access_token in the HTTPAuthorizationheader of subsequent API requests. In case of an ongoing use-case, you additionally need to store the returned refresh_token on your end to permanently keep access to your enduser's data. Whenever you use an existing refresh token you will automatically get a new one in the response. Your application has update it's existing one in your storage backend to ensure the token is valid and not expired. If no user activity is present within 90 days, or the refresh token is not replaced with a new one, your access will be lost.

Token lifetimes

📘

The actual length in bytes of all tokens (access and refresh tokens as well as authorization codes) can vary. Therefore it is highly advised to not limit the size of the database field in your storage backend. If you have to specify a size for the corresponding database field a choice of at least 2048 bytes is highly recommended.

3. Fetch financial data

Please view the Fetching Account & Transaction Data section for a detailed overview.