Skip to main content

Configure Real-Time Reconciliation

Zuora

Configure Real-Time Reconciliation

  1. Last updated
  2. Save as PDF

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.

For information on integrations that are requested through the Specialized Payment Connections service, see the article for the specific payment gateway integration.

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 the service URL using the <Zuora_Data_Center_URL>/payment-reconciliation-webhook/adyen/v1 format, such as https://rest.sandbox.na.zuora.com/payment-reconciliation-webhook/adyen/v1. You can know which data center you are in by checking the URL of your environment. For details about Zuora environments, see Zuora Data Centers.
      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
        • OFFER_CLOSED
      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 Adyen-RTR-icon.png, 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 Braintree v2.0

Prerequisites

  • A Braintree v2.0 gateway instance has been configured in Zuora.
  • Ensure that the merchant ID has not been configured for any other 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 Braintree v2.0, complete the following steps:

  1. Configure the webhook service in your Braintree merchant console.
  2. Enable Braintree Real-Time Reconciliation in Zuora.

Step 1. Configure the webhook service in your Braintree merchant console

In your Braintree merchant console, configure the webhook service by following the instructions in Braintree’s documentation. 

When configuring the service URL, use the <Zuora_Data_Center_URL>/payment-reconciliation-webhook/braintree/v1/<merchantId> format, such as https://rest.sandbox.na.zuora.com/payment-reconciliation-webhook/braintree/v1/abc12345def678y. You can know which data center you are in by checking the URL of your environment. For details about Zuora environments, see Zuora Data Centers.

Step 2. Enable Braintree Real-Time Reconciliation in Zuora

  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 merchant ID of your Braintree merchant account.
    • Gateway Type: the type of the gateway instance associated with the Real-Time Reconciliation service.
    • Gateway Identifier: the merchant ID of your Braintree merchant 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 Public Key, Private Key, Use Gateway Test Environment settings, and the user who will perform the reconciliation actions.
  2. Select Braintree from the Gateway Type dropdown list, and then click Add.
  3. In the Configuration to reconcile events section on the Enable Real-Time Reconciliation page, enter the following credentials required to validate and process the webhooks from Braintree:
    • Merchant ID
    • Public Key
    • Private Key
    • Use Gateway Test Environment: If the credentials are for the sandbox environment, select this checkbox.
  4. In the User to reconcile events section, add the user that will be used by Zuora to perform the reconciliation actions. 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.
  5. Click Submit.

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

To enable and configure Real-Time Reconciliation for GoCardless, 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 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.

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.

For dispute events, by default, external refunds are automatically generated for dispute events. If you want to opt out of this default behavior and disable the generation of external refunds for dispute events, submit a request at Zuora Global Support.

Enable and configure Real-Time Reconciliation for PayPal Commerce Platform

Prerequisites

  • A PayPal Commerce Platform gateway instance has been configured in Zuora.
  • At least one OAuth token for PayPal Commerce Platform 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 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 PayPal Commerce Platform, 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 Merchant ID of the PayPal Commerce Platform 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 PayPal Commerce Platform, and then click Add.
  3. On the Enable Real-Time Reconciliation page, from the Gateway Merchant Account 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: a user from the list who has obtained the required permissions to perform reconciliation actions.
  5. Click Submit.