Getting Started

⚠️

Geographic Limitation

This API is at the moment available only for Spanish IBANs and NIF/NIEs.

Devengo Holder Verifications API allows you to confirm that a Spanish NIF/NIE is the legal account holder of a bank account. This guide will teach you how to create and confirm holder verifications from start to finish.

Please notice that this service ONLY verifies that a provided person is the legal account holder of the provided IBAN. If you want to verify that a non-account holder (e.g. beneficiary) has access to the IBAN please use our Access Verifications API.

Although the verification occurs just in a few seconds, this is an asynchronous process and we recommend to create a webhook to receive our callbacks to have detailed and realtime control over the process.

Create a Sandbox Account

The first step, unless you are already using other Devengo products, is to create a Sandbox Account. The Sandbox Account allows you to test the functions without using real bank accounts or transactions. To create a Sandbox Account, follow these steps:

1. Create your account by filling out this form.
2. You will receive a confirmation email. Once confirmed, you will have full access to the Devengo API.

Create a session token

To interact with the Devengo API, you need to generate a session token. This token authenticates your requests and provides access to the API. To create a new session token, you will have to provide the email and password used in the signup form.

curl -X POST 'https://api.sandbox.devengo.com/v1/auth/tokens' \
-H 'Content-Type: application/json' \
-d '{"email": "[email protected]", "password": "your_password"}'

{
   "token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX25kIjoibWFuXzRuakRLSTNFQmJjYWtyQXEyMENCSVohLCJ1c2VyX3R5cG6iOiJNYW5hZ2VyIiwiY29xcGFueV9pZCI6bnVsbCwiZXhwIjoiMTY4NjA1MHA0MiJ9.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   "refresh_token": "eyJhbGciOiJIvzI1NiJ9.eyJ1c2VyX2lkIjoibWFuXzRuakRLSTNFQmJjYWtyQXEyMENCSVHiLCJ1c2VyX3R5cGUiOiJNYW5hZ2VyIiwiY29tcGFueV9pZCI6bnVsbCwicmVmcmVzaF90b2tlbl9pZCI6InRva18yNUg4ajZHMEFiUUp4VkZHdDJkTWxqIiwiZXhwIjoiMTY4NzI5ODg0MiJ9.IcTS5-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Create the first Holder Verification

Once you have a session token, you can start creating Holder Verifications:

curl -X POST https://api.sandbox.devengo.com/v1/holder_verifications \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer THE_SESSION_TOKEN' \
-d '{
      "recipient": "Devengo S.L"",
      "taxid": "B88353412",
      "destination": {
          "type": "iban",
          "iban": "ES3969400001150000000001"
      }
}'

You will get a response with this structure:

{
  "holder_verification": {
    "id": "vrh_2KX8KGkSUMr37APZsRb2l2",
    "counterparty": {
      "name": "Devengo S.L",
      "taxid": "B88353412",
      "account": {
        "identifiers": [
          {
            "type": "iban",
            "iban": "ES3969400001150000000001"
          }
        ],
        "bank": {
          "name": "Devengo",
          "bic": "DEVNESM2XXX"
        }
      }
    },
    "status": "created",
    "company_reference": null,
    "metadata": {},
    "response": null,
    "fee": {
      "cents": 0,
      "currency": "EUR"
    },
    "created_at": "2025-06-21T09:14:05Z",
    "error": null
  }
}

Result of the verification

Once we receive the verification response from the counterparty's financial institution, we will update the status to the corresponding value:

• confirmed if the counterparty is the legal account holder.
• failed if the counterparty is not the legal account holder.
• rejected if the legal holder of the provided account can't be verified (e.g. because the account does not exist, has been closed, etc.).

📘

Sandbox Testing

Please note that in the Sandbox environment:

• All verifications for the IBAN ES8569400001100000000000 will become rejected
• Verifications for any other IBAN will be processed.
• Using the counterparty identifier B88353412 will return a confirmed verification
• Any other counterparty identifier will return a failed verification.

Retrieving a holder verification

You can always access the state of a holder verification using the corresponding endpoint:

curl --request GET \
     --url https://api.sandbox.devengo.com/v1/holder_verifications/vrh_2KX8KGkSUMr37APZsRb2l2 \
     --header 'Authorization: Bearer THE_SESSION_TOKEN' \
     --header 'accept: application/json; charset=utf-8'

Next steps

• Understand the lifecycle of a Holder Verification.
• Create a webhook.