Skip to main content

Test payment gateway integration

Zuora

Test payment gateway integration

  1. Last updated
  2. Save as PDF

This article provides basic guidance on how to test payment gateway integrations within a sandbox environment. Testing in collaboration with both your gateway provider and Zuora helps ensure that payment flows are correctly configured and function as expected before going live.

Step 1. Define test cases

  1. Identify core scenarios.

    Develop a set of test cases that cover different payment operation types, payment methods, and currencies.

  2. Obtain test card and account information.

    Obtain the test card and account information from the gateway provider. Payment gateways often offer specific card numbers to trigger particular outcomes, such as approvals or declines. Here are some examples:

  3. Prepare error code testing.

    Confirm with your gateway provider which error codes the gateway supports and their use cases. Simulate them to verify the error-handling functionality. Different payment gateways offer different magic values to simulate gateway-side error codes in their test environments. You need to follow the gateway provider’s test instructions to simulate corresponding error codes.

    For example, Chase Orbital uses payment amount value to simulate an error code. When your payment amount is 571, the test environment of Chase Orbital returns the following codes and message:

    • Payment error code: 09 
    • Payment error message: Revocation of Authorization
    • If you review transaction details in the response string in Zuora's payment transaction log, you may find the Orbital Host response code 571.

Step 2. Set up the payment gateway test instance in Zuora

  1. Obtain test credentials.

    Obtain test credentials, such as API keys and login information, from your payment gateway provider.

  2. Ensure sandbox access.

    Ensure that Zuora's sandbox environment is connected to the gateway's test environment. Confirm with the gateway provider if any specific configurations are needed for connecting test environments. Here are a few examples:

  3. Set up payment gateway test instance.

    Set up the payment gateway instance in Zuora to operate in test mode:

    • Use the test credentials provided by the gateway to configure the instance.
    • Select Use Gateway Test Environment to direct your transactions in Zuora to your payment gateway's test environment or test simulator. Zuora will automatically mark all transactions as test and route them to the correct test environment. It is recommended that you name your gateway instance to reflect the test purpose. For example, you can name your gateway "PayPal - US (Test)."

    For detailed instructions on configuring the payment gateway instance in Zuora, see the article for each gateway integration

    To test payment processing in Zuora Central Sandbox environments, make the following configuration updates:

    1. Reconfigure a payment gateway test instance.
    2. Reconfigure the services that you want to use, such as Payment Method Updater and Gateway Reconciliation.
    3. Close all the payment methods that were copied from the other environment.
    4. Create the new test payment methods and associate them with your accounts.
  4. Add your test cards or accounts in the Zuora sandbox environment.

Step 3. Simulate, monitor, and verify transactions

  1. Simulate transactions.

    Run your test cases using the test card and account information to simulate successful and failed transactions.

  2. Check transaction results.

    Verify whether Zuora business flow works as expected. Each transaction should be updated appropriately in Zuora, with the correct status based on the gateway response.

  3. Review transaction logs.

    Review transaction logs in both Zuora and the payment gateway's test environment to verify that requests and responses align. In Zuora, you can review the following logs:

  4. Adjust error handling.

    Based on your testing, ensure that error codes or response variations provided by the gateway are handled as expected.

Step 4. Transition to production

  1. Set up the production environment.

    When configuring the payment gateway instance, do not use the test mode unless you specifically intend to use the gateway simulator for processing payments in your production environment.

  2. Test transactions in production.

    It is recommended that you test all your use cases and integrations on the payment gateway using both your payment gateway's test and production (live) environments. Once you have completed testing in the gateway's test environment, perform a test in your live production environment with a real card or account. 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.

If you are migrating between gateways, Zuora recommends a ‘warming up’ strategy, in which you start by moving smaller segments of your customer base to the new gateway and increasing traffic over time. This allows you to transition to the new gateway at your own pace while being able to fall back to your legacy gateway if needed.