Skip to main content

Configure Real-Time Reconciliation

Zuora

Configure Real-Time Reconciliation

The Real-Time Reconciliation feature is supported by the following gateway integrations. Click each link to see detailed instructions for configuring Real-Time Reconciliation for different gateways.

User permission requirements

The user configured to perform Real-Time Reconciliation actions must have the following permissions, if the Invoice Settlement feature is enabled on your tenant. Contact your tenant administrator to update the user role or corresponding permissions.

Enable and configure Real-Time Reconciliation for Adyen Integration v2.0

Prerequisites

  • An Adyen Integration v2.0 gateway instance has been configured in Zuora.
  • Ensure that the merchant ID has not been configured for any tenant or entity for Real-Time Reconciliation enablement. Configuring one merchant ID for multiple entities or tenants in the same environment for Real-Time Reconciliation is not supported.

Procedure

To enable and configure Real-Time Reconciliation for Adyen v2.0, complete the following steps:

  1. Configure a webhook in your Adyen merchant console.
  2. Enable Adyen Real-Time Reconciliation in Zuora.
  3. Enable the webhook configuration and validate.

Step 1. Configure a webhook in your Adyen merchant console

  1. Log in to your Adyen merchant console and navigate to Developers > Webhooks.
  2. On the Webhooks page, click Settings, ensure Recurring contract is selected, and then click Save.
  3. On the Webhooks page, click Webhook to add a webhook.
  4. In the Standard webhook row, click Add.
  5. Configure the webhook settings:
    1. Edit the Server configuration setting:
      1. Click the Edit icon in the General > Server configuration section.
      2. In the URL field, enter one of the following URLs according to the Zuora environment you are using. You can know which environment you are in by checking the URL of your environment. For details about Zuora environments, see Zuora Data Centers.
        Zuora Environment URL
        EU sandbox https://rest.sandbox.eu.zuora.com/payment-reconciliation-webhook/adyen/v1
        US Cloud Data Center 1 sandbox https://rest.sandbox.na.zuora.com/payment-reconciliation-webhook/adyen/v1
        US Cloud Data Center 2 sandbox https://rest.apisandbox.zuora.com/payment-reconciliation-webhook/adyen/v1
        US Cloud Data Center 1 central sandbox https://rest.test.zuora.com/payment-reconciliation-webhook/adyen/v1
        EU central sandbox https://rest.test.eu.zuora.com/payment-reconciliation-webhook/adyen/v1
        EU production https://rest.eu.zuora.com/payment-reconciliation-webhook/adyen/v1
        US Cloud Data Center 1 production https://rest.na.zuora.com/payment-reconciliation-webhook/adyen/v1
        US Cloud Data Center 2 production https://rest.zuora.com/payment-reconciliation-webhook/adyen/v1
      3. Keep default values for the other fields.
      4. Click Apply.
    2. Edit the Merchant accounts setting:
      1. Click the Edit icon in the General > Merchant accounts section.
      2. Select only the merchant account that this webhook is indended for. If you select multiple accounts, in the later Step 2, you will need to provide the required information about each of the merchant accounts to Zuora to enable Real-Time Reconciliation.
      3. Click Apply.
    3. Edit the Events setting:
      1. Click the Edit icon in the General > Events section.
      2. Select the following options:
        • AUTHORISATION
        • CANCEL_OR_REFUND
        • CHARGEBACK
        • PAYOUT_THIRDPARTY
        • RECURRING_CONTRACT
        • REFUND
        • REFUND_FAILED
      3. Click Apply.
    4. Edit the risk setting:
      1. Click the Edit icon in the Additional settings > Risk section.
      2. Select Include Gross Currency Chargeback Details.
      3. Click Apply.
    5. Generate an HMAC key:
      1. Click the Edit icon in the Security > HMAC Key section.
      2. Ensure Generate new key is selected and click Generate.
      3. Copy and store the key in your device. In the later Step 2, you will need to provide this key to Zuora to enable Real-Time Reconciliation.
      4. Click Apply.
  6. Click Save changes. The webhook is saved in active status. Before Real-Time Reconciliation is enabled in Zuora, it is suggested to disable the webhook.
  7. To disable the webhook, on the Webhooks page, hover over the webhook you just created, click the More Options icon  , and then click Disable webhook.

Step 2. Enable Adyen Real-Time Reconciliation in Zuora

To enable and configure Real-Time Reconciliation for Adyen v2.0, complete the following steps:

  1. Click your username in the upper right and navigate to Settings > Payments > Configure Real-Time Reconciliation. This page displays all available Real-Time Reconciliation configuration mappings for active gateway authentication credentials.
    • Name: the name of your Adyen merchant account.
    • Gateway Type: the type of the gateway instance associated with the Real-Time Reconciliation service.
    • Gateway Identifier: your Adyen merchant account name.
    • User: the Zuora username of the user who performs the reconciliation actions.
    • Actions: the operations for managing the Real-Time Reconciliation configuration:
      • Delete: Delete a configuration mapping.
      • Edit: Update the HMAC key or the user who will perform the reconciliation actions.
  2. Select Adyen from the Gateway Type dropdown list, and then click Add.
  3. On the Enable Real-Time Reconciliation page, add the merchant account and user that will be used by Zuora to perform the reconciliation actions.
    1. In the Gateway Merchant Account field, enter your Adyen merchant account name. It must be identical to the value of the Merchant Account field on your Adyen gateway instance configuration page in Zuora.
    2. In the HMAC Key field, enter the HMAC key that you generated in Step 1 Configure a webhook in your Adyen merchant console.
    3. In the User to reconcile events section, select any of the following options. Ensure the user has obtained the required permissions. Note that only users created through the Zuora UI are loaded in the list. Users created through One ID are not available in the list.
      • Current User: the user who is logging in to Zuora and performing this Real-Time Reconciliation enablement.
      • Select a User: Select a user from the list who has obtained the required permissions to perform reconciliation actions.
  4. Click Submit.

