Skip to main content

Open banking bank preselection

Use bank preselection when you want the customer to choose a bank in your own checkout UI before you create a Radom open-banking checkout session.

For example, you might show a "Pay with Revolut" button, create the checkout session with that selected bank, and then redirect the customer into the Radom-hosted bank payment flow.

Radom exposes provider-neutral bank identifiers. Use the Radom id returned by the bank catalogue. Do not display, store, or pass underlying provider bank IDs.

Flow​

  1. Decide which market and currency your checkout supports.
  2. Query Radom's bank catalogue.
  3. Show eligible banks in your UI.
  4. Create the checkout session with gateway.openBanking.bankId.
  5. Redirect the customer to the checkout session URL.
  6. Track progress from the checkout session response and final success with the managedPayment webhook.

List available banks​

Call the bank catalogue endpoint for the market and currency you want to support:

curl "https://api.radom.com/open_banking/banks?market=DE&currency=EUR&search=Revolut" \
  -H "Authorization: Bearer <api-key>"

Query parameters:

ParameterDescription
marketOptional country or market code, such as DE, FR, or NL.
currencyOptional currency filter, such as EUR or GBP.
capabilityOptional capability filter. Defaults to pis, which is the payment-initiation capability used for checkout.
searchOptional bank-name search term.

Example response:

{
  "banks": [
    {
      "id": "ob_6f3d9e0f4c2a4b7e8d9c1a2b3c4d5e6f",
      "name": "Example Bank",
      "logoUrl": null,
      "markets": ["DE"],
      "currencies": ["EUR"],
      "capabilities": ["pis"],
      "supportedPaymentSchemes": ["Sepa Credit", "Sepa Instant"]
    }
  ]
}

The id is safe to store and pass back to Radom. Bank availability can change, so refresh the catalogue periodically instead of hardcoding a permanent bank list.

logoUrl can be null. If you show bank logos, use assets Radom makes available or assets you have rights to use.

Create a checkout session with a selected bank​

Pass the Radom bank id as gateway.openBanking.bankId when creating the checkout session.

{
  "total": 100.00,
  "currency": "EUR",
  "gateway": {
    "openBanking": {
      "email": "customer@example.com",
      "bankId": "ob_6f3d9e0f4c2a4b7e8d9c1a2b3c4d5e6f"
    }
  },
  "successUrl": "https://example.com/checkout/success",
  "cancelUrl": "https://example.com/checkout/cancel"
}

If bankId is omitted, checkout session creation behaves as before and the customer chooses their bank during the hosted Radom flow.

Multi-market banks​

Some banks operate in multiple countries and can have different local availability or payment schemes. If the catalogue response includes more than one markets value for the same bank, pass gateway.openBanking.market as well:

{
  "total": 100.00,
  "currency": "EUR",
  "gateway": {
    "openBanking": {
      "email": "customer@example.com",
      "bankId": "ob_6f3d9e0f4c2a4b7e8d9c1a2b3c4d5e6f",
      "market": "DE"
    }
  },
  "successUrl": "https://example.com/checkout/success",
  "cancelUrl": "https://example.com/checkout/cancel"
}

If you do not know the customer's market, collect it before showing bank-specific buttons or let the customer choose their bank inside the Radom-hosted checkout flow.

Error handling​

Bank catalogue data is dynamic. A selected bank can become unavailable for the requested market, currency, or checkout configuration.

If a selected bank is not available, Radom returns a validation error and does not create the checkout session. Refresh the catalogue and ask the customer to choose another bank.

If the selected bank is available in multiple markets and you did not pass gateway.openBanking.market, Radom asks you to provide the market.

If the bank catalogue is temporarily unavailable, retry the catalogue request later or fall back to creating a checkout session without bankId, letting the customer choose their bank in the hosted flow.

Status handling after redirect​

Bank preselection only controls which bank is selected at checkout start. It does not change settlement timing.

After the customer returns from their bank, keep checking the checkout session and keep listening for final webhooks:

  • Read openBankingPaymentData.status on the checkout session for progress such as processing, waiting_for_payment, authorized, and finalizing.
  • Use the final managedPayment webhook before fulfilling an order.
  • Use the refund webhook for refund completion. For open-banking refunds, the payload can include openBankingPaymentData.status with refunded.
  • Use paymentScheme and instantPaymentScheme to distinguish standard rails from instant rails when explaining status to customers or support teams.

For standard rails such as SEPA Credit, the customer may have sent the transfer before Radom has received it. Show a sent or processing state, not final success, until Radom confirms the payment.