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: Request body {
"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 ..
location: https://live.finapi.io/webForm/g1u4I_310CkZHEHp9ICI5SUeDJVGYWJD33MfWohdniZ0xzNGj1PefcVe7_33Eqal5zcEQHWVNv7Iz6rjpWL5ByouwArK2HVW_fRuoldE9eGS0RPaNIDhnbwBdIK5KnEB
...Response body {
"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: Request body {
"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 {
"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:
Creation Request body {
"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 {
"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: Submission Request Body {
"paymentId": 7335698,
"interface": "XS2A"
}
Response headers ..
location: https://live.finapi.io/webForm/qNuxRocY1kew5OSzEzfHYtoFQP0G9usklxC8S8kmSYY6D_EP_vNuV62d0JUrqMWVTIDSTYFjHOtKYP0v2ZIyJAOjmiXYG0C9yu77wClVgf8PwlQpbhuk5GcJK7qqFHyO
...Response body {
"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:
Request body {
"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 {
"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"
} |