Migration from Web Form V1

Overview

Migrating from Web Form V1 to Web Form V2 is straightforward. The overall flow remains familiar, but Web Form V2 introduces several enhancements not available in V1 — including bank selection, automatic interface management, improved callback handling (see For best results), and advanced customization options for branding and user experience (see White labeling).

Web Form V2 is an extension of the core finAPI Access API, using the same user authentication process. The request structures are very similar, with most parameters retaining their names, while response handling has been streamlined. A successfully created web form in V2 will return an HTTP 201 status code, including the web form URL in the response body — replacing the V1 behavior, which used a custom HTTP 451 code with the URL provided in the response headers.

Examples

Example bank connection import

Web form V1

Web Form V2

Request URL: POST https://live.finapi.io/api/v1/bankConnections/import

Request body

JSON

{
  "bankId": 280001,
  "name": "Bank connection",
  "interface": "XS2A",
  "skipBalancesDownload": false,
  "skipPositionsDownload": false,
  "loadOwnerData": false,
  "maxDaysForDownload": 365,
  "accountTypes": [
    "Checking",
    "Savings",
    "CreditCard",
    "Security",
    "Loan",
    "Membership",
    "Bausparen"
  ]
}

Response headers

CODE

..
location: https://live.finapi.io/webForm/g1u4I_310CkZHEHp9ICI5SUeDJVGYWJD33MfWohdniZ0xzNGj1PefcVe7_33Eqal5zcEQHWVNv7Iz6rjpWL5ByouwArK2HVW_fRuoldE9eGS0RPaNIDhnbwBdIK5KnEB
...

Response body

JSON

{
  "errors": [
    {
      "message": "23894699",
      "code": "WEB_FORM_REQUIRED",
      "type": "BUSINESS",
      "multiStepAuthentication": null
    }
  ],
  "date": "2025-05-13 13:30:32.512",
  "requestId": "selfgen-363b8655-63e2-4c95-97d0-d9ef84699802",
  "endpoint": "POST /api/v1/bankConnections/import",
  "authContext": "2063/1959409",
  "bank": "DEMO0001 - finAPI Test Bank (id: 280001, location: none)"
}

Request URL: POST https://webform-live.finapi.io/api/webForms/bankConnectionImport

Request body

JSON

{
  "bank": {
    "id": 280001
  },
  "bankConnectionName": "Bank connection",
  "allowedInterfaces": [
    "XS2A",
    "FINTS_SERVER",
    "WEB_SCRAPER"
  ],
  "skipBalancesDownload": false,
  "skipPositionsDownload": false,
  "loadOwnerData": false,
  "maxDaysForDownload": 365,
  "accountTypes": [
    "CHECKING",
    "SAVINGS",
    "CREDIT_CARD",
    "SECURITY",
    "MEMBERSHIP",
    "LOAN",
    "BAUSPAREN"
  ]
}

Response headers

N/A

Response body

JSON

{
  "id": "b03e606f-6ae5-4c96-9aad-c4c60a371065",
  "url": "https://webform-live.finapi.io/wf/b03e606f-6ae5-4c96-9aad-c4c60a371065",
  "createdAt": "2025-05-13T11:31:59.374+0000",
  "expiresAt": "2025-05-13T11:51:59.374+0000",
  "type": "BANK_CONNECTION_IMPORT",
  "status": "NOT_YET_OPENED"
}

Example money transfer

Web form V1

Web Form V2

For web form V1, creating a money transfer is split into 2 calls: creation and submission

Creation Request URL: POST https://live.finapi.io/api/v1/payments/moneyTransfers

Creation Request body

JSON

{
  "iban": "DE77533700080111111100",
  "executionDate": "2026-01-01",
  "moneyTransfers": [
    {
      "counterpartName": "Max Mustermann",
      "counterpartIban": "DE13700800000061110500",
      "counterpartBic": "DRESDEFF700",
      "counterpartAddress": {
        "street": "Pariser Platz",
        "houseNumber": "1",
        "city": "Berlin",
        "postCode": "10117",
        "country": "DE"
      },
      "amount": 99.99,
      "purpose": "Test Payment",
      "sepaPurposeCode": "OTHR",
      "endToEndId": "001100550526",
      "structuredRemittanceInformation": [
        "VS:501",
        "KS:9",
        "SS:1005"
      ]
    }
  ],
  "instantPayment": false
}

Creation response body

JSON

{
  "id": 7335698,
  "accountId": null,
  "iban": "DE77533700080111111100",
  "bankId": 280001,
  "type": "MONEY_TRANSFER",
  "amount": 99.99,
  "orderCount": 1,
  "status": "OPEN",
  "instructedExecutionDate": "2026-01-01",
  "instantPayment": false,
  "statusV2": "OPEN"
}

Submission URL: POST https://live.finapi.io/api/v1/payments/submit

Submission Request Body

JSON

{
  "paymentId": 7335698,
  "interface": "XS2A"
}

Response headers

CODE

..
location: https://live.finapi.io/webForm/qNuxRocY1kew5OSzEzfHYtoFQP0G9usklxC8S8kmSYY6D_EP_vNuV62d0JUrqMWVTIDSTYFjHOtKYP0v2ZIyJAOjmiXYG0C9yu77wClVgf8PwlQpbhuk5GcJK7qqFHyO
...

Response body

JSON

{
  "errors": [
    {
      "message": "23894883",
      "code": "WEB_FORM_REQUIRED",
      "type": "BUSINESS",
      "multiStepAuthentication": null
    }
  ],
  "date": "2025-05-13 13:51:57.051",
  "requestId": "selfgen-8bca4bab-ff68-4ccc-911c-e552bc74bcb7",
  "endpoint": "POST /api/v1/payments/submit",
  "authContext": "2063/1959409",
  "bank": "DEMO0001 - finAPI Test Bank (id: 280001, location: none)"
}

Request URL: POST https://webform-live.finapi.io/api/webForms/standalonePayment

Request body

JSON

{
  "sender": {
    "iban": "DE77533700080111111100"
  },
  "executionDate": "2026-01-01",
  "orders": [
    {
      "recipient": {
        "name": "Max Mustermann",
        "iban": "DE13700800000061110500",
        "bic": "DRESDEFF700",
        "address": {
          "street": "Pariser Platz",
          "houseNumber": "1",
          "city": "Berlin",
          "postCode": "10117",
          "country": "DE"
        }
      },
      "amount": {
        "value": 99.99,
        "currency": "EUR"
      },
      "purpose": "Test Payment",
      "sepaPurposeCode": "OTHR",
      "endToEndId": "001100550526",
      "structuredRemittanceInformation": [
        "VS:501",
        "KS:9",
        "SS:1005"
      ]
    }
  ],
  "instantPayment": false
}

Response headers

N/A

Response body

JSON

{
  "id": "2541d998-a3a5-4e59-b904-4b654f3a8c19",
  "url": "https://webform-live.finapi.io/wf/2541d998-a3a5-4e59-b904-4b654f3a8c19",
  "createdAt": "2025-05-13T11:59:17.453+0000",
  "expiresAt": "2025-05-13T12:19:17.453+0000",
  "type": "STANDALONE_PAYMENT",
  "status": "NOT_YET_OPENED"
}