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:

• type – the type of variable recurring payment
• 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 (not required for fortnight periodic limit. This defaults to consent)

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": {
      "type": "sweeping",
      "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
  }
}

VRP Mandate Cancellations

VRP mandates can be cancelled by the customer either via their banking app or through the hosted Acquired.com revocation flow. Once cancelled, no further payments can be initiated under that mandate — even if the mandate limits have not been reached.

VRP Mandate Cancellation at Bank

Customers can revoke consent directly from their bank at any time.

When this happens:

• The bank cancels the VRP mandate
• Acquired will send a mandate_cancelled webhook notification
• You should update your internal customer billing state accordingly

We recommend monitoring cancellation webhooks in real time and pausing any scheduled billing immediately. This ensures a seamless customer experience and helps avoid failed payment attempts.

VRP Mandate Cancellation via Hosted Flow

In addition to cancellation through the bank, merchants must provide customers with the option to cancel a VRP mandate through a hosted Acquired.com journey.

To do this, redirect the customer to the VRP revocation URL for your environment:

The hosted revocation flow:

1. Displays mandate and payee details
2. Allows the customer to confirm cancellation
3. Cancels the mandate via Acquired’s internal VRP cancellation API
4. Sends a mandate_cancelled webhook
5. Redirects the customer back to your application

VRP mandates cannot be cancelled via the merchant API. They must be cancelled by the end-user through their bank or the hosted Acquired.com revocation page.