Integration Guide

You are obliged to validate the transmitted IBANs in good time. This helps to streamline the process for you and us.

You must use our IBAN validation service only in conjunction with our payout services.

Validate a Single IBAN

The endpoint to validate a single IBAN is POST /api/v2/Payment/Containers/me/validateSingleIban:

Request

POST /api/v2/Payment/Containers/me/validateSingleIban HTTP/1.1
Host: connect-testing.secupay-ag.de
Content-Type: application/json
Authorization: Bearer htlu0l0m22rsesvh20f7i5d22i
 
{
  "iban": "DE37503240001000000524"
}

Apart from technical conditions, the service will always respond with HTTP status 200 OK, regardless whether the IBAN is valid or not.

If valid, also BIC and bank institute name are present:

Response Valid IBAN

HTTP/1.1 200 OK
Content-Type: application/json
 
{
  "id": null,
  "valid": true,
  "iban": "DE37503240001000000524",
  "bic": "FTSBDEFAXXX",
  "bankname": "ABN AMRO Bank, Frankfurt Branch"
}

If invalid, these data cannot be present:

Response Invalid IBAN

HTTP/1.1 200 OK
Content-Type: application/json
 
{
  "id": null,
  "valid": false,
  "iban": "DE37503240001000000523",
  "bic": null
}

Validate IBANs in Blocking Batch Mode

This mode must only be used if there is a small amount of IBANs to be validated.

The endpoint to validate an IBAN is POST /api/v2/Payment/Containers/me/validateIban:

Request

POST /api/v2/Payment/Containers/me/validateIban HTTP/1.1
Host: connect-testing.secupay-ag.de
Content-Type: application/json
Authorization: Bearer htlu0l0m22rsesvh20f7i5d22i
 
[
  {
    "id": 1,
    "iban": "DE37503240001000000524"
  },
  {
    "id": 2,
    "iban": "DE99999999999999999999"
  }
]

It responds basically like the endpoint for single IBANs. The id is used to match the individual validation jobs contained:

Response Valid IBAN

HTTP/1.1 200 OK
Content-Type: application/json
 
[
  {
    "id": 1,
    "valid": true,
    "iban": "DE37503240001000000524",
    "bic": "FTSBDEFAXXX",
    "bankname": "ABN AMRO Bank, Frankfurt Branch"
  },
  {
    "id": 2,
    "valid": false,
    "iban": "DE99999999999999999999",
    "bic": null
  }
]

Validate IBANs in Non-Blocking Batch Mode

This mode must be used if there are more than a small amount of IBANs that need to be validated at once. You post your processing request and poll for the result.

The endpoint to start a non-blocking task is POST /api/v2/Event/Actions. It needs to be called with the above endpoint for IBAN validation:

Request

POST /api/v2/Event/Actions HTTP/1.1
Host: connect-testing.secupay-ag.de
Content-Type: application/json
Authorization: Bearer htlu0l0m22rsesvh20f7i5d22i
Content-Length: 346
 
{
    "endpoint": "/Payment/Containers/me/validateSingleIban",
    "http_method": "POST",
    "items": [
        {
            "id": 1,
            "iban": "DE37503240001000000524",
            "bic": ""
        },
        {
            "id": 2,
            "iban": "DE99999999999999999999",
            "bic": ""
        }
    ]
}

It responds with HTTP status 200 OK, and the current Event Action details:

Response

HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
    "object": "event.actions",
    "id": "EAC_VQKMTJFKUT04ZD5JXDSM6JFXYNGS2Q",
    "status": "processing",
    "total": 2,
    "processed": 0,
    "created": "2024-04-15T14:06:46+02:00",
    "updated": null,
    "errors": [],
    "result": []
}

Using the returned Event Action ID, you can check the validation status:

Request

GET /api/v2/Event/Actions/EAC_VQKMTJFKUT04ZD5JXDSM6JFXYNGS2QHTTP/1.1
Host: connect-testing.secupay-ag.de
Content-Type: application/json
Authorization: Bearer htlu0l0m22rsesvh20f7i5d22i

Please wait a sufficient amount of time before checking the result!

When the status switches from "processing" to "complete", the process is finished:

Response

HTTP/1.1 200 OK
Content-Type: application/json
...
 
{
    "object": "event.actions",
    "id": "EAC_VQKMTJFKUT04ZD5JXDSM6JFXYNGS2Q",
    "status": "complete",
    "total": 2,
    "processed": 2,
    "created": "2024-04-15T14:06:46+02:00",
    "updated": "2024-04-15T14:06:46+02:00",
    "errors": [],
    "result": [
        {
            "id": 1,
            "valid": true,
            "iban": "DE37503240001000000524",
            "bic": "FTSBDEFAXXX",
            "bankname": "ABN AMRO Bank, Frankfurt Branch"
        },
        {
            "id": 2,
            "valid": false,
            "iban": "DE99999999999999999999",
            "bic": null
        }
    ]
}

Now that the IBANs have been successfully validated, the payout can be processed quickly.