Match Identity data with bank information

Create a Data Session

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

🚧

Be aware!

Be sure to set permissions to ["match_identity"]

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:

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:

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"
}