Business::GoCardless - Perl library for interacting with the GoCardless Basic v1 API (https://gocardless.com)
Module for interacting with the GoCardless Basic (v1) API. Please note this module is only compatible with the Basic v1 GoCardless API, which GoCardless are now calling "The Legacy GoCardless API". If you wish to use the Pro (v2) API you should use the Business::GoCardless::Pro module.
You should refer to the official gocardless API documentation in conjunction with this perldoc, as the official API documentation explains in more depth some of the functionality including required / optional parameters for certain methods. https://developer.gocardless.com, specifically the docs for the v1 GoCardless API at https://developer.gocardless.com/legacy.
The following examples show instantiating the object and getting a resource (Bill in this case) to manipulate. For more examples see the t/002_end_to_end.t script, which can be run against the gocardless sandbox (or even live) endpoint when given the necessary ENV variables.
my $GoCardless = Business::GoCardless::Basic->new( token => $your_gocardless_token client_details => { base_url => $gocardless_url, # defaults to https://gocardless.com app_id => $your_gocardless_app_id, app_secret => $your_gocardless_app_secret, merchant_id => $your_gocardless_merchant_id, }, ); # get merchant details my $Merchant = $GoCardless->merchant; # create URL for a one off bill (https://developer.gocardless.com/#create-a-one-off-bill) my $new_bill_url = $GoCardless->new_bill_url( amount => 100, name => "Some Bill", description => "Some Bill Description", user => $user_hash, redirect_uri => "https://foo/success", cancel_uri => "https://foo/cancel", state => "some_state_data", ); # having sent the user to the $new_bill_url and them having complete it, # we need to confirm the resource using the details sent by gocardless to # the redirect_uri (https://developer.gocardless.com/#confirm-a-new-one-off-bill) my $Bill = $GoCardless->confirm_resource( resource_uri => $uri, resource_type => 'bill', # in the above case resource_id => $bill_id, signature => $signature, state => "some_state_data", ); # get a specfic Bill $Bill = $GoCardless->bill( $id ); # cancel the bill $Bill->cancel; # too late? maybe we should refund instead $Bill->refund; # or maybe it failed? $Bill->retry if $Bill->failed; # get a list of Bill objects (filter optional: https://developer.gocardless.com/#filtering) my @bills = $GoCardless->bills( %filter ); # on any resource object: my %data = $Bill->to_hash; my $json = $Bill->to_json;
Any problems or errors will result in a Business::GoCardless::Exception object being thrown, so you should wrap any calls to the library in the appropriate error catching code (ideally using a module from CPAN):
try { my $Pager = $GoCardless->bills; while( my @bills = $Pager->next ) { foreach my $Bill ( @bills ) { $Bill->cancel; } } } catch ( Business::GoCardless::Exception $e ) { # error specific to Business::GoCardless ... say $e->message; # error message say $e->code; # HTTP status code say $e->response; # HTTP status message } catch ( $e ) { # some other failure? ... }
Any methods marked as pager have a dual interface, when called in list context they will return the first 100 resource objects, when called in scalar context they will return a Business::GoCardless::Paginator object allowing you to iterate through all the objects:
# get a list of L<Business::GoCardless::Bill> objects # (filter optional: https://developer.gocardless.com/#filtering) my @bills = $GoCardless->bills( %filter ); # or using the Business::GoCardless::Paginator object: my $Pager = $GoCardless->bills; while( my @bills = $Pager->next ) { foreach my $Bill ( @bills ) { ... } }
Your gocardless API token, this attribute is required.
Hash of gocardless client details, passed to Business::GoCardless::Client.
base_url => $gocardless_url, # defaults to https://gocardless.com app_id => $your_gocardless_app_id, app_secret => $your_gocardless_app_secret, merchant_id => $your_gocardless_merchant_id,
The client object, defaults to Business::GoCardless::Client.
Methods not tied to any particular resource.
Confirm a resource.
my $Bill = $GoCardless->confirm_resource( resource_uri => $uri, resource_type => 'bill', resource_id => $bill_id, signature => $signature, state => "some_state_data", );
See Business::GoCardless::Bill for more information on Bill operations.
Create a URL for generating a one off bill:
my $new_bill_url = $GoCardless->new_bill_url( amount => 100, );
Get a Business::GoCardless::Bill object for a specific bill.
my $Bill = $GoCardless->bill( $id );
Get a list of Bill objects (%filter is optional).
my @bills = $GoCardless->bills( %filter );
See Business::GoCardless::Merchant for more information on Merchant operations.
Get object that represents you (Merchant)
my $Merchant = $GoCardless->merchant;
Get a list of Business::GoCardless::Payout objects.
my @payouts = $GoCardless->payouts;
See Business::GoCardless::Payout for more information on Payout operations.
Get a Business::GoCardless::Payout object for a specific payout.
my $Payout = $GoCardless->payout( $id );
See Business::GoCardless::PreAuthorization for more information on PreAuthorization operations.
Create a URL for generating a pre_authorization.
my $new_pre_auth_url = $GoCardless->new_pre_authorization_url( max_amount => 100, interval_length => 10, interval_unit => 'day', );
Get a Business::GoCardless::PreAuthorization object for a specific pre_authorization.
my $PreAuth = $GoCardless->pre_authorization( $id );
Get a list of Business::GoCardless::PreAuthorization objects.
my @pre_auths = $GoCardless->pre_authorizations;
See Business::GoCardless::Subscription for more information on Subscription operations.
Create a URL for generating a subscription.
my $new_pre_auth_url = $GoCardless->new_subscription_url( amount => 100, interval_length => 1, interval_unit => 'month', );
Get a Business::GoCardless::Subscription object for a specific subscription.
my $Subscription = $GoCardless->subscription( $id );
Get a list of Business::GoCardless::Subscription objects.
my @subs = $GoCardless->subscriptions;
See Business::GoCardless::User for more information on User operations.
Get a list of Business::GoCardless::User objects.
my @users = $GoCardless->users;
See Business::GoCardless::Webhook for more information on Webhook operations.
Get a Business::GoCardless::Webhook object from the data sent to you via a GoCardless webhook:
my $Webhook = $GoCardless->webhook( $json_data );
Business::GoCardless
Business::GoCardless::Pro
Business::GoCardless::Resource
Business::GoCardless::Bill
Business::GoCardless::Client
Business::GoCardless::Merchant
Business::GoCardless::Payout
Business::GoCardless::Subscription
Business::GoCardless::User
Business::GoCardless::Webhook
Lee Johnson - leejo@cpan.org
leejo@cpan.org
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. If you would like to contribute documentation, features, bug fixes, or anything else then please raise an issue / pull request:
https://github.com/Humanstate/business-gocardless
To install Business::GoCardless, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Business::GoCardless
CPAN shell
perl -MCPAN -e shell install Business::GoCardless
For more information on module installation, please visit the detailed CPAN module installation guide.