Business::GoCardless::Pro
Module for interacting with the GoCardless Pro (v2) API.
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 v2 GoCardless API at https://developer.gocardless.com/api-reference.
Note that this module is currently incomplete and limited to being a back compatiblity wrapper to allow migration from the v1 (Basic) API. The complete API methods will be added at a later stage (also: patches welcome).
Also note this class also currently inherits from Business::GoCardless::Basic so has all attributes and methods available on that class (some of which may not make sense from the context of the Pro API).
The following examples show instantiating the object and getting a resource (Payment in this case) to manipulate. For more examples see the t/004_end_to_end_pro.t script, which can be run against the gocardless sandbox (or even live) endpoint when given the necessary ENV variables.
my $GoCardless = Business::GoCardless::Pro->new( token => $your_gocardless_token client_details => { base_url => $gocardless_url, # defaults to https://api.gocardless.com webhook_secret => $secret, }, ); # create URL for a one off payment my $new_bill_url = $GoCardless->new_bill_url( session_token => 'foo', description => "Test Payment", success_redirect_url => "http://example.com/rflow/confirm?jwt=$jwt", ); # 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/api-reference/#redirect-flows-complete-a-redirect-flow) my $Payment = $GoCardless->confirm_resource( redirect_flow_id => $id, type => 'payment', # bill / payment / pre_auth / subscription amount => 0, currency => 'GBP', ); # get a specfic Payment $Payment = $GoCardless->payment( $id ); # cancel the Payment $Payment->cancel; # too late? maybe we should refund instead (note: needs to be enabled on GoCardless end) $Payment->refund; # or maybe it failed? $Payment->retry if $Payment->failed; # get a list of Payment objects (filter optional: https://developer.gocardless.com/#filtering) my @payments = $GoCardless->payments( %filter ); # on any resource object: my %data = $Payment->to_hash; my $json = $Payment->to_json;
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::Payment> objects # (filter optional: https://developer.gocardless.com/#filtering) my @payments = $GoCardless->payments( %filter ); # or using the Business::GoCardless::Paginator object: my $Pager = $GoCardless->payments; while( my @payments = $Pager->next ) { foreach my $Payment ( @payments ) { ... } }
All attributes are inherited from Business::GoCardless::Basic.
Get an individual payment, returns a Business::GoCardless::Payment object:
my $Payment = $GoCardless->payment( $id );
Get a list of Payment objects (%filter is optional)
my @payments = $GoCardless->payments( %filter );
Create a payment with the passed params
my $Payment = $GoCardless->create_payment( "amount" => 100, "currency" => "GBP", "charge_date" => "2014-05-19", "reference" => "WINEBOX001", "metadata" => { "order_dispatch_date" => "2014-05-22" }, "links" => { "mandate" => "MD123" } );
Get an individual subscription, returns a Business::GoCardless::Subscrption object:
my $Subscription = $GoCardless->subscription( $id );
Get a list of Subscription objects (%filter is optional)
my @subscriptions = $GoCardless->subscriptions( %filter );
See Business::GoCardless::RedirectFlow for more information on RedirectFlow operations.
Get an individual redirect flow, returns a Business::GoCardless::RedirectFlow object:
my $RedirectFlow = $GoCardless->pre_authorization( $id );
This is meaningless in the v2 API so will throw an exception if called.
See Business::GoCardless::Customer for more information on Customer operations.
Get an individual customer, returns a Business::GoCardless::Customer.
my $Customer = $GoCardless->customer;
Get a list of Business::GoCardless::Customer objects.
my @customers = $GoCardless->customers;
See Business::GoCardless::Webhook::V2 for more information on Webhook operations.
Get a Business::GoCardless::Webhook::V2 object from the data sent to you via a GoCardless webhook:
my $Webhook = $GoCardless->webhook( $json_data,$signature );
These methods are provided for moving from the v1 (Basic) API with minimal changes in your application code. See Business::GoCardless::Upgrading for more info.
Return a URL for redirecting the user to to complete a direct debit mandate that will allow you to setup payments. Note the parameters required are slightly different to those in the Business::GoCardless::Basic module.
See https://developer.gocardless.com/api-reference/#redirect-flows-create-a-redirect-flow for more information.
my $url = $GoCardless->new_bill_url( # required session_token => $session_token, success_redirect_url => $success_callback_url, # optional scheme => $direct_debit_scheme description => $description, prefilled_customer => { ... }, # see documentation above links => { ... }, # see documentation above );
After a user completes the form in the redirect flow (using a URL generated from one of the new_.*?url methods above) GoCardless will redirect them back to the success_redirect_url with a redirect_flow_id, at which point you can call this method to confirm the mandate and set up a one off payment, subscription, etc
The object returned will depend on the type parameter passed to the method
type
my $Payment = $GoCardless->confirm_resource( # required redirect_flow_id => $redirect_flow_id, type => 'payment', # one of bill, payment, pre_auth, subscription amount => 0, currency => 'GBP', # required in the case of type being "subscription" interval_unit => interval => start_at => );
Business::GoCardless
Business::GoCardless::Resource
Business::GoCardless::Payment
Business::GoCardless::Client
Business::GoCardless::Subscription
Business::GoCardless::User
Business::GoCardless::Webhook::V2
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.