Step 3. Enable the webhook configuration and validate

After Real-Time Reconciliation is enabled in Zuora, complete the following steps to enable and test the webhook in Adyen merchant console:

  1. Log in to your Adyen merchant console and navigate to Developers > Webhooks.
  2. On the Webhooks page, hover over the webhook you created, click the More Options icon, and then click Enable webhook.

Test this webhook by clicking Test configuration, and then follow the wizard to complete the test. For more information about the test, see Adyen's Webhooks documentation.

Enable and configure Real-Time Reconciliation for GoCardless 

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.
  • Ensure that the merchant account ID has not been configured for any tenant for Real-Time Reconciliation enablement. If an account ID is configured for multiple tenants with Real-Time Reconciliation enabled, only one tenant can receive the Real-Time Reconciliation events.

Procedure

The procedure to enable and configure GoCardless Real-Time Reconciliation varies across different Zuora environments. You can know which environment you are in by checking the URL of your environment. For more information, see Zuora Data Centers.

Zuora Environment Procedure
  • EU sandbox
  • US Cloud Data Center 1 sandbox
  • US Cloud Data Center 1 central sandbox
  • EU central sandbox
  • US Cloud Data Center 1 production

 

  1. Click your username in the upper right and navigate to Settings > Payments > Configure Real-Time Reconciliation. This page displays all available Real-Time Reconciliation configuration mappings for active gateway authentication tokens.
    • Name: the name of the OAuth token for gateway authentication.
    • Gateway Type: the type of the gateway instance associated with the OAuth token.
    • Gateway Identifier: the Organisation Id of the GoCardless account.
    • User: the Zuora username of the user who performs the reconciliation actions.
    • Actions: the operations for managing the Real-Time Reconciliation configuration:
      • Delete: Delete a configuration mapping.
      • Edit: Update the user who will perform the reconciliation actions.
  2. From the Gateway Type dropdown list, select GoCardless, and then click Add.
  3. On the Enable Real-Time Reconciliation page, from the Gateway Merchant Account dropdown list, select the authentication token that you have created through the Gateway Authentication payment setting.
  4. In the User to reconcile events section, select any of the following options to define the user who will be used by Zuora to perform the reconciliation actions. Ensure the user has obtained the required permissions. Note that only users created through the Zuora UI are loaded in the list. Users created through One ID are not available in the list.
    • Current User: the user who is logging in to Zuora and performing this Real-Time Reconciliation enablement.
    • Select a User: Select a user from the list who has obtained the required permissions to perform reconciliation actions.
  5. Click Submit.
  • EU production
  • US Cloud Data Center 2 sandbox
  • US Cloud Data Center 2 production
  1. Ensure the multi-entity feature is not enabled on your tenant. In these environments, the Real-Time Reconciliation feature is not compatible with the multi-entity feature.
  2. Click your username in the upper right and navigate to Settings > Payments > Configure GoCardless 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.
  3. Find the webhook you want to use, and click Activate to activate this webhook.

The GoCardless Webhook service might delay sending notifications to Zuora for 2 or 3 days. The corresponding records in Zuora will not be updated until the notifications from GoCardless are received. If you have any questions about this delay, please contact GoCardless.

Enable and configure Real-Time Reconciliation for Stripe v2 

Prerequisites 

  • A Stripe v2 gateway instance has been configured in Zuora. See Stripe payment gateway for instructions about how to create an instance of the gateway.
  • At least one OAuth token for Stripe v2 has been created and activated through the Gateway Authentication payment setting for the intended gateway instance. When creating an OAuth token, if Use Gateway Test Environment is selected, this token can only be used to enable Real-Time Reconciliation in the sandbox environment. Conversely, if Use Gateway Test Environment is not selected, the token can only be used to enable Real-Time Reconciliation in the production environment.
  • Ensure that the merchant account ID has not been configured for any tenant for Real-Time Reconciliation enablement. If an account ID is configured for multiple tenants with Real-Time Reconciliation enabled, only one tenant can receive the Real-Time Reconciliation events.

Procedure

To enable and configure Real-Time Reconciliation for Stripe v2, complete the following steps:

  1. Click your username in the upper right and navigate to Settings > Payments > Configure Real-Time Reconciliation. This page displays all available Real-Time Reconciliation configuration mappings for active gateway authentication tokens.
    • Name: the name of the OAuth token for gateway authentication.
    • Gateway Type: the type of the gateway instance associated with the OAuth token.
    • Gateway Identifier: the ID of the Stripe account associated with the OAuth token.
    • User: the Zuora username of the user who performs the reconciliation actions.
    • Actions: the operations for managing the Real-Time Reconciliation configuration:
      • Delete: Delete a configuration mapping.
      • Edit: Update the user who will perform the reconciliation actions.
  2. From the Gateway Type dropdown list, select Stripe, and then click Add.
  3. On the Enable Real-Time Reconciliation page, from the Gateway Merchant Account dropdown list, select the authentication token that you have created through the Gateway Authentication payment setting.
  4. In the User to reconcile events section, select any of the following options to define the user who will be used by Zuora to perform the reconciliation actions. Ensure the user has obtained the required permissions. Note that only users created through the Zuora UI are loaded in the list. Users created through One ID are not available in the list.
    • Current User: the user who is logging in to Zuora and performing this Real-Time Reconciliation enablement.
    • Select a User: Select a user from the list who has obtained the required permissions to perform reconciliation actions.
  5. Click Submit.