/ 
Business-GoCardless-1.00
⭐ Starred 1 / Business::GoCardless::Client

NAME

Business::GoCardless::Client

DESCRIPTION

This is a class for the lower level requests to the gocardless API. generally there is nothing you should be doing with this.

ATTRIBUTES

token

Your gocardless API token, this attribute is required.

base_url

The gocardless API URL, defaults to $ENV{GOCARDLESS_URL} or https://gocardless.com.

api_path

The gocardless API path, defaults to /api/v1.

app_id

Your gocardless app identifier, defaults to $ENV{GOCARDLESS_APP_ID} or will exit if not set.

app_secret

Your gocardless app secret, defaults to $ENV{GOCARDLESS_APP_SECRET} or will exit if not set.

webhook_secret

Your gocardless webhook secret, defaults to $ENV{GOCARDLESS_WEBHOOK_SECRET} or will exit if not set.

This can also be an arrayref of secrets, in which case a webhook is valid if its signature matches any of them. This allows you to rotate your webhook secret, or receive webhooks from more than one webhook endpoint, without rejecting webhooks:

webhook_secret => [ $new_secret,$old_secret ],

merchant_id

Your gocardless merchant identifier, defaults to $ENV{GOCARDLESS_MERCHANT_ID} or will exit if not set.

user_agent

The user agent string used in requests to the gocardless API, defaults to business-gocardless/perl/v . $version_of_this_library . - . $api_version

The following attributes only apply to the Pro (v2) API:

max_retries

The number of times to retry a request that failed due to a network error, a server error (500, 502, 503, 504), or being rate limited (429). Defaults to 3, set to 0 to disable retries. Retry delays back off exponentially from 0.5s.

Requests are only retried if it is safe to do so: GET, PUT, and DELETE requests, and POST requests that create a resource (as these have an idempotency key, see "IDEMPOTENCY KEYS"). POST requests to actions (e.g. cancelling a payment) are only retried if they were rate limited, as the request will not have been processed by GoCardless in that case.

max_retry_wait

When rate limited, requests are retried after the time given in the ratelimit-reset response header. If that is more than this many seconds away the request is not retried and an exception is thrown. Defaults to 60.

raise_on_idempotency_conflict

If a create request gets an idempotent_creation_conflict error, which means a resource has already been created with the idempotency key, then by default the existing resource is fetched and returned. Set this to true to throw an exception instead, you can get the ID of the existing resource with the exception's "conflicting_resource_id" in Business::GoCardless::Exception method.

rate_limit

A hashref of the rate limit details from the most recent response from the API, or undef if no request has been made yet:

my $rate_limit = $Client->rate_limit;

# {
#     limit     => 1000,
#     remaining => 999,
#     reset     => 'Thu, 03 May 2018 16:00:00 GMT', # as sent by gocardless
#     reset_at  => 1525363200,                     # reset as epoch seconds
# }

METHODS

api_get
api_post
api_put
api_delete

Make a request to the gocardless API:

my $data = $Client->api_get( '/merchants/123ABCD/bills',\%params );

In list context returns the links and pagination headers:

my ( $data,$links,$info ) = $Client->api_get( ... );

All of the methods take an optional hashref of additional headers to send with the request as the third argument:

my $data = $Client->api_post(
    '/payments',
    { payments => { ... } },
    { 'Idempotency-Key' => $your_idempotency_key },
);

Failed requests will throw a Business::GoCardless::Exception, and may be retried before doing so (see "max_retries").

IDEMPOTENCY KEYS

When using the Pro (v2) API all requests that create a resource (POST requests other than to actions) are sent with an Idempotency-Key header, so that they can be safely retried without creating duplicate resources (payments, etc). A random key is generated for each request, or you can pass your own as shown above if you want to make sure the same resource isn't created across separate calls (for example on resubmission of a form). See https://developer.gocardless.com/api-reference/#making-requests-idempotency-keys and "raise_on_idempotency_conflict".

AUTHOR

Lee Johnson - lee@payprop.com

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