Direct Debit: Setting up a mandate
Deprecation Notice: Hosted Payment Pages
Hosted payment pages are our legacy redirect flow for setting up mandates and we strongly recommend using the Billing Request flow instead.
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.
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.
1<?php 2require 'vendor/autoload.php'; 3 4$client = new \GoCardlessPro\Client([ 5 // We recommend storing your access token in an 6 // environment variable for security 7 'access_token' => getenv('GC_ACCESS_TOKEN'), 8 // Change me to LIVE when you're ready to go live 9 'environment' => \GoCardlessPro\Environment::SANDBOX 10]); 11 12$redirectFlow = $client->redirectFlows()->create([ 13 "params" => [ 14 // This will be shown on the payment pages 15 "description" => "Wine boxes", 16 // Not the access token 17 "session_token" => "dummy_session_token", 18 "success_redirect_url" => "https://developer.gocardless.com/example-redirect-uri/", 19 // Optionally, prefill customer details on the payment page 20 "prefilled_customer" => [ 21 "given_name" => "Tim", 22 "family_name" => "Rogers", 23 "email" => "firstname.lastname@example.org", 24 "address_line1" => "338-346 Goswell Road", 25 "city" => "London", 26 "postal_code" => "EC1V 7LQ" 27 ] 28 ] 29]); 30 31// Hold on to this ID - you'll need it when you 32// "confirm" the redirect flow later 33print("ID: " . $redirectFlow->id . "<br />"); 34 35print("URL: " . $redirectFlow->redirect_url);
In a real integration:
You’d set the
success_redirect_urlto 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_tokenwhich 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_customerobject with your end customer’s details. These will be pre-filled 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.
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
200000and the account number
In Sweden, use the clearingnummer (branch code)
5491, the kontonummer (account number)
0000003and the personnummer (Swedish identity number)
In Denmark, use the registreringsnummer (bank code)
345, the kontonummer (account number)
3179681and the CPR-nummer (Danish identity number)
In Australia, use the BSB
082-082and the account number
In New Zealand, use the bank code
12, branch code
3113and the account number
In Canada, use the bank code (Financial Institution number)
0003, branch code (Branch Transit number)
00006and the account number
In United States of America, use the bank code
026073150, account number
2715500356and the account type
Everywhere else, use the French IBAN
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.
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:
1<?php 2require 'vendor/autoload.php'; 3 4$client = new \GoCardlessPro\Client([ 5 // We recommend storing your access token in an environment variable for security 6 'access_token' => getenv('GC_ACCESS_TOKEN'), 7 // Change me to LIVE when you're ready to go live 8 'environment' => \GoCardlessPro\Environment::SANDBOX 9]); 10 11$redirectFlow = $client->redirectFlows()->complete( 12 "RE00006GBASX53T7KYWT4051FMC0TZA6", //The redirect flow ID from above. 13 ["params" => ["session_token" => "dummy_session_token"]] 14); 15 16print("Mandate: " . $redirectFlow->links->mandate . "<br />"); 17// Save this mandate ID for the next section. 18print("Customer: " . $redirectFlow->links->customer . "<br />"); 19 20// Display a confirmation page to the customer, telling them their Direct Debit has been 21// set up. You could build your own, or use ours, which shows all the relevant 22// information and is translated into all the languages we support. 23print("Confirmation URL: " . $redirectFlow->confirmation_url . "<br />");
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.
Our provided confirmation page is only available for 15 minutes from the moment when you complete the redirect flow via the API, so you should redirect the customer straight to it.
Let’s try listing our customers again as we did for our first request. Now, we’ll see the customer we’ve just created:
1$customers = $client->customers()->list()->records; 2print_r($customers);