NAME
Business::GoCardless::Pro - Perl library for interacting with the GoCardless Pro v2 API (https://gocardless.com)
DESCRIPTION
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 so has all attributes and methods available on that class (some of which may not make sense from the context of the Pro API).
SYNOPSIS
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;PAGINATION
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 ) {
...
}
}ATTRIBUTES
All attributes are inherited from Business::GoCardless.
Payment Methods
payment
Get an individual payment, returns a Business::GoCardless::Payment object:
my $Payment = $GoCardless->payment( $id );payments (pager)
Get a list of Payment objects (%filter is optional)
my @payments = $GoCardless->payments( %filter );create_payment
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"
}
);Subscription Methods
subscription
Get an individual subscription, returns a Business::GoCardless::Subscrption object:
my $Subscription = $GoCardless->subscription( $id );subscriptions (pager)
Get a list of Subscription objects (%filter is optional)
my @subscriptions = $GoCardless->subscriptions( %filter );RedirectFlow Methods
See Business::GoCardless::RedirectFlow for more information on RedirectFlow operations.
pre_authorization
Get an individual redirect flow, returns a Business::GoCardless::RedirectFlow object:
my $RedirectFlow = $GoCardless->pre_authorization( $id );pre_authorizations (pager)
This is meaningless in the v2 API so will throw an exception if called.
Mandate Methods
See Business::GoCardless::Mandate for more information on Mandate operations.
mandate
Get an individual mandate, returns a Business::GoCardless::Mandate object:
my $Mandate = $GoCardless->mandate( $id );Customer Methods
See Business::GoCardless::Customer for more information on Customer operations.
customer
Get an individual customer, returns a Business::GoCardless::Customer.
my $Customer = $GoCardless->customer;customers (pager)
Get a list of Business::GoCardless::Customer objects.
my @customers = $GoCardless->customers;Webhook Methods
See Business::GoCardless::Webhook::V2 for more information on Webhook operations.
webhook
Get a Business::GoCardless::Webhook::V2 object from the data sent to you via a GoCardless webhook:
my $Webhook = $GoCardless->webhook( $json_data,$signature );Note that GoCardless may continue to send old style webhooks even after you have migrated from the Basic to the Pro API, so to handle this the logic in this method will check the payload and if it is a legacy webhook will return a legacy Webhook object. You can check this like so:
if ( $Webhook->is_legacy ) {
# process webhook using older legacy code
...
} else {
# process webhook using new style code
...
}BACK COMPATIBILITY METHODS
These methods are provided for those who want to move from the v1 (Basic) API with minimal changes in your application code.
new_bill_url
new_pre_authorization_url
new_subscription_url
Return a URL for redirecting the user to to complete a direct debit mandate that will allow you to setup payments.
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
);confirm_resource
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
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 =>
);SEE ALSO
Business::GoCardless::Resource
Business::GoCardless::Subscription
Business::GoCardless::Webhook::V2
AUTHOR
Lee Johnson - leejo@cpan.org
LICENSE
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