Data Sessions
Retrieve different kinds of bank account data with data sessions
A Data Session is the secure way to programmatically launch the client-side Ivy Data Session Flow that lets your users authenticate access to their their bank accounts.
Create a Data Session with the Ivy API
To create a data session using the Ivy API, call the POST /data/session/create
endpoint. At a minimum, you can create a checkout with the following data:
Field | Type | required | Description |
---|---|---|---|
referenceId | string | true | A unique reference ID, usually your internal transfer ID. |
permissions | string[] | true | The type of data, you want to retrieve from your user. Options: balances , transactions and identity |
returnUrl | string | true | The user will be redirected to this URL when they return to your app. |
market | string | false | The market of the user will be preselected when passing this field. |
customer | object | false | You can pass the customer identifier of the Ivy returning customer network, either email or customerId here to increase returning customer conversion. |
Example Payload
This is an example request payload to retrieve identity data of a user:
{
"referenceId": "123456789",
"permissions": ["identity"],
"returnUrl": "https://example.com/callback/result",
}
The response is the data session object with the additional redirectUrl
field:
Field | Type | Description |
---|---|---|
id | string | The unique Ivy id for this data session. |
referenceId | string | A unique reference ID, usually your internal Id. |
permissions | string[] | The type of data, you want to retrieve from your user. Options: balances , transactions and identity |
returnUrl | string | The user will be redirected to this URL when they return to your app. |
market | string | The market of the user will be preselected when passing this field. |
customer | object | You can pass the customer identifier of the Ivy returning customer network, either email or customerId here to increase returning customer conversion. |
status | string | The status of the data session. Possible values are started , pending , failed or complete . The data is available as soon as the status equals complete . |
data | object | An object containing the requested data. |
redirectUrl | string | The URL to which you need to redirect the user. |
Redirect the User to the Data Session URL
After you receive the response from the Ivy API, you need to redirect the user to the redirectUrl
that you received in the response.
Parameter | Type | Description |
---|---|---|
id | String | A unique identifier for the created data session. |
redirectUrl | String | Send the user here to start the data session. |
Retrieve Bank Data
After a user successfully finished authentication with their bank, Ivy adds the status pending
which then results in either a complete
or failed
terminal status.
The user will be redirected to the returnUrl
when the flow is done or cancelled. The following data is attached as query parameters to the return URLs.
Field | Type | Description |
---|---|---|
referenceId | string | The referenceId that you provided when creating the data session |
data-session-id | string | The data session id. |
success | boolean | true when the flow was successfully finished. Else, false . |
In order to retrieve bank data, you can either poll the GET /data/session/retrieve
endpoint or you can set up Webhooks to receive data session events.
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 20 days ago