Skip to main content

GoCardless Gateway

Zuora

GoCardless Gateway

GoCardless powers recurring payments for over 50,000 businesses around the world, from growing businesses to household names in software, media and technology. Zuora’s integration to GoCardless makes it simple to accept a variety of recurring and one-off payments through the first global Direct Debit network of the world.

The following video is provided by GoCardless for your reference. It demonstrates the integration between Zuora and the GoCardless gateway. It does not necessarily reflect the latest version of the Zuora UI. You can click GoCardlessVideoCCIcon.png on the video toolbar to change the subtitles to your preferred language.

You must use the GoCardless Pro package and have the Custom Payment Page feature enabled to work with the GoCardless integration in Zuora.

Supported Payment Method

  • ACH
  • Bank Transfer, including:
    • Direct Debit UK (BACS)
    • SEPA
    • AU Direct Entry (BECS)
    • Direct Debit NZ (BECS)
    • Denmark Direct Debit (Betalingsservice)
    • Sweden Direct Debit (Autogiro)
    • Canadian Pre-Authorized Debit (PAD)

For the SEPA payment method, you must use the International Bank Account Number (IBAN) to create payment methods. Different schemes are used on the GoCardless side corresponding to different country codes in IBAN. For example, if the IBAN is set to "GB60BARC20000055779911", the scheme used by GoCardless will be “Bacs". If IBAN is set to "FR1420041010050500013M02606", the scheme used by GoCardless will be "sepa_core".

Supported Currencies

GoCardless supports the following currencies:

  • USD (ACH)
  • GBP (Direct Debit UK, SEPA)
  • EUR (SEPA)
  • AUD (AU Direct Entry)
  • SEK (Autogiro)
  • DKK (Betalingsservice)
  • NZD (Direct Debit NZ)
  • CAD (Canadian PAD)

Supported Payment Operations

  • Set up of Service User Number (for Bacs) and Creditor ID (for SEPA)
  • Set up Direct Debit mandate and validate bank details, either online, over the phone or via paper
  • Collect payments automatically
  • One-off, ad-hoc, recurring and pre-payments
  • Real-time alerts for failed or cancelled payments and check status of all payments in Zuora
  • Retry failed payments automatically
  • Refund payments (full or partial refunds) via Faster Payments or SEPA Credit Transfer
  • Simple to transfer existing Direct Debit mandates from another provider to GoCardless and Zuora
  • Sandbox environment available for full testing
  • Support for the following ACH payment operations:
    • Validation
    • Payment
    • Refund
    • Credit
    • Void
  1. Supported Gateway Reconciliation Event Types

  2. GoCardless Gateway supports the following Gateway Reconciliation event types:
  • Settlement
  • Rejection
  • Chargeback
  • Mandate Rejected
  • Mandate Cancelled
  • Mandate Expired
  • Mandate Reinstated
  • Mandate Transferred
  • Mandate Replaced

Prerequisites

You will need to obtain the following information from GoCardless before configuring the GoCardless payment gateway in Zuora:

Note that only one OAuth token can be active at a time. It indicates that you cannot use the same Creditor ID across multiple tenants. 

Configure the GoCardless Gateway Instance

  1. Navigate to Zuora Payments Settings > Setup Payment Gateway
  2. Select GoCardless from the Gateway Type drop-down menu.
  3. Click create gateway.

Zuora Configuration Fields

There are some common fields you must complete for every gateway configuration. We recommend reviewing Setting Up Payment Gateways for information on these fields: 

  • Type
  • Name
  • Use Gateway Test Environment
  • Default Authorization Amount
  • Verify new payment method (required)
  • Verify updated payment method (optional)
  • Enable gateway reconciliation: If you select this checkbox, it will trigger a daily job to reconcile all payment events processed through the gateway. 

In addition to the common fields, you must provide the credentials information.

  • OAuth Token: Select the created OAuth 2.0 token from the OAuth Token dropdown list. You can navigate to Payments Settings > Gateway Authentication to create a new token or view all available tokens. For more information about how to create OAuth tokens in Zuora, see Payment Gateway Authentication.

    One merchant account can have only one active OAuth token. The previous token is automatically expired on the GoCardless end when the new token is created. If a separate token is required because multiple environments are used, please contact GoCardless for a separate testing MID.

  • Access Token (read-only): Only available for the gateway instances created before Zuora Billing Release 289. 
  • Creditor ID (read-only): Only available for the gateway instances created before Zuora Billing Release 289. 

Once you have entered the necessary information, click save gateway information.

Note that for the GoCardless gateway instances created before Zuora Billing Release 289, the previously stored Access Token and Creditor ID credentials can continue to work, but you cannot update them anymore. If you want to switch to the OAuth authentication mode, you can create an OAuth token and select it from the OAuth Token dropdown list. The OAuth 2.0 authentication is then enabled for all subsequent requests.

