Guides

Similarly to the previous three guides above, we will also be able to use the Billing Request with Actions in order to request an Instant Bank payment and create a Direct Debit mandate. We'll be able to create both requests at the same time within one flow.

By combining both a payment_request as well as a mandate_request in the API request, we'll be able to omit having to pass the customer's bank account details, as those would be retrieved automatically from the Instant Bank payment.

In order to complete all the actions on the mandate_request we'll need to pass all required customer_billing_details including the payer's billing address.

The customer's email is a mandatory field for Payment Providers using our Embed product!

POST https://api.gocardless.com/billing_requests/create_with_actions HTTP/1.1
Content-Type: application/json
{
    "billing_request_with_actions": {
        "payment_request": {
            "description": "Instant Bank Payment",
            "amount": 123,
            "currency": "GBP",
            "metadata": {
                "internal_payment_id": "ID123"
            }
        },
        "mandate_request": {
            "currency": "GBP",
            "scheme": "bacs",
            "verify": "recommended",
            "metadata": {
                "mandate_metadata": "ID456"
            }
        },
        "actions": {
            "collect_customer_details": {
                "customer": {
                    "given_name": "Alice",
                    "family_name": "Smith",
                    "email": "alice.smith@example.com",
                    ...
                },
                "customer_billing_detail": {
                    "address_line1": "Street 123",
                    "city": "London",
                    ...
                }
            },
            "select_institution": {
                "institution": "INSTITUTION_ID123",
                "country_code": "GB"
            },
            "bank_authorisation_redirect_uri": "https://pay.gocardless.com/billing/static/thankyou",
            "create_bank_authorisation": true
        },
        "links": {
            "creditor": "CR123"
        }
    }
}

HTTP/1.1 200 OK
Content-Type: application/json
{
    "billing_request_with_actions": {
        "billing_requests": {
            "id": "BRQ123",
            "created_at": "2025-12-16T14:58:06.643Z",
            "status": "pending",
            "mandate_request": {
                ...
                "currency": "GBP",
                ...
            },
            "payment_request": {
                "description": "Penny payment",
                "currency": "GBP",
                "amount": 123,
                "scheme": "faster_payments",
                ...
            },
            ...
            "links": {
                "customer": "CU123",
                ...
                "creditor": "CR123
                ...
            },
            ...
            "bank_authorisations": {
            "id": "BA123",
            "url": "https://institution.com/...",
            "qr_code_url": "https://pay-sandbox.gocardless.com/obauth/BA123/qr_code",
            "created_at": "2025-12-04T13:47:16.645Z",
            ...
            "expires_at": "2025-12-04T14:02:16.632Z",
            ...
            "links": {
                ...
                "institution": "INSTITUTION_ID123"
            }
        }
    }
}

We can see that the Billing Request is still in a pending status. This means that the Direct Debit mandate has not yet been created.

Only if the customer approved the Instant Bank Pay request by authorising the bank authorisation either via their mobile banking app or via desktop, we'll then see that the mandate was created.

The customer will be able to approve this request by being redirected to the url parameter.

In a mobile-to-mobile flow we'd ideally use a call-to-action so that the customer is immediately redirected to this link after they clicked on a button.
In a desktop-to-mobile flow, we could use the qr_code_url instead. This will allow the customer to scan the qr code on your website using their mobile device in order to then authorise the Instant Bank payment request via their banking app.

Listening to the bank_authorisation_authorised webhook allows us to make sure that the customer has approved the payment request.

Listening to the payment_confirmed webhook notifies us that the payment has been successfully collected.

Once the customer had approved the bank authorisation, the status of the Billing Request would then move from pending to fulfilled.

The Direct Debit mandate will be created.

Need help?

Connect as a partner