Guides

This is the highest-effort integration. Consider starting with Hosted Payment Pages to validate your integration - the underlying API is identical. See how all of our integration types compare.

Supports: Direct Debit, Instant Bank Pay, VRP.

Best for

White-label or embedded product requirements
Complex, multi-step user journeys
Deep integration with your application
Full control over UX and brand experience

How it works

Build your own UI for collecting customer and bank account details
Use the Billing Requests API to create and progress through the payment flow
Call API actions to collect customer details, collect bank account information, and confirm
Handle all states, errors, and edge cases in your application

What you need to handle:

Input validation and error messaging
Scheme-specific bank account fields per country
Compliance requirements (e.g., Direct Debit Guarantee display)
Loading states and timeouts
Mobile responsiveness

Step-by-step guide

Applies to all flows

curl -X POST https://api.gocardless.com/billing_requests/BRQ0000301/actions/collect_customer_details \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "customer": {
        "email": "frank.osborne@example.com",
        "given_name": "Frank", "family_name": "Osborne"
      },
      "customer_billing_detail": {
        "address_line1": "27 Acer Road", "city": "London",
        "postal_code": "E8 3GX", "country_code": "GB"
      }
    }
  }'

Response: Billing Request with collect_customer_details marked completed.

Applies to all flows. Required fields vary by country and scheme. Example for UK (Bacs / Faster Payments):

curl -X POST https://api.gocardless.com/billing_requests/BRQ0000301/actions/collect_bank_account \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "country_code": "GB",
      "account_holder_name": "Frank Osborne",
      "account_number": "55779911",
      "branch_code": "200000"
    }
  }'

Response: Billing Request with collect_bank_account marked completed.

Applies to: all flows including mandates (Mandate-only flow and Payment + Mandate flow The customer confirms their consent to set up the mandate. No request body required.

curl -X POST https://api.gocardless.com/billing_requests/BRQ0000301/actions/confirm_payer_details \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response: Billing Request with collect_bank_account marked completed.

{ "billing_requests": { "id": "BRQ0000301", "status": "ready_to_fulfil",
  "actions": [
    { "type": "collect_customer_details", "required": true, "completed": true },
    { "type": "collect_bank_account", "required": true, "completed": true },
    { "type": "confirm_payer_details", "required": true, "completed": true }
  ] } }

Applies to: all flows including payments (Payment-only flow and Payment + Mandate flow Identify the customer's bank for the open banking authorisation. Use the list institutions endpoint to present a bank picker to the customer.

curl -X POST https://api.gocardless.com/billing_requests/BRQ0000302/actions/select_institution \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "institution": "MONZO_MONZGB2L",
      "country_code": "GB"
    }
  }'

Response: Billing Request with select_institution marked completed.

Applies to: all flows including payments (Payment-only flow and Payment + Mandate flow.

curl -X POST https://api.gocardless.com/bank_authorisations \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_authorisations": {
      "redirect_uri": "https://yoursite.com/payment-complete",
      "links": { "billing_request": "BRQ0000302" }
    }
  }'

Response:

{
  "bank_authorisations": {
    "id": "BAU0000101",
    "url": "https://pay.gocardless.com/obauth/BAU0000101",
    "redirect_uri": "https://yoursite.com/payment-complete",
    "expires_at": "2024-06-01T18:15:00.000Z",
    "links": { "billing_request": "BRQ0000302" }
  }
}

Applies to: Mandate-only flow Once the Billing Request status is ready_to_fulfil, call the fulfil action to activate the mandate.

curl -X POST https://api.gocardless.com/billing_requests/BRQ0000301/actions/fulfil \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response:

{
  "billing_requests": {
    "id": "BRQ0000301",
    "status": "fulfilled",
    "links": { "mandate_request_mandate": "MD0000301" }
  }
}

Event	Meaning	Applies to
billing_requests.fulfilled	Billing Request completed	All flows
mandates.active	Mandate is active and ready	Mandate-only, payment + mandate
payments.confirmed	Instant Bank Pay payment settled	Payment-only, payment + mandate
payments.failed	Payment failed	Payment-only, payment + mandate
mandates.cancelled	Mandate cancelled	Mandate-only, payment + mandate

Need help?

Connect as a partner

Guides

Custom Payment Pages

What are Custom Payment Pages?

Best for

How it works

What you need to handle:

Step-by-step guide

Create a billing request

Collect Customer Details

Collect a bank account

Confirm payer details

Select Institution

Create a bank authorisation

Redirect customer to their bank

Fulfill the billing request

Handle Webhooks