{
  "openapi": "3.1.0",
  "info": {
    "title": "BAV (Verification of Payee) API",
    "version": "3",
    "summary": "Ask the bank that holds an IBAN whether a given name is the name on that account.",
    "description": "Part of the Bank Account Verification service of IBAN.com. One request sends an IBAN and an account\nholder name to the bank through the Verification of Payee (VoP) scheme and returns the bank's verdict:\n`yes`, `partial`, `no` or `unavailable`.\n\nFull documentation with recorded examples: https://developer.iban.com/bav-api\n\nEvery completed verification (HTTP 200) uses one query from the BAV balance, and so do\n`INVALID_IBAN_CHECKSUM` (400) and `INTERNAL_SERVER_ERROR:UNERSP` (500); requests refused before the\nbank is identified use none. Allow 180 s before timing out: a bank may take up to three minutes.\n",
    "termsOfService": "https://www.iban.com/terms",
    "license": {
      "name": "Proprietary — IBAN.com Terms & Conditions",
      "url": "https://www.iban.com/terms"
    },
    "contact": {
      "name": "IBAN.com support",
      "url": "https://clients.iban.com/support"
    }
  },
  "servers": [
    {
      "url": "https://api.iban.com/clients/api/verify/v3",
      "description": "Production. Each completed verification uses one query."
    },
    {
      "url": "https://sandbox.iban.com/clients/api/verify/v3",
      "description": "Sandbox with fixed answers (key `testkey`); contacts no bank and uses no queries."
    }
  ],
  "security": [
    {
      "ApiKeyHeader": []
    }
  ],
  "tags": [
    {
      "name": "Verification",
      "description": "Verification of Payee through the account's bank."
    }
  ],
  "paths": {
    "/": {
      "post": {
        "tags": [
          "Verification"
        ],
        "operationId": "verifyPayee",
        "summary": "Verify that a name matches the holder of an IBAN",
        "description": "The IBAN is cleaned (spaces and any other character that is not a letter or digit removed, letters\nupper-cased), its country and check digits are tested, the bank is identified and the request is sent\nto that bank. Supported countries: AT BE HR CY EE FI FR DE GR IE IT LV LT LU MT NL PT SK SI ES GB.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerificationRequest"
              },
              "examples": {
                "match": {
                  "summary": "Published donation account of the German Red Cross",
                  "value": {
                    "IBAN": "DE63370205000005023307",
                    "name": "Deutsches Rotes Kreuz e.V"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The verification was carried out. The outcome is in `result.name_match`; `error` carries the\nstatus code of the verdict (`\"\"`, `NAME_PARTIAL_MATCH`, `NAME_NOT_MATCH`,\n`VERIFICATION_NOT_SUPPORTED`, `VOP_REQUEST_FAILED`). `query.success` is always `true` here.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationResponse"
                },
                "examples": {
                  "match": {
                    "summary": "Name matches (recorded 8 Oct 2026)",
                    "value": {
                      "query": {
                        "IBAN": "DE63370205000005023307",
                        "name": "Deutsches Rotes Kreuz e.V",
                        "success": true
                      },
                      "result": {
                        "valid": true,
                        "name_match": "yes",
                        "bic": "BFSWDE33XXX"
                      },
                      "error": ""
                    }
                  },
                  "partial": {
                    "summary": "Close match (recorded 8 Oct 2026)",
                    "value": {
                      "query": {
                        "IBAN": "IT12T0623003204000030737371",
                        "name": "Associazione della Croce Rossa Italiana – ODV",
                        "success": true
                      },
                      "result": {
                        "valid": true,
                        "name_match": "partial",
                        "bic": "CRPPIT2PXXX"
                      },
                      "error": "NAME_PARTIAL_MATCH"
                    }
                  },
                  "no_match": {
                    "summary": "Wrong name for an existing account (recorded 8 Oct 2026)",
                    "value": {
                      "query": {
                        "IBAN": "DE63370205000005023307",
                        "name": "John Doe",
                        "success": true
                      },
                      "result": {
                        "valid": false,
                        "name_match": "no",
                        "bic": "BFSWDE33XXX"
                      },
                      "error": "NAME_NOT_MATCH"
                    }
                  },
                  "unavailable": {
                    "summary": "No verdict from the bank network (recorded 8 Oct 2026)",
                    "value": {
                      "query": {
                        "IBAN": "FR7630027174110002636660114",
                        "name": "Fondation pour le Logement des Défavorisés",
                        "success": true
                      },
                      "result": {
                        "valid": true,
                        "name_match": "unavailable",
                        "bic": "CMCIFRPPXXX"
                      },
                      "error": ""
                    }
                  },
                  "not_supported": {
                    "summary": "Bank or account outside the VoP scheme (shape from the API source; not recorded on production)",
                    "value": {
                      "query": {
                        "IBAN": "NL91ABNA0417164300",
                        "name": "John Doe",
                        "success": true
                      },
                      "result": {
                        "valid": null,
                        "name_match": "unavailable",
                        "bic": "ABNANL2AXXX"
                      },
                      "error": "VERIFICATION_NOT_SUPPORTED"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Refused before any bank was contacted: `MISSING_API_KEY`, `INVALID_JSON`, `MISSING_INPUT_IBAN`,\n`MISSING_INPUT_NAME`, `COUNTRY_NOT_SUPPORTED`, `INVALID_IBAN_CHECKSUM` (the last one uses a query).\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RefusedResponse"
                },
                "examples": {
                  "checksum": {
                    "value": {
                      "error": "INVALID_IBAN_CHECKSUM"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Key, address or subscription problem: `INVALID_API_KEY`, `IP_NOT_ALLOWED`, `USER_NOT_ALLOWED`,\n`SUBSCRIPTION_EXPIRED`, `NO_CREDITS_AVAILABLE`. Stop sending until it is fixed.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RefusedResponse"
                },
                "examples": {
                  "wrong_key": {
                    "value": {
                      "error": "INVALID_API_KEY"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "The request was not a POST (`METHOD_NOT_ALLOWED`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RefusedResponse"
                },
                "examples": {
                  "get": {
                    "value": {
                      "error": "METHOD_NOT_ALLOWED"
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "The `Content-Type` is not `application/json` or the header is missing (`UNSUPPORTED_FORMAT`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RefusedResponse"
                },
                "examples": {
                  "form": {
                    "value": {
                      "error": "UNSUPPORTED_FORMAT"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "More than 20 requests per second. Rejected by the web server before reaching the API, not charged; the body is a small HTML page, there is no `Retry-After` header.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "`INTERNAL_SERVER_ERROR:BNFDBS` — the bank code in the IBAN is not in the bank directory (not charged,\ndo not resend unchanged); `INTERNAL_SERVER_ERROR:UNERSP` — the request to the bank network failed\n(uses a query, retry later); other tags are unexpected errors. Match on the prefix `INTERNAL_SERVER_ERROR`.\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RefusedResponse"
                },
                "examples": {
                  "bank_not_found": {
                    "value": {
                      "error": "INTERNAL_SERVER_ERROR:BNFDBS"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your personal key, shown under API Access in the client area. Sandbox key is `testkey`."
      }
    },
    "schemas": {
      "VerificationRequest": {
        "type": "object",
        "required": [
          "IBAN",
          "name"
        ],
        "properties": {
          "IBAN": {
            "type": "string",
            "description": "IBAN of the account to verify, in a supported country. Spaces and other separators are removed and letters upper-cased before the checks.",
            "examples": [
              "DE63370205000005023307",
              "DE63 3702 0500 0005 0233 07"
            ]
          },
          "name": {
            "type": "string",
            "description": "Name the account should be held under — first and last name for a person, the legal name for a company. UTF-8.",
            "examples": [
              "Deutsches Rotes Kreuz e.V"
            ]
          }
        }
      },
      "VerificationResponse": {
        "type": "object",
        "required": [
          "query",
          "result",
          "error"
        ],
        "properties": {
          "query": {
            "type": "object",
            "required": [
              "IBAN",
              "name",
              "success"
            ],
            "properties": {
              "IBAN": {
                "type": "string",
                "description": "The IBAN as checked (cleaned, upper case)."
              },
              "name": {
                "type": "string",
                "description": "The name as sent, unchanged."
              },
              "success": {
                "type": "boolean",
                "description": "`true` for every 200 response."
              }
            }
          },
          "result": {
            "type": "object",
            "required": [
              "valid",
              "name_match",
              "bic"
            ],
            "properties": {
              "valid": {
                "type": [
                  "boolean",
                  "null"
                ],
                "description": "Whether the IBAN and the name are a valid pair: `true` for a match, a partial match and a verdict-less\nanswer; `false` when the bank rejected the pair (`NAME_NOT_MATCH`); `null` when no verdict could be\nobtained (`VERIFICATION_NOT_SUPPORTED`, `VOP_REQUEST_FAILED`).\n"
              },
              "name_match": {
                "type": "string",
                "enum": [
                  "yes",
                  "partial",
                  "no",
                  "unavailable"
                ],
                "description": "The bank's verdict on the name."
              },
              "bic": {
                "type": "string",
                "minLength": 11,
                "maxLength": 11,
                "description": "BIC of the bank that issued the IBAN, 11 characters (head office or branch)."
              }
            }
          },
          "error": {
            "type": "string",
            "enum": [
              "",
              "NAME_PARTIAL_MATCH",
              "NAME_NOT_MATCH",
              "VERIFICATION_NOT_SUPPORTED",
              "VOP_REQUEST_FAILED"
            ],
            "description": "Status code of the verdict; empty for a match and for a verdict-less answer."
          }
        }
      },
      "RefusedResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Upper-case error code; `INTERNAL_SERVER_ERROR` is followed by a colon and an internal tag.",
            "examples": [
              "INVALID_IBAN_CHECKSUM",
              "INVALID_API_KEY",
              "INTERNAL_SERVER_ERROR:BNFDBS"
            ]
          }
        },
        "additionalProperties": false
      }
    }
  }
}