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.

This module supports the resources of the GoCardless API (see "RESOURCE METHODS"), as well as being a back compatibility wrapper to allow migration from the v1 (Basic) API (see "BACK COMPATIBILITY METHODS"). Note that new integrations should use Billing Requests rather than Redirect Flows (which the back compatibility methods use), see "Setting up a mandate with a Billing Request".

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;

Any methods marked as pager have a dual interface, when called in list context they will return the first page of resource objects (50 by default, you can pass a limit filter of up to 500), when called in scalar context they will return a Business::GoCardless::Paginator object allowing you to iterate through all the objects using the API's cursor based pagination:

# 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 );

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"
    }
);

As with all of the create methods you can pass an idempotency_key, see "IDEMPOTENCY KEYS".

Subscription Methods

subscription

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 );

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 );

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( $id );

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.

Get a list of Business::GoCardless::Webhook::V2 objects.

my @webhooks = $GoCardless->webhooks

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
    ...
}

Payout Methods

See Business::GoCardless::Payout for more information on Payout operations.

Get a list of Business::GoCardless::Payout objects.

my @payouts = $GoCardless->payouts

payout

Get an individual payout, returns a Business::GoCardless::Payout object:

my $Payout = $GoCardless->payout( $id );

RESOURCE METHODS

Methods for the resources of the Pro API follow the same pattern. For example for billing requests:

# get a single resource, returns a Business::GoCardless::BillingRequest
my $BillingRequest = $GoCardless->billing_request( $id );

# get a list of resources (pager), %filters are optional
my @billing_requests = $GoCardless->billing_requests( %filters );

# create a resource, returns a Business::GoCardless::BillingRequest
my $BillingRequest = $GoCardless->create_billing_request( %params );

Operations on a resource (cancel, update, etc) are methods on the resource objects, see the documentation of each resource class for these. The parameters and filters are as documented in the GoCardless API reference. Note that some of the endpoints are restricted, for example to GoCardless Embed customers or to those with custom payment pages enabled, see the GoCardless API reference for details.

Setting up a mandate with a Billing Request

Billing Requests have replaced Redirect Flows, for example to set up a mandate using the GoCardless hosted payment pages:

my $BillingRequest = $GoCardless->create_billing_request(
    mandate_request => { scheme => 'bacs' },
);

my $Flow = $BillingRequest->create_flow(
    redirect_uri => 'https://example.com/mandate/complete',
    exit_uri     => 'https://example.com/mandate/exit',
);

# send the customer to $Flow->authorisation_url, once they have completed
# the flow GoCardless will send you a billing_requests fulfilled webhook
# (or you can check the billing request):

$BillingRequest = $GoCardless->billing_request( $BillingRequest->id );

if ( $BillingRequest->fulfilled ) {
    my $Mandate = $GoCardless->mandate( $BillingRequest->mandate_id );
    ...
}

IDEMPOTENCY KEYS

All of the create methods take an optional idempotency_key parameter, which is sent as the Idempotency-Key header rather than in the request body. If you don't pass one a random key is generated for the request. See "IDEMPOTENCY KEYS" in Business::GoCardless::Client for more details.

my $Payment = $GoCardless->create_payment(
    %params,
    idempotency_key => $your_unique_key,
);

Mandates

See Business::GoCardless::Mandate

my @mandates = $GoCardless->mandates( %filters );
my $Mandate = $GoCardless->create_mandate( %params );

Subscriptions

See Business::GoCardless::Subscription

my $Subscription = $GoCardless->create_subscription( %params );

Customers

See Business::GoCardless::Customer

my $Customer = $GoCardless->create_customer( %params );

Refunds

See Business::GoCardless::Refund

my $Refund = $GoCardless->refund( $id );
my @refunds = $GoCardless->refunds( %filters );
my $Refund = $GoCardless->create_refund( %params );

Events

See Business::GoCardless::Webhook::Event

my $Event = $GoCardless->event( $id );
my @events = $GoCardless->events( %filters );

Billing Requests

See Business::GoCardless::BillingRequest

my $BillingRequest = $GoCardless->billing_request( $id );
my @billing_requests = $GoCardless->billing_requests( %filters );
my $BillingRequest = $GoCardless->create_billing_request( %params );

Billing Request Flows

See Business::GoCardless::BillingRequestFlow

my $BillingRequestFlow = $GoCardless->create_billing_request_flow( %params );

Billing Request Templates

See Business::GoCardless::BillingRequestTemplate

my $BillingRequestTemplate = $GoCardless->billing_request_template( $id );
my @billing_request_templates = $GoCardless->billing_request_templates( %filters );
my $BillingRequestTemplate = $GoCardless->create_billing_request_template( %params );

Bank Authorisations

See Business::GoCardless::BankAuthorisation

my $BankAuthorisation = $GoCardless->bank_authorisation( $id );
my $BankAuthorisation = $GoCardless->create_bank_authorisation( %params );

Institutions

