Guides

In order to request an Instant Bank payment, we'll need to initiate a payment_request. In this instance, we are going to set the currency to GBP and will need to link the Billing Request with Actions to the creditor we wish to pay out to, CR123.

The required actions of the Billing Request will be different from those of a mandate_request.

In order to generate the payment request url for the customer, we will also need to provide the institution as well as a bank_authorisation_redirect_uri. Setting the create_bank_authorisation to true allows us to retrieve the redirect url in the API response.

The list of available institution IDs can be obtained from the Institutions API.

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"
            }
        },
        "actions": {
            "collect_customer_details": {
                "customer": {
                    "given_name": "Alice",
                    "family_name": "Smith",
                    "email": "alice.smith@example.com",
                    ...
                }
            },
            "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-04T13:47:16.211Z",
            "status": "pending",
            ...
            "payment_request": {
                "description": "Sleek Granite Tuna",
                "currency": "GBP",
                "amount": 1230,
                ...
            },
            ...
            "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 will now be able to grab the url parameter and send it to our customer.

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 has approved the payment request and the funds were collected from their bank account, the status of the Billing Request will then move from pending to fulfilled.

What's next?

Taking an Instant Bank Payment and setting up a Direct Debit mandate

Need help?

Connect as a partner