in Engineering, Support

Getting started with the GoCardless PHP library

This post relates to the Legacy GoCardless API. If you're starting a new integration, you'll need to use the new GoCardless API - for help getting started, check out our guide.

PHP is the web's most popular coding language, used by nearly 40% of websites, so we've made it super simple to integrate with GoCardless using our open-source API library.

In 90% of cases, you'll be wanting to set up pre-authorizations. These are variable Direct Debits, letting you have your customer authorise once through our secure payment pages, after which you'll be able to charge them automatically whenever you need to with just two lines of code.

1. Add the PHP library to your project

First of all, you'll need to sign up for a GoCardless account and enable developer mode. Once you've done that, you'll get your authentication details which you'll be able to copy and paste into your code. This will take about 5 minutes - just follow our guide here.

Next, you'll need to grab the latest version of our library. There are two options for doing this:

  • Download the ZIP file here and add it to your project.
  • Add GoCardless to your composer.json file:
    "require": {
        "gocardless/gocardless": ">=0.4.2"

We'd recommend storing the extracted GoCardless.php file and the gocardless folder inside a lib/ directory. This makes it easy to organise your code's dependencies.

Next, create a central configuration file. Using this will make it easy to share all the GoCardless setup between different pages, meaning you only have to change your settings in one place. I'll call it


  // By default, your application will run in the sandbox - here,
  // you can test with no money changing hands. When you're
  // reading to go live, simply uncomment this line.
  // GoCardless::$environment = 'production';

  // Let's add your authentication details for the production and
  // sandbox. You can get them both from your Dashboard - copy them
  // in to replace the examples.
  if (GoCardless::$environment == 'production') {
    $account_details = array(
      'app_id'        => 'INSERT_LIVE_APP_ID',
      'app_secret'    => 'INSERT_LIVE_APP_SECRET',
      'merchant_id'   => 'INSERT_LIVE_MERCHANT_ID',
      'access_token'  => 'INSERT_LIVE_MERCHANT_ACCESS_TOKEN'
  } else {
    $account_details = array(
      'app_id'        => 'INSERT_SANDBOX_APP_ID',
      'app_secret'    => 'INSERT_SANDBOX_APP_SECRET',
      'merchant_id'   => 'INSERT_SANDBOX_MERCHANT_ID',


2. Send the customer to the GoCardless payment pages

Setting up a pre-authorization will allow you to get authorisation from your customer once, and then charge them whenever you need to in the future. To do that, you'll need to send the customer through our secure payment process.

Our API library makes this simple:

// Bring in the file we made earlier, which includes the GoCardless
// library and all of our configuration

// Provide the details to use to set up the Direct Debit. In
// particular, make sure you set the amount to be higher than
// you'll ever need to collect in a month.
$pre_authorization_details = array(
  "amount" => "10000",
  "interval_length" => 1,
  "interval_unit" => "month"

// The GoCardless library puts everything together and
// generates a personalised link to our secure payment pages
$pre_authorization_url = GoCardless::new_pre_authorization_url($pre_authorization_details);

// Now we could put that generated URL behind a link...
echo "<a href='" . $pre_authorization_url . "'>Set up a Direct Debit</a>";
// or we could redirect the user right away...
header("Location: " . $pre_authorization_url);

3. Confirm the setup of the Direct Debit

Once the customer has finished going through our payment flow, we'll send them back to your website, where you'll need to confirm the authorization via our API.

Let's create a file called callback.php. You'll need to set the URL of that as your "redirect URL" in your Dashboard's developer settings:

Setting your redirect URI

// Let's include our central configuration file again.

// Pull out the required data from the redirect
$confirm_params = array(
  'resource_id'    => $_GET['resource_id'],
  'resource_type'  => $_GET['resource_type'],
  'resource_uri'   => $_GET['resource_uri'],
  'signature'      => $_GET['signature']

// We'll add this - it'll come into effect if you implement
// a more advanced integration,
if (isset($_GET['state'])) {
  $confirm_params['state'] = $_GET['state'];


// If all has gone well, you'll now be able to charge this
// customer. To do this, you'll need to store their
// pre-authorization's ID somewhere - for instance on a
// user's database record.
$pre_authorization_id = $resource_id;

<p><b>Thank you!</b></p>

4. Charge your customer

When you're ready to charge your customer, it's just a few simple lines of code:


// You'll need to pull our the customer's pre-
// authorization ID which you saved somewhere in
// the previous step.
$pre_authorization_id = fetch_id_from_database();

$pre_auth = GoCardless_PreAuthorization::find($pre_authorization_id);

// Set the details for the payment to collect. We'll
// display the "name" in emails sent to the customer.
$bill_details = array(
  "name" => "Invoice for June 2014",
  "amount" => "25.00"

$bill = $pre_auth->create_bill($bill_details);

// It's likely that you'll want to store the bill's ID
// - this is useful for staying up to date on its status
// later.
$bill_id = $bill->id;

What next?

You've now seen how to set up the GoCardless PHP library, create your first Direct Debit and then take a payment. Here's a few things to check out as your next steps:

  • Web hooks allow you to be informed about the progress of a payment or any changes to your customers' Direct Debits - so for example, we'll let you know when money has been successfully collected.
  • Pre-populating information makes it simpler for your customers to pay and increases conversion.
  • Using the "state" parameter lets you pass data through the payment process, and collect it at the other end.

If you have any questions or we can help at all, just get in touch - email us.

Want to find out more or ask questions?
Book a chat with an expert
By using this site you agree to the use of cookies for analytics, personalised content and ads. Learn more