Skip to content
BTC Direct

Resolves a customer IBAN to the Pay by Bank bank(s) behind it, so the picker can pre-select the customer's own bank. A POST on purpose: an IBAN is PII and must never appear in URL paths or access logs. All resolution logic (BIC lookup, catalog matching) lives in Latinum; this endpoint proxies Latinum's typed response.

POST
/api/v2/buy/pay-by-bank/banks/by-iban

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
object
iban
required

The customer IBAN to resolve to a bank.

string
nullable
Example
NL37BUNQ2025406444
flow
string
Allowed values: one-off recurring

Responses

Section titled “ Responses ”

200

Section titled “200 ”

The bank(s) the IBAN resolved to, with the resolution outcome.

object
outcome
required
string
Allowed values: match candidates none
country
required

ISO 3166-1 alpha-2 country code derived from the IBAN; null when it could not be derived.

string
nullable
Example
NL
banks
required

The bank(s) the IBAN resolved to: one for match, several for candidates, empty for none.

Array<object>
default:
object
bankId
required

Unique identifier of the bank.

string
Example
ABNANL2A
name
required

Display name of the bank.

string
Example
ABN AMRO
country
required

ISO country code of the bank.

string
Example
NL
supportsOneOff
required

Whether the bank supports one-off payment initiation (PIS).

boolean
Example
true
supportsRecurring
required

Whether the bank supports recurring payment initiation (PIS_RECURRING).

boolean
bic
required

BIC(s) of the bank, for matching against a customer IBAN. Empty when none are published.

Array<string>
default:
Example
[
  "ABNANL2A"
]
logo

Central logo id for the bank, resolved by Latinum (banks of one chain share an id). Render the logo asset keyed by this id; null when the bank has no BIC to derive it from.

string
nullable
Example
ing
requiredInput
required

Extra input fields this bank requires before a Pay by Bank session can be created for it. Empty when the bank requires none.

Array<object>
default:
object
name
required

Machine name of the field; used as the request key when submitting the collected value on session create.

string
Example
debtorIban
type
required

Input type hint for rendering and client-side validation of the field.

string
Example
iban
label
required

Human-readable label to render next to the input.

string
Example
IBAN
description

Longer help text for the field; null when the bank provides none.

string
nullable
Example
The IBAN of the account the payment is made from.
example

Example value to show as a placeholder; null when the bank provides none.

string
nullable
Example
NL37BUNQ2025406444

400

Section titled “400 ”

A list of possible errors for this endpoint.

object
code
required
string
Allowed values: ER056 ER113 ER800 ER801 ER802 ER803 ER805 ER806 ER999
message
required
string
solution
required
string
Example
{
  "errors": {
    "ER056": {
      "code": "ER056",
      "message": "Invalid IBAN number provided.",
      "solution": "Provide a valid IBAN number."
    },
    "ER113": {
      "code": "ER113",
      "message": "No IBAN account provided.",
      "solution": "Provide a valid IBAN account."
    },
    "ER800": {
      "code": "ER800",
      "message": "Authorization token is invalid.",
      "solution": "Provide a valid authorization token."
    },
    "ER801": {
      "code": "ER801",
      "message": "Authorization token has expired.",
      "solution": "Request a new authorization token."
    },
    "ER802": {
      "code": "ER802",
      "message": "Authorization token not found.",
      "solution": "Provide an authorization token."
    },
    "ER803": {
      "code": "ER803",
      "message": "Multiple authorization methods used.",
      "solution": "Use exactly one authorization method."
    },
    "ER805": {
      "code": "ER805",
      "message": "API key is invalid.",
      "solution": "Provide a valid API key."
    },
    "ER806": {
      "code": "ER806",
      "message": "API key not found.",
      "solution": "Provide an API key."
    },
    "ER999": {
      "code": "ER999",
      "message": "A general error has occurred. Please contact our support team.",
      "solution": "Contact our support team."
    }
  }
}