Direct Debit: Setting up a mandate

Using the Hosted Payment Pages to set up a mandate

Setting up Direct Debit mandates using Hosted Payment Pages

The Redirect Flow API lets you use these hosted payment pages. Once your customer enters their bank details, you will be set up with everything you need at once: a customer, a customer bank account, and a mandate.

Creating a redirect flow

We’ll use the API to create a redirect flow, generating a URL that we can send our customers to in order to have them set up a mandate.

<?php
require 'vendor/autoload.php';

$client = new \GoCardlessPro\Client([
    // We recommend storing your access token in an
    // environment variable for security
    'access_token' => getenv('GC_ACCESS_TOKEN'),
    // Change me to LIVE when you're ready to go live
    'environment' => \GoCardlessPro\Environment::SANDBOX
]);

$redirectFlow = $client->redirectFlows()->create([
    "params" => [
        // This will be shown on the payment pages
        "description" => "Wine boxes",
        // Not the access token
        "session_token" => "dummy_session_token",
        "success_redirect_url" => "https://developer.gocardless.com/example-redirect-uri/",
        // Optionally, prefill customer details on the payment page
        "prefilled_customer" => [
          "given_name" => "Tim",
          "family_name" => "Rogers",
          "email" => "tim@gocardless.com",
          "address_line1" => "338-346 Goswell Road",
          "city" => "London",
          "postal_code" => "EC1V 7LQ"
        ]
    ]
]);

// Hold on to this ID - you'll need it when you
// "confirm" the redirect flow later
print("ID: " . $redirectFlow->id . "<br />");

print("URL: " . $redirectFlow->redirect_url);

In a real integration:

You’d set the success_redirect_url to a cheery success page on your website where you’d “complete” the flow using the API (we’ll show you how to do this next), as well as storing the created customer and mandate details.
You’d provide a session_token which identifies the user’s session on your website (for example their session ID in your application). You provide this when creating the redirect flow, and must provide it again when “completing” it at the end. Supplying this token twice makes sure that the person who completed the redirect flow is the person you sent to it.
Optionally, you can include a prefilled_customer object with your end customer’s details. These will be prefilled on the payment page so your customer doesn’t have to enter them. For a full list of the details you can provide, head to the API reference.

The redirect_url we’ve just printed (which will look something like https://pay-sandbox.gocardless.com/flow/RE00006GBDVVP3BBCP9Q5318ZVJWE0DN) is where you send your customer to set up their mandate on our secure payment pages.

Try going to the URL printed by your code and completing the setup process - this is exactly what your customers will see. You can use our example bank details rather than your own while working in the sandbox:

In the UK, use the sort code 200000 and the account number 55779911
In Sweden, use the clearingnummer (branch code) 5491, the kontonummer (account number) 0000003 and the personnummer (Swedish identity number) 198112289874
In Denmark, use the registreringsnummer (bank code) 345, the kontonummer (account number) 3179681 and the CPR-nummer (Danish identity number) 0101701234
In Australia, use the BSB 082-082 and the account number 012345678
In New Zealand, use the bank code 12, branch code 3113and the account number 0003869-00
In Canada, use the bank code (Financial Institution number) 0003, branch code (Branch Transit number) 00006 and the account number 0000000
In United States of America, use the bank code 026073150, account number 2715500356 and the account type checking
Everywhere else, use the French IBAN FR1420041010050500013M02606
When you sign up in the sandbox, we’ll give you access to the Direct Debit scheme most appropriate for your location: Bacs in the UK, ACH in the United States of America, Autogiro in Sweden, Betalingsservice in Denmark, BECS in Australia, BECS NZ in New Zealand and SEPA elsewhere. If you want to use other schemes, just get in touch. You’ll need to have a bank account where you can receive payouts in the relevant currency.

Completing a redirect flow

Once you’ve completed the form, you’ll be redirected back to our example success page. Note that the redirect_flow_id query parameter in the URL matches the ID of the redirect flow object.

Now we’ll use a second API call to “complete” the redirect flow. In a real integration, we’d build our own success page, setting it as the redirect_url, and this page would perform this step.

We’ll need the ID from above, and the session_token we set earlier:

<?php
require 'vendor/autoload.php';

$client = new \GoCardlessPro\Client([
    // We recommend storing your access token in an environment variable for security
    'access_token' => getenv('GC_ACCESS_TOKEN'),
    // Change me to LIVE when you're ready to go live
    'environment' => \GoCardlessPro\Environment::SANDBOX
]);

$redirectFlow = $client->redirectFlows()->complete(
    "RE00006GBASX53T7KYWT4051FMC0TZA6", //The redirect flow ID from above.
    ["params" => ["session_token" => "dummy_session_token"]]
);

print("Mandate: " . $redirectFlow->links->mandate . "<br />");
// Save this mandate ID for the next section.
print("Customer: " . $redirectFlow->links->customer . "<br />");

// Display a confirmation page to the customer, telling them their Direct Debit has been
// set up. You could build your own, or use ours, which shows all the relevant
// information and is translated into all the languages we support.
print("Confirmation URL: " . $redirectFlow->confirmation_url . "<br />");

The complete method returns the redirect flow object, now including details of the mandate, customer, and customer bank account that have been created.

Keep a note of the mandate ID - you'll need it later. In a real application, you’d write them to a database record associated with your customer.

With the redirect flow completed via the API and the mandate ID stored, show your customer a clear confirmation page telling them that their Direct Debit has been set up, and what will happen next.

You could build your own, or you could use our pre-made one which comes ready translated into all the languages we support - just redirect the customer to the URL found in the confirmation_url attribute of the redirect flow.

Let’s try listing our customers again as we did for our first request. Now, we’ll see the customer we’ve just created:

$customers = $client->customers()->list()->records;
print_r($customers);

What's Next?

Taking a one-off payment against a mandate

More Guides

Taking subscription payments against a mandate

Taking instalment payments against a mandate

Need help?