Guides

Match Identity Data with bank information

Match the Full Name, and bank account number / IBAN for a user. You can use this for KYC, AML etc.

Suggest Edits

Create a Data Session

To create a data session using the Ivy API, you will need to call the Create a DataSession endpoint with the following request parameters.

🚧

Be aware!

Be sure to set permissions to ["match_identity"]

ParameterTypeRequiredDescription
referenceIdStringyesA unique identifier for the data session.
permissionsArrayyesThe permissions that the user will be asked to grant. Possible values identity, balance, match_identity
resultCallbackUrlStringyesThe URL to which the account ownership result will be sent if the data session is completed successfully.
successCallbackUrlStringyesThe URL to which the user will be redirected when the data session is successfully completed.
errorCallbackUrlStringyesThe URL to which the user will be redirected when the data session is not completed successfully.
marketStringyesThe market of the user. This will determine the default banks shown to the user initially. It will not restrict any banks. ISO 3166-1 alpha-2 codes.
matchDataObjectconditionalRequired if permissions is set to match_identity. The data provided which will be used to check against any data provided by the bank.
localeStringnoThe language/locale to use in the data session.
externalUserObjectnoAny external user data you want to store to the data session. You can query for data sessions with this later.
prefill.bankIdStringnoIf given, the bank corresponding to this id will be pre-selected in the data session.
metadataObjectnoYou can store random key-value pairs in this field. This field will be sent in the result as well.

Here is an example curl request for creating a data session to verify identity:

curl -X POST \
  https://api.getivy.de/api/service/data/session/create \
  -H 'Content-Type: application/json' \
  -H 'X-IVY-API-KEY: <api-key>' \
  -d '{
    "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 following parameters:

ParameterTypeDescription
idStringA unique identifier for the created data session.
redirectUrlStringSend the user here to start the data session.

In order to start the data session and let the user verify 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.

Check the Result

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 calculation in Node.js:

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

/*
  Parameter "data" is the request / response body
  The response is the X-IVY-SIGNATURE
*/
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 Parameters

The Result payload contains the following parameters:

ParameterTypeDescription
idstringThe unique ID is assigned to the data session.
referenceIdstringThe referenceId is provided in the request.
statusstringThe 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.
matchResultstringA string. One of "match", "unclear" or "no_match".
metadataobjectAn object containing any metadata is included in the request. This can be used to provide additional context or information about the data session.

Match Result

The match result is a string. It can be one of the following values: match, unclear or no_match. It indicates how well the identity data matches the data provided by the bank. The match result is calculated based on the field matchData which was provided when creating the data session.

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",
    "matchResult": "full_match"
  },
  "date": "2023-04-29T11:50:13.176Z"
}

Updated 11 months ago