Data Sessions
Retrieve different kinds of bank account data with 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 beidentity
ormatch_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_identity
permission:
{
"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:
Parameter | Type | Description |
---|---|---|
id | String | A unique identifier for the created data session. |
redirectUrl | String | Send the user here to start the data session. |
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:
Parameter | Type | Description |
---|---|---|
id | string | The unique ID assigned to the data session. |
referenceId | string | The referenceId is provided in the request. |
status | string | The status of the data session. Possible values are open , waiting_for_data , closed , failed , complete . The data is available as soon as the status equals complete . |
data | object | An object containing the requested data. This includes the following parameters: bankName , identity and accounts . |
matchResult | string | A string. One of full_match , partial_match or no_match . Only set if permission is set to match_identity |
identity | object | The identity object. See below for more information. Only set if permission is set to identity` |
metadata | object | An object containing any metadata is included in the request. This can be used to provide additional context or information about the data session. |
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:
Parameter | Type | Description |
---|---|---|
name | string | The name of the account holder. |
dateOfBirth | string | Optional. The date of birth of the account holder. |
Accounts
The accounts
array contains the following parameters:
Parameter | Type | Description |
---|---|---|
name | string | The name of the account. |
financialAddress | object | An object containing the identifier of the account. |
accountType | string | The type of the account. Possible values are checking , savings , credit , card , loan , investment , insurance , other , unknown . |
Financial Address
The financialAddress
object contains the following parameters:
Parameter | Type | Description |
---|---|---|
type | string | The type of the financial address. Possible values are iban , bank_code . |
iban | object | An object containing the IBAN and the account holder name. |
bankCode | object | An object containing the bank code, the accountNumber and the account holder name. |
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"
}
Updated 3 months ago