A couple of years ago I released a CFML client library for UK Direct Debit (DD) provider GoCardless's REST API.

Since then the service has been expanded to cover DD payments across Europe and cater for larger organsations with more complex requirements.

To accommodate these changes GoCardless have released a new backwards incompatible version of their API. Although the previous API still works, it is now regarded as "legacy" and is not recommended for new integrations.

Anyone using ColdFusion or Lucee and thinking of integrating GoCardless with their applications should take a look at the completely revised CFML client library I've recently created to work with the new API. It covers all of the core endpoints and provides a convenience method for processing webhooks sent by GoCardless to your application when relevant events occur.

Simpler and more complex

The client library aims to hide most of the complexity involved in making requests to the API, but the mechanism for making calls is actually simpler than the legacy version. Previously every request had to be digitally signed with an HMAC digest of the URL parameters in a "normalised" form using a shared secret as the key. Now authentication only requires sending the shared secret as a header over TLS.

On the other hand, the number of resource types, endpoints and parameter options has increased substantially, so building tests and implementations for each has proved quite time-consuming. The BDD style TestBox Suite contains around 120 tests—more then twice as many as the previous library.

Passing parameters via chained methods

The earlier library used the standard way of passing parameters to the API: as arguments to the appropriate method.

newSubscriptionUrl = client.newSubscriptionUrl(
 amount=30.00
 ,name="Example subscription"
 ,interval_unit="month"
 ,interval_length=1
);

GoCardless provide a number of libraries for popular languages such as PHP, Ruby and Python, most of which follow this approach to parameters. However, I noticed that the new Java client library's syntax was quite different.

Subscription subscription = client.subscriptions().create()
  .withAmount( 30 )
  .withCurrency( "GBP" )
  .withName( "Example subscription" )
  .withIntervalUnit( "monthly" )
  .withLinksMandate( "MD123" )
  .execute();

This "chained method" approach to building a request object may be common in the Java world, but it was new to me. I very much like the clarity of the syntax so I've adopted it, with some modifications, in the CFML library.

client = New gocardless( access_token="your_access_token_here", environment="sandbox" );
result = client.subscriptions().create()
    .withAmount( 30 )
    .withCurrency( "GBP" )
    .withName( "Example subscription" )
    .withIntervalUnit( "monthly")
    .withMandate( "MD123" )
    .execute();
subscription = result.resource;
subscriptionID = subscription.id;

If you need to pass parameters conditionally, then you simply build the request object in stages before calling the final execute() method.

client = New gocardless( access_token="your_access_token_here", environment="sandbox" );
requestObject = client.subscriptions().create()
    .withAmount( 30 )
    .withCurrency( "GBP" )
    .withIntervalUnit( "monthly")
    .withMandate( "MD123" );
if( IsDefined( "subscriptionName" ) )
    requestObject.withName( "Example subscription" );
result = requestObject.execute();

More examples and documentation are available as part of the Github repo and wiki.

GoCardless Pro CFML client library