Guides

A Direct Debit mandate is an authorisation from your customer that allows you to collect payments directly from their bank account. Once set up, you can collect recurring or future payments without the customer taking any further action - giving you full control over your payment collection.

Set up a Direct Debit mandate to collect recurring or future payments from your customer. Once authorised, you can collect payments without the customer taking any further action.

Step-by-step guide

Use Billing Requests to create a mandate alongside a new customer. If you want to create a mandate against an existing customer, specify the customer ID in links.customer.

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->billingRequests()->create([
  "params" => [
    "mandate_request" => [
      "scheme" => "bacs"
    ]
  ]
]);

Response:

{
  "billing_requests": {
    "id": "BRQ123",
    "status": "pending",
    "payment_request": null,
    "mandate_request": {
      "currency": "GBP",
      "scheme": "bacs"
    },
    "links": {
      "customer": "CU00016WDAM7BS",
      "customer_billing_detail": "CBD000010PDF4WD",
      "mandate_request": "MRQ123",
      "organisation": "OR123"
    },
    "actions": [
      {
        "type": "collect_customer_details",
        "status": "pending",
      },
      {
        "type": "collect_bank_account",
        "status": "pending"
      }
    ]
  }
}

Direct the customer to authorise the mandate. How you do this depends on your integration type:

Hosted Pages: Create a Billing Request Flow and redirect the customer to the authorisation_url. See Hosted Payment Pages guide
Drop-in: Create a Billing Request Flow and pass the flow ID to the GoCardless Drop-in. See the Drop-in guide
Custom Payment Pages: Collect customer details and bank account via Billing Request actions, then confirm payer details. See the Custom Payment Pages guide

For Hosted Pages and Drop-in, create the flow:

$client = new \GoCardlessPro\Client(array(
  'access_token' => 'your_access_token_here',
  'environment'  => \GoCardlessPro\Environment::SANDBOX
));

$client->billingRequestFlows()->create([
  "params" => [
    "redirect_uri" => "https://my-company.com/landing",
    "exit_uri" => "https://my-company.com/exit",
    "links" => [
      "billing_request" => "BRQ000010NMDMH2"
    ]
  ]
]);

UX Preview

Response:

{
  "billing_request_flows": {
    "authorisation_url": "https://pay.gocardless.com/billing/static/flow?id=<brf_id>",
    "lock_customer_details": false,
    "lock_bank_account": false,
    "auto_fulfil": true,
    "created_at": "2021-03-30T16:23:10.679Z",
    "expires_at": "2021-04-06T16:23:10.679Z",
    "redirect_uri": "https://my-company.com/completed",
    "links": {
      "billing_request": "BRQ123"
    }
  }
}

redirect_uri: where GoCardless sends the customer after they complete the flow.

exit_uri: where GoCardless sends customers who can't complete the flow (e.g. bank not found, no online banking). We recommend returning them to your checkout so they can choose a different payment method.

Send the authorisation_url to your customer via redirect, email, or SMS.

Set these on the Billing Request Flow to restrict what the customer can change during the flow:

Parameter	Effect
`lock_customer_details: true`	Customer details page hidden; customer cannot edit
`lock_bank_account: true`	The bank selection page is hidden; the customer cannot switch accounts
`lock_currency: true`	The customer cannot change the currency or payment scheme