Validate bank account details before you generate a quote or execute a transaction so you can reduce failed payouts.

⏱️
Time to integrate: Most teams can validate this endpoint in under 10 minutes once they know the provider, account number, and country or routing context required for the payout rail they use.

What this endpoint does

Use this endpoint to resolve and validate bank account details before funds are sent.

This step helps confirm that the destination details you collected are internally consistent and usable for the intended payout flow.

In practical terms, this endpoint helps reduce failed transactions, operational escalations, and recipient-facing payout delays.

When to call this endpoint

Call this endpoint when you need to:

validate a bank account before saving or using it
confirm account details before generating a quote
reduce payout failures caused by invalid provider or routing combinations
support internal review for beneficiary account setup

Use this endpoint after you create the beneficiary and before you execute a live payout flow that depends on bank account accuracy.

Why bank account resolution matters

Saving a beneficiary account does not always guarantee that the payout destination is ready for execution.

Bank account resolution adds an extra validation step so your team can:

catch formatting issues earlier
detect invalid provider or account combinations
reduce failed payouts and support tickets
improve recipient confidence before funds are sent

For payment operations teams, this is one of the most valuable pre-execution checks in the payout flow.

Authentication

Send your API key in the x-api-key header on every request.

Item	Value
Authentication method	API key
Required header	`x-api-key`
Rate limit scope	Per API key

Recommended workflow

Use this endpoint in the core payout preparation sequence:

Fetch organization accounts.
Check verification status.
Create a beneficiary.
Add a beneficiary account.
Resolve bank account details.
Generate a quote.
Execute the transaction.

If your payout flow does not use bank rails, this step may not apply.

What data to prepare before resolving a bank account

Before sending the request, collect the inputs required by the payout rail.

At minimum, your team should confirm:

the account number or destination identifier
the provider or bank code if required
the country or corridor context if required
the beneficiary or destination this validation applies to
the currency or network context if required by the rail

⚠️
Needs confirmation: Exact request fields, supported providers, country requirements, field formats, and whether beneficiary context is required should be confirmed in the API definition.

Validation guidance

Before calling this endpoint, validate the bank details in your own system first.

Recommended checks:

trim spaces and normalize account numbers before submission
verify the correct provider or bank code is selected
confirm the country and currency match the intended payout corridor
require the operator or end user to review the entered account details before resolution

If you collect bank details in a UI, run this endpoint before allowing the user to continue to quote generation or execution.

How to use the response

Use the response to decide whether the destination can proceed to the next stage.

You will typically use the result to:

confirm the account details appear valid
compare the resolved result against the recipient details you expected
block quote generation or execution if the result is inconsistent
store resolution output for support and audit review

Recommended decision flow

If resolution succeeds:

store the validated details your workflow needs
continue to quote generation
proceed to transaction execution only after final review

If resolution fails or looks inconsistent:

stop the payout flow
ask for corrected destination details
rerun validation before saving or executing the payout

Common use cases

Validate a newly added beneficiary account

After attaching a bank destination to a beneficiary, resolve the account details before allowing the account to be used for live payouts.

Validate recipient-entered payout details

Use this endpoint in an onboarding or payout form to reduce manual review and catch incorrect banking details early.

Support operations review

Use resolution results to help operations teams verify that destination details look correct before high-value or first-time payouts.

Production notes

Before using this endpoint in production:

Decide whether bank account resolution is mandatory for all bank payouts.
Define what your team will do when resolution fails or returns unexpected data.
Log who submitted the account for validation and when.
Store only the minimum resolution result your workflow requires.

For high-value or regulated payout flows, bank account resolution should usually be treated as a required control, not an optional enhancement.

Common failure cases

Authentication fails

Check these items first:

the x-api-key header is present
the API key belongs to the intended environment
the base URL is correct

Validation fails

If the endpoint rejects the request:

verify all required fields are present
verify the account number format
verify the provider or bank code
verify the country or currency context for the intended rail

The resolved details do not match expectations

If the response returns unexpected account details:

do not proceed to execution automatically
compare the resolved data against the intended recipient
request correction or manual review before continuing

The account resolves successfully but the payout still fails later

Bank account resolution improves payout quality, but it does not guarantee transaction success.

Next check:

quote validity and execution timing
transaction limits
source account funding
transaction-specific validation rules

⚠️
Needs confirmation: Exact response fields, match semantics, error codes, and whether successful resolution guarantees any downstream eligibility should be confirmed from the API schema and backend behavior.

Enterprise implementation notes

Access control

Restrict bank account resolution to trusted backend services or approved operational systems.

Auditability

Record:

beneficiary ID or destination reference
account number reference or masked identifier
provider or routing context
validation timestamp
initiating service or user

Data handling

Treat bank account details and resolution output as sensitive data. Mask or minimize storage wherever possible and align retention with your compliance requirements.

Troubleshooting checklist

Use this checklist if bank validation is blocking your payout flow:

Confirm authentication with x-api-key.
Confirm the provider, bank code, or routing context is correct.
Confirm the account number is formatted correctly.
Confirm the country and currency match the intended payout corridor.
Compare the resolved output against the expected recipient details.
Continue to quote generation only after the result is acceptable.

Recommended next endpoints

After bank account resolution, continue with:

Related pages

Add Beneficiary Account

Attach the payout destination before you validate bank account details.

Generate Quote

Continue to pricing after the destination details are validated.

Execute Transaction

Finalize the payout only after validation, pricing, and funding checks are complete.