Pay By Bank#

View as Markdown

In order to request a Pay By Bank, 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.

HTTPPHPPythonRubyJavaJavaScript.NETGoBash

POST https://api.gocardless.com/billing_requests/create_with_actions HTTP/1.1
Content-Type: application/json
{
  "billing_request_with_actions": {
      "payment_request": {
          "description": "Pay By Bank",
          "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"
}
}
}
}

$client->billingRequestsWithActions()->create([
"params" => [
"payment_request" => [
"description" => "Pay By Bank",
"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"
]
]
]);

client.billing_requests_with_actions.create(params={
"payment_request": {
"description": "Pay By Bank",
"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"
}
})

@client.billing_requests_with_actions.create(
params: {
payment_request: {
description: "Pay By Bank",
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"
}
}
)

BillingRequestWithActions response = client.billingRequestsWithActions().create()
.withPaymentRequestDescription("Pay By Bank")
.withPaymentRequestAmount(123)
.withPaymentRequestCurrency("GBP")
.withPaymentRequestMetadata("internal_payment_id", "ID123")
.withActionsCollectCustomerDetailsCustomerGivenName("Alice")
.withActionsCollectCustomerDetailsCustomerFamilyName("Smith")
.withActionsCollectCustomerDetailsCustomerEmail("alice.smith@example.com")
.withActionsSelectInstitutionInstitution("INSTITUTION_ID123")
.withActionsSelectInstitutionCountryCode("GB")
.withActionsBankAuthorisationRedirectUri("https://pay.gocardless.com/billing/static/thankyou")
.withActionsCreateBankAuthorisation(true)
.withLinksCreditor("CR123")
.execute();

const response = await client.billingRequestsWithActions.create({
payment_request: {
description: "Pay By Bank",
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",
},
});

var paymentRequest = new GoCardless.Services.BillingRequestWithActionsCreateRequest.BillingRequestWithActionsPaymentRequest
{
Description = "Pay By Bank",
Amount = 123,
Currency = "GBP",
Metadata = new Dictionary<string, string>()
{
{"internal_payment_id", "ID123"}
}
};

var collectCustomerDetails = new GoCardless.Services.BillingRequestWithActionsCreateRequest.BillingRequestWithActionsActionsCollectCustomerDetails
{
Customer = new GoCardless.Services.BillingRequestWithActionsCreateRequest.BillingRequestWithActionsActionsCollectCustomerDetailsCustomer
{
GivenName = "Alice",
FamilyName = "Smith",
Email = "alice.smith@example.com"
}
};

var selectInstitution = new GoCardless.Services.BillingRequestWithActionsCreateRequest.BillingRequestWithActionsActionsSelectInstitution
{
Institution = "INSTITUTION_ID123",
CountryCode = "GB"
};

var resp = await gocardless.BillingRequestsWithActions.CreateAsync(
new GoCardless.Services.BillingRequestWithActionsCreateRequest
{
PaymentRequest = paymentRequest,
Actions = new GoCardless.Services.BillingRequestWithActionsCreateRequest.BillingRequestWithActionsActions
{
CollectCustomerDetails = collectCustomerDetails,
SelectInstitution = selectInstitution,
BankAuthorisationRedirectUri = "https://pay.gocardless.com/billing/static/thankyou",
CreateBankAuthorisation = true
},
Links = new GoCardless.Services.BillingRequestWithActionsCreateRequest.BillingRequestWithActionsLinks
{
Creditor = "CR123"
}
}
);

billingRequestWithActionsCreateParams := gocardless.BillingRequestWithActionsCreateParams{
PaymentRequest: &gocardless.BillingRequestWithActionsCreateParamsPaymentRequest{
Description: "Pay By Bank",
Amount: 123,
Currency: "GBP",
Metadata: map[string]interface{}{"internal_payment_id": "ID123"},
},
Actions: &gocardless.BillingRequestWithActionsCreateParamsActions{
CollectCustomerDetails: &gocardless.BillingRequestWithActionsCreateParamsActionsCollectCustomerDetails{
Customer: &gocardless.BillingRequestWithActionsCreateParamsActionsCollectCustomerDetailsCustomer{
GivenName: "Alice",
FamilyName: "Smith",
Email: "alice.smith@example.com",
},
},
SelectInstitution: &gocardless.BillingRequestWithActionsCreateParamsActionsSelectInstitution{
Institution: "INSTITUTION_ID123",
CountryCode: "GB",
},
BankAuthorisationRedirectUri: "https://pay.gocardless.com/billing/static/thankyou",
CreateBankAuthorisation: true,
},
Links: &gocardless.BillingRequestWithActionsCreateParamsLinks{
Creditor: "CR123",
},
}

response, err := client.BillingRequestsWithActions.Create(context, billingRequestWithActionsCreateParams)

curl -X POST "https://api.gocardless.com/billing_requests/create_with_actions" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "GoCardless-Version: 2015-07-06" \
-H "Content-Type: application/json" \
-d '{
"billing_request_with_actions": {
"payment_request": {
"description": "Pay By Bank",
"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"
}
}
}'

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 Pay By Bank 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?#

Dual Flow

Combine a Pay By Bank and a Direct Debit mandate setup in a single flow.

Learn more

Handling Webhooks

Listen to webhooks to confirm payment authorisation and fulfilment.

Learn more