See Business::GoCardless::Institution

my @institutions = $GoCardless->institutions( %filters );

Customer Bank Accounts

See Business::GoCardless::CustomerBankAccount

my $CustomerBankAccount = $GoCardless->customer_bank_account( $id );
my @customer_bank_accounts = $GoCardless->customer_bank_accounts( %filters );
my $CustomerBankAccount = $GoCardless->create_customer_bank_account( %params );

Bank Details Lookups

See Business::GoCardless::BankDetailsLookup

my $BankDetailsLookup = $GoCardless->create_bank_details_lookup( %params );

Creditors

See Business::GoCardless::Creditor

my $Creditor = $GoCardless->creditor( $id );
my @creditors = $GoCardless->creditors( %filters );
my $Creditor = $GoCardless->create_creditor( %params );

Creditor Bank Accounts

See Business::GoCardless::CreditorBankAccount

my $CreditorBankAccount = $GoCardless->creditor_bank_account( $id );
my @creditor_bank_accounts = $GoCardless->creditor_bank_accounts( %filters );
my $CreditorBankAccount = $GoCardless->create_creditor_bank_account( %params );

Verification Details

See Business::GoCardless::VerificationDetail

my @verification_details = $GoCardless->verification_details( %filters );
my $VerificationDetail = $GoCardless->create_verification_detail( %params );

Instalment Schedules

See Business::GoCardless::InstalmentSchedule

my $InstalmentSchedule = $GoCardless->instalment_schedule( $id );
my @instalment_schedules = $GoCardless->instalment_schedules( %filters );

Tax Rates

See Business::GoCardless::TaxRate

my $TaxRate = $GoCardless->tax_rate( $id );
my @tax_rates = $GoCardless->tax_rates( %filters );

Mandate Imports

See Business::GoCardless::MandateImport

my $MandateImport = $GoCardless->mandate_import( $id );
my $MandateImport = $GoCardless->create_mandate_import( %params );

Mandate Import Entries

See Business::GoCardless::MandateImportEntry

my @mandate_import_entries = $GoCardless->mandate_import_entries( %filters );
my $MandateImportEntry = $GoCardless->create_mandate_import_entry( %params );

Transferred Mandates

See Business::GoCardless::TransferredMandate

my $TransferredMandate = $GoCardless->transferred_mandate( $id );

Payout Items

See Business::GoCardless::PayoutItem

my @payout_items = $GoCardless->payout_items( %filters );

Balances

See Business::GoCardless::Balance

my @balances = $GoCardless->balances( %filters );

Negative Balance Limits

See Business::GoCardless::NegativeBalanceLimit

my @negative_balance_limits = $GoCardless->negative_balance_limits( %filters );

Currency Exchange Rates

See Business::GoCardless::CurrencyExchangeRate

my @currency_exchange_rates = $GoCardless->currency_exchange_rates( %filters );

Blocks

See Business::GoCardless::Block

my $Block = $GoCardless->block( $id );
my @blocks = $GoCardless->blocks( %filters );
my $Block = $GoCardless->create_block( %params );

Logos

See Business::GoCardless::Logo

my $Logo = $GoCardless->create_logo( %params );

Payer Themes

See Business::GoCardless::PayerTheme

my $PayerTheme = $GoCardless->create_payer_theme( %params );

Scheme Identifiers

See Business::GoCardless::SchemeIdentifier

my $SchemeIdentifier = $GoCardless->scheme_identifier( $id );
my @scheme_identifiers = $GoCardless->scheme_identifiers( %filters );
my $SchemeIdentifier = $GoCardless->create_scheme_identifier( %params );

Exports

See Business::GoCardless::Export

my $Export = $GoCardless->export( $id );
my @exports = $GoCardless->exports( %filters );

Outbound Payments

See Business::GoCardless::OutboundPayment

my $OutboundPayment = $GoCardless->outbound_payment( $id );
my @outbound_payments = $GoCardless->outbound_payments( %filters );
my $OutboundPayment = $GoCardless->create_outbound_payment( %params );

Outbound Payment Imports

See Business::GoCardless::OutboundPaymentImport

my $OutboundPaymentImport = $GoCardless->outbound_payment_import( $id );
my @outbound_payment_imports = $GoCardless->outbound_payment_imports( %filters );
my $OutboundPaymentImport = $GoCardless->create_outbound_payment_import( %params );

Outbound Payment Import Entries

See Business::GoCardless::OutboundPaymentImportEntry

my @outbound_payment_import_entries = $GoCardless->outbound_payment_import_entries( %filters );

Bank Account Holder Verifications

See Business::GoCardless::BankAccountHolderVerification

my $BankAccountHolderVerification = $GoCardless->bank_account_holder_verification( $id );
my $BankAccountHolderVerification = $GoCardless->create_bank_account_holder_verification( %params );

Payment Accounts

See Business::GoCardless::PaymentAccount

