Data Sessions

A dataSession is the Ivy object, which you can use to let your user securely and efficiently log in to their bank account. When creating a dataSession, you can specify which data you want to retrieve from your user. This can be, for example, identity data such as the account number & holder name or a matching request with your user's bank account data.

Create a Data Session

To create a data session using the Ivy API, call the Create a DataSession endpoint.

🚧

Check which mode

Be sure to set permissions to the data access you want to retrieve. this can be identity or match_identity.

Example Request Payload

This is an example request payload to retrieve identity data of a user:

{
    "referenceId": "123456789",
    "permissions": ["identity"],
    "market": "DE",
    "successCallbackUrl": "https://example.com/callback/success",
    "errorCallbackUrl": "https://example.com/callback/error",
    "resultCallbackUrl": "https://example.com/callback/result",
}

If you want to check if the user gave you rightful bank data, you can also just use the match_identitypermission:

{
    "referenceId": "123456789",
    "permissions": ["match_identity"],
    "market": "DE",
    "successCallbackUrl": "https://example.com/callback/success",
    "errorCallbackUrl": "https://example.com/callback/error",
    "resultCallbackUrl": "https://example.com/callback/result",
}

Redirect the User

The response includes the fields:

In order to start the data session and let the user authenticate with their bank, redirect the user to the redirectUrl specified in the response.

Result

Successful Redirection of the User

When the user finished the verification with their bank successfully in the Ivy Flow, they will be sent back to the specified successCallbackUrl. You need to provide this URL by setting the successCallbackUrl field in the Create a DataSession request.

Handle the Result Callback

The result of the data request will be sent to the resultCallbackUrl endpoint as a POST Request. You have to set up an API endpoint in order to receive the result. Make sure to verify that the result is coming from the Ivy API by checking the X-Ivy-Signature header.

• Obtain the Webhook Signing Secret from the Ivy Dashboard
• The calculation is done with the request body and the Webhook Signing Secret using the HMAC & SHA-256 Hash

Here is an example signature calculation with Node:

const { createHmac } = require('crypto')
const config = require('../config')

/*
  Parameter "data" is the request body
*/
function sign(data) {
  const hmac = createHmac('sha256', config.IVY_WEBHOOK_SIGNING_SECRET)
  hmac.update(JSON.stringify(data))
  return hmac.digest('hex')
}

Calculate the signature with the incoming payload and the Webhook Signing Secret and compare it with the X-Ivy-Signature header. If the signatures match, the request is coming from the Ivy API.

Result Payload

The Result payload contains the following parameters:

Result for match_identity

full_match: The account holder name & financial address match the given matchData exactly

partial_match: The account holder name & financial address match the given matchData partially

no_match: The account holder name & financial address do not match the given matchData at all

Result for Identity

The identity object contains the following parameters:

Accounts

The accounts array contains the following parameters:

Financial Address

The financialAddress object contains the following parameters:

Example

The result will be sent as a webhook of type data_session_completed. An example result payload for an identity request might look like this:

{
  "type": "data_session_completed",
  "payload": {
    "id": "abcdef1234567890",
    "referenceId": "123456789",
    "status": "complete",
    "data": {
      "bankName": "Example Bank",
      "identity": {
        "name": "John Doe",
        "dateOfBirth": "1980-01-01"
      },
      "accounts": [
        {
          "financialAddress": {
            "type": "iban",
            "iban": {
              "iban": "DE12345678901234567890",
              "accountHolderName": "John Doe"
            }
          },
          "accountType": "checking",
          "name": "Example Account"
        },
        {
          "financialAddress": {
            "type": "bankCode",
            "bankCode": {
              "accountNumber": "1234567890",
              "bankCode": "123456",
              "accountHolderName": "Dohn Joe"
            }
          },
          "accountType": "checking",
          "name": "Example Account"
        }
      ]
    }
  },
  "date": "2023-04-29T11:50:13.176Z"
}