Guides
Setting up mandates
Direct Debit Mandates Verified Mandates Collecting mandates offline Importing MandatesRecurring payments
Subscriptions Instalments Variable Recurring Payments Instant Bank Pay + Direct DebitSend an outbound payment
Adding a new recipient Initiate an outbound payment Approve an outbound payment Cancel an outbound paymentSetting up mandates / collecting payments
Billing Request with Actions: Setting up a Direct Debit mandate Collecting a Direct Debit payment Billing Request with Actions: Taking an Instant Bank Payment Billing Request with Actions Dual Flow: Taking an Instant Bank Payment and setting up a Direct Debit mandateBilling Request with Actions: Taking an Instant Bank Payment
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!
1POST https://api.gocardless.com/billing_requests/create_with_actions HTTP/1.1
2Content-Type: application/json
3{
4 "billing_request_with_actions": {
5 "payment_request": {
6 "description": "Instant Bank Payment",
7 "amount": 123,
8 "currency": "GBP",
9 "metadata": {
10 "internal_payment_id": "ID123"
11 }
12 },
13 "actions": {
14 "collect_customer_details": {
15 "customer": {
16 "given_name": "Alice",
17 "family_name": "Smith",
18 "email": "alice.smith@example.com",
19 ...
20 }
21 },
22 "select_institution": {
23 "institution": "INSTITUTION_ID123",
24 "country_code": "GB"
25 },
26 "bank_authorisation_redirect_uri": "https://pay.gocardless.com/billing/static/thankyou",
27 "create_bank_authorisation": true
28 },
29 "links": {
30 "creditor": "CR123"
31 }
32
33HTTP/1.1 200 OK
34Content-Type: application/json
35{
36 "billing_request_with_actions": {
37 "billing_requests": {
38 "id": "BRQ123",
39 "created_at": "2025-12-04T13:47:16.211Z",
40 "status": "pending",
41 ...
42 "payment_request": {
43 "description": "Sleek Granite Tuna",
44 "currency": "GBP",
45 "amount": 1230,
46 ...
47 },
48 ...
49 "links": {
50 "customer": "CU123",
51 ...
52 "creditor": "CR123",
53 "...
54 },
55 ...
56 "bank_authorisations": {
57 "id": "BA123",
58 "url": "https://institution.com/...",
59 "qr_code_url": "https://pay-sandbox.gocardless.com/obauth/BA123/qr_code",
60 "created_at": "2025-12-04T13:47:16.645Z",
61 ...
62 "expires_at": "2025-12-04T14:02:16.632Z",
63 ...
64 "links": {
65 ...
66 "institution": "INSTITUTION_ID123"
67 }
68 }
69 }
70}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_urlinstead. 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