Skip to main content
Version: 2.0.0

Settings

This page explains every GoCardless setting and where to find it. Open settings in Craft CP:

GoCardless -> Settings (gocardless/settings).

Settings are split into five tabs: General, Credentials, Pricing, Restrictions, Test cards.

General tab​

  • Default payment description: the description GoCardless shows for a payment when the caller of /gocardless/pay doesn't supply one.
  • Success redirect URL / Failure redirect URL: where the customer lands after /gocardless/complete. Both accept environment variable references. Leave Success redirect URL blank to keep the default /gocardless/complete behavior (a JSON response for API clients, or a plain success page otherwise).
  • Create payment after mandate setup: when on (the default), completing the standard redirect flow immediately creates a payment against the new mandate if an amount was included in the original /gocardless/pay request. When off, only the mandate is created — charge it later from your own code with createPaymentFromMandate().

Credentials tab​

  • Environment: Sandbox or Live. Use sandbox while testing — live creates real mandates and takes real payments.
  • Access token: the GoCardless API access token for the selected environment. Supports environment variable references, e.g. $GOCARDLESS_ACCESS_TOKEN.
  • Webhook secret: must match the signing secret configured on your GoCardless webhook endpoint. Inbound webhooks that don't match this secret are rejected.
  • Enable Pro features: unlocks billing requests, subscriptions, refunds, and other Pro-only service methods, and adds the Subscriptions item to the CP navigation.
  • Pro access token: optional. Leave blank to reuse Access token for Pro calls. Set a separate value when a client account has distinct Pro credentials.
  • Creditor ID: optional. Used for Pro partner and multi-creditor integrations.

Required fields: Access token is required once the plugin is enabled; Pro access token is required once both Enabled and Enable Pro features are on (falls back to Access token if left blank in that case too, per the model default — but fill it in explicitly for clarity in multi-creditor setups).

Pricing tab​

  • Default currency: three-letter ISO 4217 currency code (e.g. GBP, EUR). Used whenever a /gocardless/pay request omits currency. The value is uppercased and trimmed automatically on save, and must match the AAA pattern.

Restrictions tab​

GoCardless does not support country or date-range restrictions at the plugin level — this tab is informational only. Availability (supported countries, currencies, Direct Debit schemes) is controlled entirely by your GoCardless account configuration, not by plugin settings.

Test cards tab​

GoCardless is Direct Debit, so there are no card numbers to test with:

  1. Set Environment to Sandbox in the Credentials tab and use a sandbox access token.
  2. Run the full mandate and payment flow — GoCardless simulates mandate confirmations automatically for sandbox accounts, using GoCardless-provided test bank accounts.

Validation and save behavior​

  • Environment must be sandbox or live.
  • Default currency must be exactly three uppercase letters.
  • Success redirect URL / Failure redirect URL must be valid URLs when set (HTTPS assumed if no scheme is given); both may be left blank.
  • Access token is required whenever the plugin is enabled; Pro access token is additionally required whenever Pro features are enabled on an enabled plugin.
  • Saving redirects back to the active settings tab and shows a Craft success/error notice as usual. A Test connection action (gocardless/settings/test-connection) is available to verify the configured credentials can reach the GoCardless API without leaving the settings page.
  1. Install the plugin, then open Credentials and set Environment to Sandbox with a sandbox access token.
  2. Set Webhook secret to match a webhook endpoint you've registered in the GoCardless dashboard pointing at /gocardless/webhook.
  3. Adjust General (description, redirect URLs, whether to auto-create a payment after mandate setup) and Pricing (default currency) to match your store.
  4. Run a full test payment through /gocardless/pay → GoCardless → /gocardless/complete, and confirm it shows up under Payments and Mandates in the CP.
  5. Only after a successful sandbox run, switch Environment to Live and swap in the live access token (and Pro access token, if used).
  6. Enable Enable Pro features only if you need billing requests, subscriptions, or refunds beyond the base flow.

Troubleshooting​

Webhooks aren't showing up under "Webhooks"​

Confirm the endpoint registered in the GoCardless dashboard is exactly /gocardless/webhook on your site, and that Webhook secret in Credentials matches the secret configured for that endpoint — a mismatch causes the signature check to fail and the event to be rejected before it's recorded.

"Access token" validation error even though a value looks set​

The field is required whenever the plugin is Enabled. If you're using an environment variable reference (e.g. $GOCARDLESS_ACCESS_TOKEN), confirm the variable is actually defined in .env — the settings form only validates that a value is present, not that the referenced environment variable resolves to something.

A payment isn't created after the customer completes the mandate​

Check Create payment after mandate setup in the General tab, and confirm the original /gocardless/pay request included an amount greater than zero — without both, only the mandate is created.

Pro-only CP pages or MCP tools aren't available​

Confirm Enable Pro features is switched on in Credentials. The Subscriptions CP navigation item and Pro-gated behavior only appear once this is on.