Bank Account Verification Integration

Use this guide to integrate Bank Account Verification (BAV) into an API v2 workflow.

Before you begin

This guide extends the API v2 integration. Complete steps 1–5 of that guide before continuing.

Make sure you also have:

A workflow configured with Bank Account Verification
The correct workflow value for Create workflow
Handling for BAV product statuses

We recommend that you:

Configure webhooks to receive status updates
Use Get workflow status to retrieve the latest workflow state

Choose a verification method

Bank Account Verification supports two verification methods. The method used is determined by your workflow configuration.

Method	Description
Money Transfer	Confirms account ownership and identity consistency by having the client make a small reference payment from their bank account. Recommended for onboarding flows.
IBAN Verification	A lightweight check that confirms the IBAN is valid and associated with the client. Boosts conversion where full transfer confirmation is not required.

Confirm the verification method configured for your workflow with your Fourthline delivery manager.

Choose an integration type

Bank Account Verification supports two integration types. The integration type used is determined by your workflow configuration.

Integration type	Description
API-only	You control the BAV flow entirely in your own application or backend. Upload client data via the API before starting the workflow.
SDK	Fourthline captures client data through the SDK (App Drop-in, Web, or App Components). You create an SDK session after creating the workflow.

Confirm the integration type configured for your workflow with your Fourthline delivery manager.

Upload BAV data

Complete the uploads described in step 3 of the API v2 integration guide.

API reference:

Upload all required data before calling Start workflow.

Note

If your integration uses SDK capture, also complete step 4 (Create SDK session) of the API v2 integration guide.

Missing or invalid data can result in statuses such as:

kyc_required
failed with status code 7011

Monitor the payment status

In API v2, Bank Account Verification appears as Payments in products[].name on Get workflow status.

Track Payments.status using webhooks or Get workflow status.

`Payments.status`	What to do
`new`	Wait. The workflow has been created successfully.
`pending`	Wait. The client has initiated the transfer and a reference payment has been created.
`pending_verification`	Wait. The transfer was received and the reference payment is being processed.
`kyc_required`	The client's Identity Verification case was unsuccessful or does not exist. Create a new workflow that includes both Identity Verification and Bank Account Verification.
`completed`	The reference payment was successfully processed. No further action required.
`failed`	The reference payment failed. Check the accompanying status code. Create a new workflow for Bank Account Verification only.

Important

Use Payments.status to determine the outcome of the verification. Don't rely on workflowStatus alone.

A workflowStatus of completed does not mean the verification was successful — it means processing has finished. The product status can still be kyc_required or failed.

After receiving a webhook, call Get workflow status and inspect products[].name, products[].status, and products[].messages.

Webhook payload for Payments

In webhook events, Bank Account Verification is identified by details.name: "Payments".

When details.status is completed, the webhook payload includes a transferData object containing:

IBAN
Transfer reference
Amount and related fields

Other statuses do not include transferData.

Note

Treat each webhook as a signal to refresh workflow state. Always call Get workflow status after receiving a webhook before updating your application state or making business decisions.

Status codes

When Payments.status is failed, one or more of the following status codes may be present in products[].messages:

Status code	Description	Action
`7000`	The client did not complete the Bank Account Verification flow in time and it expired.	Create a new workflow for Bank Account Verification only.
`7011`	Fourthline did not receive the required data to complete the Bank Account Verification flow.	Check all mandatory uploads are completed before calling Start workflow, then create a new workflow.
`7012`	The information received from the bank does not match the client's Identity Verification case.	Create a new workflow for Bank Account Verification only.
`7021`	A problem occurred with the client's bank.	Wait for the next status notification before taking further action.

Test in sandbox

Use the following to test your BAV integration in sandbox:

Create test payment — simulate a reference payment within a BAV workflow without sending a real transfer
Get workflow status — confirm that status transitions occur as expected

Verify that:

Workflow status transitions occur as expected (new → pending → pending_verification → completed)
Webhooks are delivered and your handler routes details.name: "Payments" correctly
Your integration handles kyc_required and failed with each relevant status code
transferData is present in the webhook payload when details.status is completed

Troubleshooting

Symptom	Likely cause	Recommended action
`kyc_required` on BAV only	Identity Verification has not been completed for the provided `clientId`, or the IDV case was unsuccessful.	Create a new workflow that includes both Identity Verification and Bank Account Verification.
`failed` with code `7000`	The client did not complete the flow before it expired.	Create a new workflow for Bank Account Verification only.
`failed` with code `7011`	Required data was missing when the workflow was started.	Check all mandatory uploads are completed before calling Start workflow, then create a new workflow.
`failed` with code `7012`	The bank account details do not match the verified identity.	Create a new workflow for Bank Account Verification only.
`failed` with code `7021`	A problem occurred with the client's bank.	Wait for the next status notification before taking further action.
`workflowStatus` is `completed` but verification failed	`kyc_required` and `failed` are terminal product statuses that both map to `workflowStatus: completed`.	Always inspect `Payments.status` before onboarding a client or releasing funds.
`transferData` missing from webhook	`transferData` is only included when `details.status` is `completed`.	This is expected behaviour for other statuses.

FAQ

Does Bank Account Verification generate a CDD Report or risk code?

No. No risk code or CDD Report is generated for Bank Account Verification. Use the product status and any accompanying status codes to determine the outcome.

What is the difference between Money Transfer and IBAN Verification?

Money Transfer confirms account ownership and identity consistency by requiring the client to make a small reference payment from their bank account. It is the recommended method for onboarding flows where you need strong proof of ownership.

IBAN Verification is a lightweight method that confirms the IBAN is valid and associated with the client. It boosts conversion where a full transfer confirmation is not required.

The verification method used is determined by your workflow configuration. Contact your Fourthline delivery manager to confirm which method is enabled for your workflow.

Can I use BAV without Identity Verification?

Yes. Use the BAV-only workflow when the client has already completed Identity Verification with Fourthline. Pass the existing clientId when creating the workflow.

If no completed Identity Verification case exists for that client, Payments.status will become kyc_required. In that case, create a new workflow that includes both Identity Verification and Bank Account Verification, or complete Identity Verification first using the same clientId and then retry BAV only.

Why is workflowStatus completed even though my verification failed?

A workflowStatus of completed indicates that Fourthline has finished processing the workflow — it does not mean the verification outcome is positive.

Product statuses kyc_required and failed both map to workflowStatus: completed. Always inspect Payments.status and any accompanying status codes before onboarding a client or releasing funds.

What should I do if I receive status code 7021?

Status code 7021 means a problem occurred with the client's bank. Wait for the next status notification before taking action. If the issue persists, contact your Fourthline delivery manager.

Support

For questions about your workflow configuration or Bank Account Verification setup, contact your Fourthline delivery manager.