Skip to content
Go to GoCardless homepage
LoginSign up

A Second Look at the GoCardless PHP Library

By GoCardlessMar 20122 min read

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.

In our first blog post about our PHP library we looked at how to create a payment URL and then confirm the payment once it had been created. Examples of this are included in the repo itself (in the /examples folder) and detailed in our documentation too. Now let's look at a couple of other features available with the library.

Passing a variable through the payment process

Very often when the user arrives at the Redirect URI (where you must confirm the new payment object) you will want a way to refer to what the payment was for. We have a variable for that called 'state'. You can pass in 'state' as a variable when you generate a new payment link:

// The parameters for the payment
$subscription_details = array(
 'amount' => '10.00',
 'interval_length' => 1,
 'interval_unit' => 'month',
 'state' => $reference

// Generate the url
$subscription_url = GoCardless::new_subscription_url($subscription_details);

// Display the link
echo '<a href="'.$subscription_url.'">New subscription</a>';

It then gets passed back to the Redirect URI page as a GET variable which you can access like this:

$reference = $_GET['state'];

Creating bills within a pre-authorization

Our pre-authorization payment type lets you bill your customer whenever you want to up to an agreed limit. To create a bill within a pre-authroization, you can do the following:

// Load your pre-authorization
$pre_auth = GoCardless_PreAuthorization::find($pre_auth_id);

// Details of the bill to create
$bill_details = array(
 'amount' => '5.00'

// Create the bill
$bill = $pre_auth->create_bill($bill_details);

Cancelling a subscription

// Load the subscription
$subscription = GoCardless_Subscription::find($subscription_id);

// Call the cancel method
$subscription = $subscription->cancel();


We fire off a webhook a few days after a payment is made to confirm whether the payment was successful or not. In the most recent version of the PHP library we included a webhook listener demo. The webhook content is sent in the body of the request (rather than in the headers) which you can extract like this:

// Use this line to fetch the body of the HTTP request
$webhook = file_get_contents('php://input');

// Convert json blog to array
$webhook_array = json_decode($webhook, true);

// Validate webhook
if (GoCardless::validate_webhook($webhook_array['payload'])) {
 // Send a success header
 header('HTTP/1.1 200 OK');

GoCardless is used by over 55,000 businesses around the world. Learn more about how you can improve payment processing at your business today.

Learn moreSign Up

Interested in automating the way you get paid? GoCardless can help

Contact sales

Contact Us


Contact sales

+44 20 8338 9539


Request support

+44 20 8338 9540

Seen 'GoCardless Ltd' on your bank statement? Learn more

GoCardless Ltd., Sutton Yard, 65 Goswell Road, London, EC1V 7EN, United Kingdom

GoCardless (company registration number 07495895) is authorised by the Financial Conduct Authority under the Payment Services Regulations 2017, registration number 597190, for the provision of payment services. GoCardless SAS (23-25 Avenue Mac-Mahon, Paris, 75017, France), an affiliate of GoCardless Ltd (company registration number 834 422 180, R.C.S. PARIS), is authorised by the ACPR (French Prudential Supervision and Resolution Authority), Bank Code (CIB) 17118, for the provision of payment services.