GoCardless Refunds

  1. GoCardless payments can only be refunded two days after the payment has been processed. If a refund is performed prior to the two day delay, the call will fail and return the following error message: "invalid_state – A refund is not possible on this payment."

  2. For further information on getting the most out of the GoCardless integration for Zuora, contact the GoCardless team on hello@gocardless.com.

  1. Batch GR Event Mapping between GoCardless and Zuora 

    The gateway reconciliation batch job on the GoCardless side starts at 6:30 am PT every day. Within a GR job, every record in the gateway reconciliation report is parsed into an event and matched with the corresponding Zuora transaction.

  2. The following table lists the event mapping between GoCardless and Zuora in gateway reconciliation.

  3. Object GoCardless Action Zuora Event Zuora Action
    Mandate reinstated MandateReinstated Zuora reactivates the payment method.
    Mandate canceled MandateCanceled Zuora closes the payment method.
    Mandate failed MandateRejected Zuora closes the payment method.
    Mandate expired MandateExpired Zuora closes the payment method.
    Mandate resubmission_requested MandateReinstated Zuora reactivates the payment method.
    Payment customer_approval_denied TransactionRejected
    • Zuora updates the Gateway State to "Failed to Settle" on the Payment transaction.
    • Zuora creates an External Refund with the Reason Code set to "Payment Rejection".
    Payment confirmed TransactionSettled Zuora updates the Gateway State to "Settled" and the Settled On date field of the Payment event.
    Payment cancelled TransactionRejected
    • Zuora updates the Gateway State to "Failed to Settle" on the Payment transaction.
    • Zuora creates an External Refund with the Reason Code set to "Payment Rejection".
    Payment failed TransactionRejected
    • Zuora updates the Gateway State to "Failed to Settle" on the Payment transaction.
    • Zuora creates an External Refund with the Reason Code set to "Payment Rejection".
    Payment charged_back TransactionReversed Optionally, Zuora creates an External Refund with the Reason Code set to "Payment Reversal."
    Payment late_failure_settled TransactionReversed Optionally, Zuora creates an External Refund with the Reason Code set to "Payment Reversal."
    Refund paid TransactionSettled Zuora updates the Gateway State to "Settled" and the Settled On date field of the Refund event.
    Refund refund_settled TransactionSettled Zuora updates the Gateway State to "Settled" and the Settled On date field of the Refund event.
  1. Real-Time Reconciliation 

Real-time Reconciliation is an Early Adopter feature. If you want to use this feature, submit a request at Zuora Global Support.

With Real-Time Reconciliation enabled, the payment gateway can submit notifications to Zuora for various event types on gateway objects, and the corresponding records can be automatically updated in real time.

Currently, this feature is only supported by the GoCardless gateway.

Prerequisites

  • A GoCardless gateway instance has been configured in Zuora.
  • You have created at least one authentication mechanism set up through the Gateway Authentication payment setting.

Configure Real-Time Reconciliation

  1. Navigate to Payments Settings > Configure Real-Time Reconciliation. This page displays all available webhooks. Each time you create an authentication mechanism such as OAuth through the Gateway Authentication payment setting, a corresponding webhook is automatically added to this page.
  2. Find the webhook you want to use, and click Activate to activate this webhook.

After the webhook is activated, updates to different gateway events will be reflected in Zuora in real time.

Real-time Reconciliation Event Mapping between GoCardless and Zuora

The following table lists Zuora's actions on GoCardless events when the Real-time Gateway Reconciliation feature is enabled. 

GoCardless event type GoCardless event Zuora action
Mandate created Zuora ignores this event because the payment method is created.
customer_approval_granted N/A
customer_approval_skipped N/A
active N/A
submitted N/A
reinstated Zuora activates the payment method.
cancelled Zuora closes the payment method.
failed Zuora closes the payment method.
transferred N/A
expired Zuora closes the payment method.
resubmission_requested Zuora activates the payment method.
replaced N/A
Payment customer_approval_denied
  • Zuora updates the Gateway State to "Failed to Settle" on the Payment transaction.
  • Zuora creates an External Refund with the Reason Code set to "Payment Rejection".
confirmed Zuora updates the Gateway State to "Settled" and the Settled On date field of the Payment event.
cancelled
  • Zuora updates the Gateway State to "Failed to Settle" on the Payment transaction.
  • Zuora creates an External Refund with the Reason Code set to "Payment Rejection".
failed
  • Zuora updates the Gateway State to "Failed to Settle" on the Payment transaction.
  • Zuora creates an External Refund with the Reason Code set to "Payment Rejection".
charged_back
  • Zuora updates the Gateway State to "Settled" on the Payment transaction.
  • Zuora creates an External Refund.
chargeback_cancelled N/A
late_failure_settled
  • Zuora updates the Gateway State to "Settled" on the Payment transaction.
  • Zuora creates an External Refund.
created N/A
customer_approval_granted N/A
submitted N/A
paid_out N/A
chargeback_settled N/A
surcharge_fee_credited N/A
surcharge_fee_debited N/A
Refund paid N/A
refund_settled N/A
created N/A
failed N/A
refund_returned N/A
Payout paid Update payment
fx_rate_confirmed N/A
tax_exchange_rates_confirmed N/A

Limitations of Real-Time Reconciliation

  • The Real-Time Reconciliation feature is not supported in the Zuora Central Sandbox environment.
  • The Real-Time Reconciliation feature is not compatible with Multi-entity.

Supported Gateway Option Fields 

You can submit additional information to the GoCardless gateway using gateway options. Currently, Zuora's GoCardless gateway integration only supports the InvoiceNum field. This field can be used in Payment Pages 2.0SOAP API, or the following REST API:

Note that this gateway option field is mapped to the reference field in the Create a payment operation of GoCardless. So the character limit forreference also applies to the InvoiceNum gateway option field. Refer to GoCardless's documentation for the character limit details.

If you have enabled the Bacs custom mandate feature on the gateway side, refer to Bacs custom mandate reference guide for additional requirements.

Testing Your Configuration 

We recommend that you test your payment gateway by using both your payment gateway's test and production (live) environments.  Once you have completed testing in the gateway's test environment, it is recommended that you perform a test in your live production environment with real information. If there are any differences in the configuration of your testing and production accounts, testing in production ensures your production merchant account is set up properly and can successfully connect to the production environment.

You can use the testing scenarios provided by the gateway vendor to test your integration. See Test bank details in GoCardless guides for details.