GoCardlessDeveloper Docs
Create a sandbox account

Setting Up a DD Mandate#

View as Markdown

What is the aim of this tutorial?#

This tutorial aims to familiarise Embed PSP integrators with the Billing Request with Actions / Billing Request and will explain setting up either a Pay By Bank, or a Direct Debit mandate and subsequent Direct Debit payment or a Pay By Bank 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 Pay By Bank 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 a Pay By Bank). 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 in billing request actions if you're interested.

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"
},
...
}
$client->billingRequestsWithActions()->create([
"params" => [
"mandate_request" => [
"currency" => "GBP",
"scheme" => "bacs"
],
"actions" => [
"collect_customer_details" => [
"customer" => [
"email" => "alice@example.com",
"given_name" => "Alice",
"family_name" => "Smith"
],
"customer_billing_detail" => [
"address_line1" => "1 Example Street",
"city" => "London",
"postal_code" => "W1 1AA",
"country_code" => "GB"
]
],
"collect_bank_account" => [
"account_number" => "55779911",
"branch_code" => "200000",
"account_holder_name" => "Alice Smith",
"country_code" => "GB"
],
"confirm_payer_details" => []
]
]
]);
client.billing_requests_with_actions.create(params={
"mandate_request": {
"currency": "GBP",
"scheme": "bacs"
},
"actions": {
"collect_customer_details": {
"customer": {
"email": "alice@example.com",
"given_name": "Alice",
"family_name": "Smith"
},
"customer_billing_detail": {
"address_line1": "1 Example Street",
"city": "London",
"postal_code": "W1 1AA",
"country_code": "GB"
}
},
"collect_bank_account": {
"account_number": "55779911",
"branch_code": "200000",
"account_holder_name": "Alice Smith",
"country_code": "GB"
},
"confirm_payer_details": {}
}
})
@client.billing_requests_with_actions.create(
params: {
mandate_request: {
currency: "GBP",
scheme: "bacs"
},
actions: {
collect_customer_details: {
customer: {
email: "alice@example.com",
given_name: "Alice",
family_name: "Smith"
},
customer_billing_detail: {
address_line1: "1 Example Street",
city: "London",
postal_code: "W1 1AA",
country_code: "GB"
}
},
collect_bank_account: {
account_number: "55779911",
branch_code: "200000",
account_holder_name: "Alice Smith",
country_code: "GB"
},
confirm_payer_details: {}
}
}
)
BillingRequestWithActions response = client.billingRequestsWithActions().create()
.withMandateRequestCurrency("GBP")
.withMandateRequestScheme("bacs")
.withActionsCollectCustomerDetailsCustomerEmail("alice@example.com")
.withActionsCollectCustomerDetailsCustomerGivenName("Alice")
.withActionsCollectCustomerDetailsCustomerFamilyName("Smith")
.withActionsCollectCustomerDetailsCustomerBillingDetailAddressLine1("1 Example Street")
.withActionsCollectCustomerDetailsCustomerBillingDetailCity("London")
.withActionsCollectCustomerDetailsCustomerBillingDetailPostalCode("W1 1AA")
.withActionsCollectCustomerDetailsCustomerBillingDetailCountryCode("GB")
.withActionsCollectBankAccountAccountNumber("55779911")
.withActionsCollectBankAccountBranchCode("200000")
.withActionsCollectBankAccountAccountHolderName("Alice Smith")
.withActionsCollectBankAccountCountryCode("GB")
.withActionsConfirmPayerDetails(true)
.execute();
const response = await client.billingRequestsWithActions.create({
mandate_request: {
currency: "GBP",
scheme: "bacs",
},
actions: {
collect_customer_details: {
customer: {
email: "alice@example.com",
given_name: "Alice",
family_name: "Smith",
},
customer_billing_detail: {
address_line1: "1 Example Street",
city: "London",
postal_code: "W1 1AA",
country_code: "GB",
},
},
collect_bank_account: {
account_number: "55779911",
branch_code: "200000",
account_holder_name: "Alice Smith",
country_code: "GB",
},
confirm_payer_details: {},
},
});
var mandateRequest = new GoCardless.Services.BillingRequestWithActionsCreateRequest.BillingRequestWithActionsMandateRequest
{
Currency = "GBP",
Scheme = "bacs"
};

