Pay by Bank in Hosted Checkout

Use this for: one-off or recurring Open Banking payments via Pay by Bank.

Hosted Checkout supports two types of Pay by Bank transactions:

• Single Immediate Payments (SIPs) – one-off payments authorised by the customer in real time.
• Variable Recurring Payments (VRPs) – ongoing payments made under a pre-approved mandate with configurable limits.

The Pay by Bank type depends on the checkout scenario you configure:

One-off Payment (SIP)

Use this for: taking a single Open Banking payment from a customer.

For Pay by Bank (SIP), no additional fields are required beyond the standard transaction fields. The request structure is identical to one-off payments made with cards or wallets. See the One-off Payments page for full details.

How it Works

1. The customer selects Pay by Bank at checkout.
2. They are redirected to their banking app or online banking portal.
3. The customer reviews and authorises the transaction.
4. The bank processes the payment instantly via Faster Payments.
5. Hosted Checkout confirms the outcome via status_update webhook and form POST.

Funds are transferred in real time, and no credentials are stored for future use.

Variable Recurring Payments (VRPs)

VRPs allow you to set up a mandate that authorises future payments within defined limits (amounts and frequency).

Unlike SIPs, which are single transactions, VRPs follow a two-step flow:

1. Mandate Setup The customer is redirected through their bank’s Open Banking flow to authorise a VRP mandate. The mandate includes:

   • Maximum per-payment amount
   • Periodic limits (e.g. £100 per month)
   • Payee account details

   Once authorised, a mandate_active webhook confirms the mandate is live.

2. Payment Initiation (outside Hosted Checkout) Future payments are initiated by you via the Payments API. No customer interaction is required, as long as payments remain within the agreed mandate parameters.

ℹ️

Note: Hosted Checkout only supports the mandate setup portion of VRPs. All VRP payments — including the first payment in a Charge + Store scenario — must be initiated separately via the Payments API.

VRP Scenarios

VRPs in Hosted Checkout use the same baseline fields as when storing credentials for cards and digital wallets, plus VRP mandate details.

If you’re offering VRPs, these fields are required in addition to the baseline card/digital wallet fields above:

Note: transaction.currency must be set togbp to offer VRPs via Pay by Bank. Other payment types support additional currencies

VRP Mandate Requirements

To successfully offer VRPs via Hosted Checkout, within the configuration.variable_recurring_payment you must include:

• maximum_payment_amount – the cap per payment
• At least one periodic limit (e.g. day, week, month) containing:
  • maximum_amount – cap for that period
  • alignment – calendar or consent
  • currency – must match transaction.currency

These parameters define the scope of the customer’s authorisation and must be honoured in every payment request under the mandate. If any of these fields are missing or malformed, the /payment-links API request will fail.

⚠️

Monzo does not support the day, week fortnight or half_year periodic limits. They also do not support the calendar option for alignment. If these values are included in your request, Monzo will be removed from the list of banks available for customers to select.

Store Credentials Only vs. Charge + Store Credentials

The distinction between Store Credentials Only and Charge + Store Credentials depends on a combination of transaction.capture and transaction.amount:

⚠️

Important: For Pay by Bank, Hosted Checkout never takes a payment during mandate setup. All payments — including the first one in a Charge + Store flow — must be created via the Payments API.

Example Request

The payload below shows the baseline VRP structure. Toggle transaction.capture to switch between Store Credentials Only and Charge + Store Credentials scenarios:

{
  "transaction": {
    "order_id": "vrp-001",
    "currency": "gbp",
    "amount": 10.00,
    "capture": false   // Store Credentials Only -> set to true for Charge + Store
  },
  "is_recurring": true,
  "payment": {
    "reference": "Monthly Plan"  // optional; defaults to Company Name if omitted
  },
  "configuration": {
    "variable_recurring_payment": {
      "per_payment": {
        "amount": 100,
        "currency": "GBP"
      },
      "periodic_limit": {
        "month": {
          "maximum_amount": 300,
          "alignment": "calendar",
          "currency": "GBP"
        }
      }
    }
  },
  "recurring": {
    "term": {
      "start_date": "2025-09-01",
      "end_date": "2026-09-01"
    }
    // term is optional — omit if you don't need a validity window
  }
}