Guides

This tutorial aims to familiarise Embed PSP integrators with the Billing Request with Actions / Billing Request and will explain setting up either an Instant Bank Payment (IBP), or a Direct Debit mandate and subsequent Direct debit payment or an Instant Bank Payment as well as Direct Debit mandate in a dual flow.

Getting started

For this tutorial, you will need:

An API token
The GoCardless client library of your choice configured in your language of choice
A Creditor to collect payments against

Billing Request with Actions: Setting up a Direct Debit mandate

We can start by creating a Billing Request with Actions. This will allow us to set up a mandate, which is linked to a creditor.

In order to create a mandate, we'll initiate a mandate_request and specify the scheme (for Instant Bank Pay it would be a payment_request).

In this instance, we are going to use bacs for a GBP mandate.

You will need to pass the full payer's billing address to create a bacs Direct Debit mandate.

If you want to collect in EUR, use sepa_core. We link the Billing Request with Actions to the creditor we wish to pay out to, CR123.

With this endpoint you'll be able to complete all required actions to fulfil the mandate request in one single API call.

The required actions of the Billing Request can change depending on the type of payment being taken or set up (e.g a Direct Debit mandate or an Instant Bank payment). We don’t need to worry about them too much in this tutorial - but it’s good to be aware of them! You can read more about them here if you’re interested.

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": {
        "mandate_request": {
            "scheme": "bacs",
            ...
        },
        "actions": {
            "collect_customer_details": {
                "customer": {
                    "given_name": "Alice",
                    "family_name": "Smith",
                    "email": "alice.smith@example.com",
                    ...
                },
                "customer_billing_detail": {
                    "address_line1": "1 Somewhere Lane",
                    ...
                }
            },
            "collect_bank_account": {
                "country_code": "GB",
                "account_holder_name": "Alice Smith",
                "account_number": "55779911",
                "branch_code": "200000"
            }
        },
        "links": {
            "creditor": "CR123"
        }
    }
}

HTTP/1.1 200 OK
Content-Type: application/json
{
    "billing_request_with_actions": {
        "billing_requests": {
            "id": "BRQ123",
            "created_at": "2025-12-04T10:59:05.144Z",
            "status": "fulfilled",
            "mandate_request": {
                "currency": "GBP",
                "scheme": "bacs",
                "links": {
                    "mandate": "MD123"
                },
    ...
}

For the purpose of this tutorial, we will only need to keep track of the mandate ID (MD123) from the API response in order to create a Direct Debit payment.

What's next?

Collecting a Direct Debit payment

Need help?

Connect as a partner