NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Packagist
Packagist, #2349 most downloaded on Packagist
GoCardless PHP Client Library
Latest stable
8.21.0
Last release 12 days ago
10 Nov 2026
Ships unpredictably
gaps range from 8 days to 13 months
Nearly every release is documented
notes for 59 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
11 years old
141 releases · first in 2015
Drag across the ruler to compare, or tap a release to open it.
Add mandate_submitted scenario simulator for Bacs, Autogiro and Betalingsservice mandates, and allow mandate_activated to run on submitted mandates
mandate_submitted scenario simulator for Bacs, Autogiro and Betalingsservice mandates, and allow mandate_activated to run on submitted mandatesThe status of an institution (enabled, disabled or temporarily_disabled) is now documented on the institution resource and exposed in the client libra
status field to institutionsThe status of an institution (enabled, disabled or temporarily_disabled) is now documented on the institution resource and exposed in the client libraries. The API already returned this field, so integrations calling the API directly are unaffected.
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Add account_information_request field on billing requests, in both create and response, and the links.account_information_request ID.
Add account_information_request field on billing requests, in both create and
response, and the links.account_information_request ID.
Update documentation links for new docs site
The legacy methods are now marked as deprecated with PHPDoc @deprecated tags. Behaviour is unchanged. IDEs and static analysers that understand PHPDoc…
Redirect Flows and Payer Authorisations are legacy APIs and cannot be used by new integrators. If you use redirectFlows() and payerAuthorisations(), migrate to Billing Requests, which cover the same flows (and more) through a single API. The integration planner is a good place to start.
The legacy methods are now marked as deprecated with PHPDoc @deprecated tags. Behaviour is unchanged. IDEs and static analysers that understand PHPDoc will flag these methods.
Includes linked resources in the response. Use customer to embed customer details, or mandate to embed mandate details.
include parameter to paymentsIncludes linked resources in the response. Use customer to embed customer details, or mandate to embed mandate details.
day_of_month documentation for subscriptions and plansFor subscriptions and plans, values 1-31 or -1 are accepted, not just 1-28.
1-28 applies to payout intervals, creditors and mandate caps.
The timeout client option already existed, but defaulted to 0, which waits indefinitely, so a stalled connection could hang forever. It now defaults t
The timeout client option already existed, but defaulted to 0, which waits indefinitely, so a stalled connection could hang forever. It now defaults to 60 seconds. If you rely on requests taking longer than that, pass a larger timeout, or 0 to restore the old behaviour:
$client = new \GoCardlessPro\Client([
'access_token' => $access_token,
'environment' => \GoCardlessPro\Environment::SANDBOX,
'timeout' => 10
]);
Timed out requests are retried automatically before an ApiConnectionException is raised, so the total time before an error can exceed timeout. The timeout option is not applied if you supply your own http_client.
PHP 8.5.12, 8.4.27, 8.3.36 and 8.2.35 fix two critical vulnerabilities that can allow unauthenticated remote code execution: CVE-2026-109618 and CVE-2…
The README now recommends always using the latest patch release of a supported PHP version.
PHP 8.5.12, 8.4.27, 8.3.36 and 8.2.35 fix two critical vulnerabilities that can allow unauthenticated remote code execution: CVE-2026-109618 and CVE-2026-109619. These vulnerabilities are in PHP itself, not in this library. If you are running an earlier version of PHP, please upgrade as soon as possible. See the PHP security advisory for more details.
Error responses whose error is a plain string (eg HTML from Cloudflare), with a status other than 400, 401, 403 or 429 (for example a 404 or 500), pre
Error responses whose error is a plain string (eg HTML from Cloudflare), with a status other than 400, 401, 403 or 429 (for example a 404 or 500), previously raised GoCardlessProException: Invalid error type and lost the message from the response. They now raise GoCardlessInternalException with the message from the response, and getType() returns gocardless as it is an internal error.
Includes linked resources in the response. Use customer to embed customer details, or bank_account to embed bank account details.
include parameter to mandatesIncludes linked resources in the response. Use customer to embed customer details, or bank_account to embed bank account details.
Remove unused definitions from schema
This field is only used in request parameters on GET requests. Parameters on GET requests are querystrings and can only ever be strings.
This field is only used in request parameters on GET requests. Parameters on GET requests are querystrings and can only ever be strings.
Therefore any attempt was rejected with "One of your parameters was incorrectly typed" - ""true" is not a boolean.".
This string enum "true" or "false" is our general pattern for parameters like this.
Add payment_request.retry_if_possible - On failure, automatically retry payments using intelligent retries. Add actions.available_country_codes - list
Add payment_request.retry_if_possible - On failure, automatically retry payments using intelligent retries.
Add actions.available_country_codes - list of currencies the current mandate supports
Updates the public institutions API to allow merchants to provide the include_disabled query param and see institution status per feature
Several resource response schemas were missing required field lists, even though the fields are always present in the actual response. Added accurate
required fields on several API resource responsesSeveral resource response schemas were missing required field lists,
even though the fields are always present in the actual response.
Added accurate required arrays (and fixed a few hardcoded docs
examples that predated them) for: payment, bank_details_lookup,
billing_request_template, currency_exchange_rate, mandate_import,
mandate_import_entry, negative_balance_limit, payer_authorisation,
payout, payout_item, refund, scenario_simulator,
scheme_identifier, tax_rate, verification_detail and logo.
This is a documentation-only change; API behaviour is unchanged.
The low-level request path was joined onto the configured base URL with a resolving join, which follows a path the way a browser follows a link. An ab
The low-level request path was joined onto the configured base URL with a resolving
join, which follows a path the way a browser follows a link. An absolute URL
(https://host/x) or a scheme-relative one (//host/x) replaced the configured
origin outright while the Authorization header was still attached, so an application
that passed untrusted input as a path could send its API token to a host of someone
else's choosing.
A path that is not a relative reference is now rejected before the join. Paths containing dot segments remain valid: they resolve against the base URL and cannot leave its origin.
A URL parameter is a single path segment — a resource identity — but the escaping
applied to one varied by language, and in Go, Node, PHP and .NET there was none at
all. A value carrying path syntax could move a request to an endpoint the caller
never asked for: find("../mandates") reached the mandates collection, and
find("?limit=500") injected a query parameter.
Escaping alone cannot fix this, because . and .. are dot segments that a path
resolver strips whether or not they are encoded, and an empty value addresses the
collection rather than one resource. Values that could change which endpoint is
addressed are therefore rejected rather than escaped: /, ?, #, control
characters, ., .. and the empty string now raise an error instead of producing a
request that quietly 404s. Everything else is escaped as before.
No valid GoCardless resource identity contains any of these characters, so correct
code is unaffected. Ruby and Java previously encoded / as %2F and sent the
request; they now raise.
Fixed postal_code and country_code fields on Scheme Identifiers to correctly allow null values.
Fixed response_body_truncated, response_headers_content_truncated, and response_headers_count_truncated fields on Webhooks to correctly allow null val
Fixed the email field in merchant_contact_details on Billing Request Flows to correctly allow null values.
Fixed the url field on Bank Authorisations to correctly allow null values.
Made account_number_ending nullable across all resources that reference this shared definition
Added language and phone_number properties to prefilled_customer in Billing Request Flows.
language and phone_number properties to prefilled_customer in Billing Request Flows.Add missing consent_parameters properties: id, scheme, currency, fixed_amount_per_payment
consent_parameters properties: id, scheme, currency, fixed_amount_per_paymentmax_amount_per_period, max_payments_per_period and end_date nullableperiod_alignment to period_alignment enumGET /institutions documentation incorrectly listing status and autocompletes_collect_bank_account fieldsThese fields are only returned by GET /billing_requests/{identity}/institutions, not by the top-level GET /institutions endpoint. This is a documentation-only fix; API behaviour is unchanged.
Only payment_created, mandate_created and subscription_created are supported for now, but the enum implied it was more event types.
Only payment_created, mandate_created and subscription_created are supported for now, but the enum implied it was more event types.
The enum is unchanged to avoid breaking consumers dependent on the ordering.
Add missing bank_name property to payer_authorisation bank_account schema
Fix nullable metadata reference in billing_request list response schema
The API and client libraries accept string or integer for amount-type fields. We only emit those same fields as integer. However, the schema incorrect
The API and client libraries accept string or integer for amount-type fields. We only emit those same fields as integer. However, the schema incorrectly specified string or integer for the response as well as the request.
Prune unused definitions from the schema
Add missing institution properties to billing_request schema
Bank details lookups now return a payer_name_verification_result field when an account_holder_name is supplied and a payer name verification check is
payer_name_verification_result to bank details lookupsBank details lookups now return a payer_name_verification_result field when an account_holder_name is supplied and a payer name verification check is performed. It can be full, close, cannot_perform_verification or null
You can now pass interval (daily, weekly, or monthly) when fetching metrics to have values aggregated over that period, instead of only receiving a si
interval param to GET /reporting/metrics for aggregating results by day, week, or monthYou can now pass interval (daily, weekly, or monthly) when fetching metrics to have values aggregated over that period, instead of only receiving a single value for the full start_date/end_date range.
Fix example values for a small number of fields to comply with the schema
Fix schema definition/component names to avoid losing types in openapi schema
Add "reference" to Create Bank Account Holder Verification
Adds null to type declarations for fields that legitimately return nil across redirect_flows, webhooks, scheme_identifiers, customer_bank_accounts, ou
Adds null to type declarations for fields that legitimately return nil across redirect_flows, webhooks, scheme_identifiers, customer_bank_accounts, outbound_payments, and billing_request_with_actions. Also adds the missing period_alignment property to mandate consent_parameters.
Adds sepa_credit_transfer and sepa_instant_credit_transfer to the complete scheme enum, adds hosted payment flow sources to the event source/type enum
Adds sepa_credit_transfer and sepa_instant_credit_transfer to the complete scheme enum, adds hosted payment flow sources to the event source/type enum, and makes creditor_type nullable for legacy creditors.
The two variants for creating an instalment_schedule were surfaced as separate functions. However, they both went to the same URL and endpoint on the
The two variants for creating an instalment_schedule were surfaced as separate functions. However, they both went to the same URL and endpoint on the backend.
This created some bugs in generating our openapi schema and therefore our API reference documentation.
Therefore, we've added specific URLs for each endpoint aliased to the original one: POST /instalment_schedules/with_dates or POST /instalment_schedules/with_schedule.
The existing POST /instalment_schedules endpoint is unchanged and will remain available for the foreseeable future.
Client libraries will now use the specific endpoint matching the method - if you are stubbing the HTTP call you may need to update those stubs.
Add remember_me to ui_components bootstrap endpoint
The "Create a mandate", "Reinstate a mandate", and "Create a customer bank account" endpoints incorrectly stated they were restricted to GoCardless Pr
The "Create a mandate", "Reinstate a mandate", and "Create a customer bank account" endpoints incorrectly stated they were restricted to GoCardless Pro and Enterprise accounts. Custom payment pages are available to any merchant — they are not package-restricted.
Update code samples to match change to integer types for amounts etc
The intention is to make it possible to define common types in generated code. Instead of ~37 different currency enum types which are all equivalent,
The intention is to make it possible to define common types in generated code. Instead of ~37 different currency enum types which are all equivalent, we could have one.
Fix typo in Mandate next_possible_standard_ach_charge_date description
Exports can now be created with resource_type: app_connected_organisations, allowing connected merchant details to be exported.
app_connected_organisations export typeExports can now be created with resource_type: app_connected_organisations, allowing connected merchant details to be exported.
Fix typo in subscription status description
Fix typo in mandate_import_entry status description
Fix typo in mandate_import_entry status description
Fix typo in mandate_import_entry status description
Use HTML in inline documentation, including working links rather than broken markdown anchors. Hopefully this provides a better user experience, pleas
Use HTML in inline documentation, including working links rather than broken markdown anchors. Hopefully this provides a better user experience, please let us know if you have any feedback.
Relax dependency to allow guzzle 7.4.x or 8.0.x
Changes from gocardless/client-library-templates by @gocardless-ci-robot[bot] in https://github.com/gocardless/gocardless-pro-php/pull/228
Changes from gocardless/client-library-templates by @gocardless-ci-robot[bot] in https://github.com/gocardless/gocardless-pro-php/pull/230
Full Changelog: https://github.com/gocardless/gocardless-pro-php/compare/v8.0.2...v8.0.3
Start of changelog tracking with Knope. See GitHub releases for the history of earlier versions.
Changes from gocardless/client-library-templates by @gocardless-ci-robot[bot] in https://github.com/gocardless/gocardless-pro-php/pull/226
Full Changelog: https://github.com/gocardless/gocardless-pro-php/compare/v8.0.1...v8.0.2
Changes from gocardless/client-library-templates by @gocardless-ci-robot[bot] in https://github.com/gocardless/gocardless-pro-php/pull/225
Full Changelog: https://github.com/gocardless/gocardless-pro-php/compare/v8.0.0...v8.0.1
Changes from gocardless/client-library-templates by @gocardless-ci-robot[bot] in https://github.com/gocardless/gocardless-pro-php/pull/222
Full Changelog: https://github.com/gocardless/gocardless-pro-php/compare/v7.5.0...v8.0.0
Stopped exposing negative balance limit creation API
Full Changelog: https://github.com/gocardless/gocardless-pro-php/compare/v7.1.0...v7.2.0
Added mandate_request_constraints to Billing Request templates
constraints[max_amount_per_payment] is required for Billing Requests Creation, if they contain PayTo mandate_requestFull Changelog: https://github.com/gocardless/gocardless-pro-php/compare/v7.0.0...v7.1.0
Important bug fixes and a few breaking changes to the following endpoint:
Full Changelog: https://github.com/gocardless/gocardless-pro-php/compare/v6.8.0...v7.0.0
Adds support for new Billing Request With Actions endpoint
Note
Use v7.0.0 onwards to make full use of the new create_with_actions endpoint. It contains some major bug fixes.
Full Changelog: https://github.com/gocardless/gocardless-pro-php/compare/v6.7.0...v6.8.0
Introduce the authenticated limits attribute to the "List Institution" endpoint, more details here https://developer.gocardless.com/api-reference/#bil
limits attribute to the "List Institution" endpoint, more details here https://developer.gocardless.com/api-reference/#billing-requests-institutionsFull Changelog: https://github.com/gocardless/gocardless-pro-php/compare/v6.6.0...v6.7.0
Changes from gocardless/gocardless-pro-php-template by @gocardless-ci-robot in https://github.com/gocardless/gocardless-pro-php/pull/203
Full Changelog: https://github.com/gocardless/gocardless-pro-php/compare/v6.5.0...v6.6.0
Added /bank_account_details API to fetch encrypted bank details
Full Changelog: https://github.com/gocardless/gocardless-pro-php/compare/v.6.4.0...v6.5.0
Added new endpoint /balance that returns the balances for a creditor
/balance that returns the balances for a creditorNothing published for this version
One column per quarter.