var collectCustomerDetails = new GoCardless.Services.BillingRequestWithActionsCreateRequest.BillingRequestWithActionsActionsCollectCustomerDetails
{
Customer = new GoCardless.Services.BillingRequestWithActionsCreateRequest.BillingRequestWithActionsActionsCollectCustomerDetailsCustomer
{
Email = "alice@example.com",
GivenName = "Alice",
FamilyName = "Smith"
},
CustomerBillingDetail = new GoCardless.Services.BillingRequestWithActionsCreateRequest.BillingRequestWithActionsActionsCollectCustomerDetailsCustomerBillingDetail
{
AddressLine1 = "1 Example Street",
City = "London",
PostalCode = "W1 1AA",
CountryCode = "GB"
}
};

var collectBankAccount = new GoCardless.Services.BillingRequestWithActionsCreateRequest.BillingRequestWithActionsActionsCollectBankAccount
{
AccountNumber = "55779911",
BranchCode = "200000",
AccountHolderName = "Alice Smith",
CountryCode = "GB"
};

var resp = await gocardless.BillingRequestsWithActions.CreateAsync(
new GoCardless.Services.BillingRequestWithActionsCreateRequest
{
MandateRequest = mandateRequest,
Actions = new GoCardless.Services.BillingRequestWithActionsCreateRequest.BillingRequestWithActionsActions
{
CollectCustomerDetails = collectCustomerDetails,
CollectBankAccount = collectBankAccount,
ConfirmPayerDetails = new GoCardless.Services.BillingRequestWithActionsCreateRequest.BillingRequestWithActionsActionsConfirmPayerDetails()
}
}
);
billingRequestWithActionsCreateParams := gocardless.BillingRequestWithActionsCreateParams{
MandateRequest: &gocardless.BillingRequestWithActionsCreateParamsMandateRequest{
Currency: "GBP",
Scheme: "bacs",
},
Actions: &gocardless.BillingRequestWithActionsCreateParamsActions{
CollectCustomerDetails: &gocardless.BillingRequestWithActionsCreateParamsActionsCollectCustomerDetails{
Customer: &gocardless.BillingRequestWithActionsCreateParamsActionsCollectCustomerDetailsCustomer{
Email: "alice@example.com",
GivenName: "Alice",
FamilyName: "Smith",
},
CustomerBillingDetail: &gocardless.BillingRequestWithActionsCreateParamsActionsCollectCustomerDetailsCustomerBillingDetail{
AddressLine1: "1 Example Street",
City: "London",
PostalCode: "W1 1AA",
CountryCode: "GB",
},
},
CollectBankAccount: &gocardless.BillingRequestWithActionsCreateParamsActionsCollectBankAccount{
AccountNumber: "55779911",
BranchCode: "200000",
AccountHolderName: "Alice Smith",
CountryCode: "GB",
},
ConfirmPayerDetails: &gocardless.BillingRequestWithActionsCreateParamsActionsConfirmPayerDetails{},
},
}

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": {
"mandate_request": {
"currency": "GBP",
"scheme": "bacs"
},
"actions": {
"collect_customer_details": {
"customer": {
"email": "alice@example.com",
"given_name": "Alice",
"family_name": "Smith"
},
"customer_billing_detail": {
"address_line1": "1 Example Street",
"city": "London",
"postal_code": "W1 1AA",
"country_code": "GB"
}
},
"collect_bank_account": {
"account_number": "55779911",
"branch_code": "200000",
"account_holder_name": "Alice Smith",
"country_code": "GB"
},
"confirm_payer_details": {}
}
}
}'

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 DD Payment

Use the mandate ID from the previous step to collect a Direct Debit payment.

Learn more
Pay By Bank

Request a Pay By Bank using a Billing Request with Actions.

Learn more
SupportDashboard