my $PaymentAccount = $GoCardless->payment_account( $id );
my @payment_accounts = $GoCardless->payment_accounts( %filters );

Payment Account Transactions

See Business::GoCardless::PaymentAccountTransaction

my $PaymentAccountTransaction = $GoCardless->payment_account_transaction( $id );

OTHER RESOURCE METHODS

The following methods are for API endpoints that don't follow the standard pattern of the "RESOURCE METHODS".

create_billing_request_with_actions

Create a billing request and perform actions on it in a single request (this is restricted to custom payment pages, and doesn't support ACH/PAD). Returns a Business::GoCardless::BillingRequest object, and in list context also the Business::GoCardless::BankAuthorisation if one was created:

my ( $BillingRequest,$BankAuthorisation )
    = $GoCardless->create_billing_request_with_actions(
        payment_request => { amount => 1000,currency => 'GBP' },
        actions         => {
            collect_customer_details  => { ... },
            create_bank_authorisation => JSON::true,
        },
    );

create_instalment_schedule_with_dates

Create an Business::GoCardless::InstalmentSchedule with the dates of each instalment:

my $Schedule = $GoCardless->create_instalment_schedule_with_dates(
    name         => 'Bike',
    currency     => 'GBP',
    total_amount => 3000,
    instalments  => [
        { charge_date => '2026-11-01',amount => 1500 },
        { charge_date => '2026-12-01',amount => 1500 },
    ],
    links => { mandate => $mandate_id },
);

create_instalment_schedule_with_schedule

Create an Business::GoCardless::InstalmentSchedule with a schedule from which the instalment dates are calculated:

my $Schedule = $GoCardless->create_instalment_schedule_with_schedule(
    name         => 'Bike',
    currency     => 'GBP',
    total_amount => 3000,
    instalments  => {
        start_date    => '2026-11-01',
        interval      => 1,
        interval_unit => 'monthly',
        amounts       => [ 1500,1500 ],
    },
    links => { mandate => $mandate_id },
);

Instalment schedules are created asynchronously, so the status will be pending until it becomes active (or creation_failed).

create_mandate_pdf

Create a Business::GoCardless::MandatePdf, the PDF can be in a language other than English by passing accept_language:

my $Pdf = $GoCardless->create_mandate_pdf(
    links           => { mandate => $mandate_id },
    accept_language => 'fr', # optional
);

my $url = $Pdf->url;

bank_account_detail

Get the encrypted bank account details of a customer bank account (restricted to the Encrypted Bank Details Access upgrade), you must pass the ID of your public key. Returns a Business::GoCardless::BankAccountDetail object:

my $Detail = $GoCardless->bank_account_detail( $bank_account_id,$key_id );

funds_available

Check if funds are available for a VRP mandate, returns true or false:

if ( $GoCardless->funds_available( $mandate_id,$amount ) ) {
    ...
}

block_by_ref

Create blocks for the details of a customer or mandate, returns a list of the Business::GoCardless::Block objects created:

my @blocks = $GoCardless->block_by_ref(
    reference_type  => 'customer',
    reference_value => $customer_id,
    reason_type     => 'no_intent_to_pay',
);

run_scenario_simulator

Run a scenario simulator against a resource (sandbox only), for example to simulate a payment being paid out:

$GoCardless->run_scenario_simulator( 'payment_paid_out',$payment_id );

See https://developer.gocardless.com/api-reference/#testing-scenario-simulators for the available scenarios.

create_outbound_payment_withdrawal

Create an Business::GoCardless::OutboundPayment to withdraw funds to your verified business bank account:

my $Withdrawal = $GoCardless->create_outbound_payment_withdrawal(
    amount => 1000,
    scheme => 'faster_payments',
);

outbound_payment_stats

Get the statistics of your outbound payments, returns a hashref:

my $stats = $GoCardless->outbound_payment_stats;

Get a list of the Business::GoCardless::PaymentAccountTransaction objects for a payment account:

my @transactions = $GoCardless->payment_account_transactions(
    $payment_account_id,
    value_date_from => '2026-10-01',
    value_date_to   => '2026-10-31',
);

handle_customer_notification

Handle a customer notification (meaning you have sent it rather than GoCardless), returns a Business::GoCardless::CustomerNotification object:

$GoCardless->handle_customer_notification( $notification_id );

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.

The new_bill_url, new_pre_authorization_url, and new_subscription_url methods all return a URL for redirecting the user to to complete a direct debit mandate that will allow you to setup payments, and they all take the same parameters.

See https://developer.gocardless.com/api-reference/#redirect-flows-create-a-redirect-flow for more information.

new_bill_url

Return a redirect flow URL for setting up a one off payment

new_pre_authorization_url

Return a redirect flow URL for setting up a mandate

new_subscription_url

Return a redirect flow URL for setting up a subscription

All three methods take the following parameters:

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         =>
);

AUTHOR

Lee Johnson - lee@payprop.com

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/payprop/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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	Go to GitHub issues (only if GitHub is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)