Skip to main content

Set up and configure a Worldline Global Collect Legacy gateway instance

Zuora

Set up and configure a Worldline Global Collect Legacy gateway instance

Worldline has ceased support for this platform and new instances of this gateway are not supported in Zuora. Please use Worldline Global Collect instead.

Prerequisites

IP address whitelist configuration

This gateway requires adding Zuora EU or US Cloud Data Center IP addresses to the whitelist for each of your gateway merchant accounts, depending on which data center that your tenant is located at. Therefore, before start using this gateway on Zuora EU or US Cloud Data Center, you must contact with the gateway to add Zuora EU or US Clould Data Center IP addresses to the gateway's whitelist for both the Sandbox and Production environments so that both environments can work properly.

For more information about the Zuora EU or US Cloud Data Center IP addresses, see Outbound IP Addresses Whitelisting.

Worldline Global Collect Legacy Merchant Account Configuration

Work with your Worldline Global Collect Legacy implementation manager to ensure your Worldline Global Collect Legacy merchant account is configured to support a two-step payment process for Sale transactions.  To do this, Worldline Global Collect Legacy will configure the delayed settlement per card type setting in your account by setting the indicator to the value to 7. This ensures the payment transactions are pending until triggered via the set_payment for settlement.

Clarification on API calls for Sale transactions: 

For Sale transactions, the integration uses a two-step process with the following Worldline Global Collect Legacy API calls: Insert Order With Payment()+ SetPayment()

  • Insert Order with Payment() - This call inserts an order and a payment in a single API call combining the Insert Order() and a Do Payment() action in a single call.
  • SetPayment - This call is used to settle authorized credit card payments or to register mandates for direct debit. 

Error if Account is Not Configured for Two-Step Sale Process

It is very important for your account to be configured properly to accept the two-step Sale call. If it is not configured correctly, your transactions may error with Worldline Global Collect Legacy code "410110."

By default, the integration and your Worldline Global Collect Legacy account support a one-step process for Refund transactions, so no action is required from you to ensure that this configuration is correct on your merchant account. With the one-step process, Zuora will make a DoRefund call, and Worldline Global Collect Legacy will process the refund automatically.

Set Up a Secure File Transfer (SFT) Account with Worldline Global Collect Legacy

This SFT account allows you to upload and/or download data from Worldline Global Collect Legacy. 

Enable the Worldline Global Collect Legacy Payment Gateway Integration for Your Tenant

See Enable payment gateway integrations for your tenant for instructions.

Procedure

Take the following steps to set up and configure a Worldline Global Collect Legacy gateway instance:

  1. Click your username at the top right and navigate to Settings > Payments > Setup Payment Gateway
  2. On the Configure Gateway Instance tab, select GlobalCollect (WebCollect Merchant Link) from the Gateway Type drop-down list.
  3. Click Create Gateway.
  4. Complete the information for the gateway instance. See below for more information on the fields.
  5. Click save gateway information after entering the necessary information.

Configuration fields

Common configuration fields

There are some common fields you must complete for every gateway configuration. We recommend reviewing our Setup Payment Gateway documentation for information on these common fields: 

  • Name
  • Use Gateway Test Environment
  • Test Environment Type
  • Merchant ID
  • Soft Descriptor (Direct Debit Text)
  • Cards Accepted
  • Default Authorization Amount
    Note that 0 is not permitted. If 0 is entered in this field, Zuora will automatically change it to 1 in order to avoid transaction failure.
  • Verify new payment method (optional)
  • Verify updated payment method (optional)
  • Support Recurring
  • Collection offset (days)
  • Enable AVS Filtering

If enabled, Zuora will decline Credit Card transactions for certain AVS response codes returned by the gateway, even if the gateway has approved the transaction. Default is disabled.

  • Enable CVV Filtering

If enabled, Zuora will decline Credit Card transactions for certain CVV response codes returned by the gateway, even if the gateway has approved the transaction. Default is disabled.

AVS and CVV Response Codes

The following table lists the AVS and CVV response codes:

AVS Response Codes Description
N No match
CVV Reponse Code Description
N CVV checked and no match

Credentials

In addition to the common fields, every gateway has unique requirements and information (such as credentials) that you must provide to configure the gateway in Zuora. For Worldline Global Collect Legacy, you must select a Merchant ID and provide a Soft Descriptor. 

Merchant ID

Your merchant ID is a unique ID (a numeric value of up to 10 digits) that is provided to you by Worldline Global Collect Legacy. The merchant ID number should be the same one you provided to Zuora Global Support to enable in your tenant, and the IDs will appear as a list in the gateway configuration page. If you have more than one Merchant ID number, you configure multiple gateways for each Merchant ID number.

Soft Descriptor (Direct Debit Text)

Soft Descriptor is a dynamic descriptor (text) that helps the customer identify the merchant's business on their statement. This is important, because charge backs can occur if a customer does not recognize the merchant debiting their account and believes that it is an unauthorized charge. 

Support Recurring

If you accept credit card payment methods, you may consider enabling the Support Recurring option. If Support Recurring is selected, Zuora will mark such payments as recurring when submitting the sale payment transactions to Worldline Global Collect Legacy. For recurring payments, this option may result in reduced fees for the subsequent payments. and greater acceptance with your merchant bank. 

Collection Offset (Days)

Collection Offset informs Worldline Global Collect Legacy to delay collection of a UK Direct Debit payment by the specified number of days. The default is five days.

For example, if you submit a request to process the payment on 8/5/14, with an offset date of five days, then they would submit the payment to be collected on 8/10/15.

Zuora recommends setting the field to five days. This accounts for the delay of setting up a mandate and the initial payment that is immediately processed by Zuora. If the acquisition flow considers this delay already, then the offset should be reduced to accelerate collections of recurring payments.

Implement Direct Debit

Although direct debit is treated as any other electronic payment method in Zuora, there are some additional steps required to implement this payment method. See Implementing Direct Debit with Worldline Global Collect Legacy for information about using direct debit with Zuora. 

Testing the configuration

Zuora recommends testing your selected payment gateway using both your payment gateway's test (staging) 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 a real credit card. 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.

Accessing Your Gateway's Test Environment

If Use Gateway Test Environment is selected in your payment gateway configuration, Zuora will direct payment transactions to the Worldline Global Collect Legacy staging environment. 

You will be accessing a staging environment linked to Zuora's integration. This environment is a testing simulator and is shared amongst all merchants using the Zuora Worldline Global Collect Legacy integration.

If Use Gateway Test Environment is not selected (disabled), Zuora will direct payment transactions to the Worldline Global Collect Legacy production environment.

Test Credit Cards and Testing Scenarios

Please contact your Worldline Global Collect Legacy implementation manager or Worldline Global Collect Legacy Support for specific test credit card numbers and testing scenarios. General support information can be viewed on the Worldline Global Collect Legacy 24/7 Shopper Support web page, including phone numbers by region and email contact information.

General Testing Information

Integration Testing

Zuora has been certified with Worldline Global Collect Legacy as an integration partner and maintains the integration on an ongoing basis, thoroughly testing the integration with every new release. The Worldline Global Collect Legacy integration documentation is helpful if you are integrating Worldline Global Collect Legacy directly with your website, however, you do not need to perform any integration or certification testing to submit transactions to Worldline Global Collect Legacy via the Zuora application. The intended audience for the integration guides are technical integrators, however, these documents can be helpful to non-technical integrators who can refer to it for information on testing and troubleshooting gateway errors. Integration guides and all necessary documentation are provided to you by your Worldline Global Collect Legacy implementation team (as described below). 

Performance and Volume Testing

In general, gateway testing environments are intended to give merchants the opportunity to test their gateway and integrations to their gateway, in order to work out any bugs before going to the production environment. Some gateway test environments are shared amongst multiple merchants, and other gateways provide unique testing environments for each merchant. Additionally, gateway test environments (also referred to as certification or sandbox environments) do not have the same high availability or performance capability as production environments. As such, they are not intended for load testing. Merchants performing high volumes of load testing that puts a stress on a shared test environment may receive a warning from the gateway or have their access to the testing environment suspended.

Transaction Testing

The following information explains how to test Worldline Global Collect Legacy transactions: 

Credit Card Transactions:

  • PM Creation: This can be tested by making an auth call.
  • Sale: The Sale can be tested by making a sale call.
  • Void: The void can be done before the transaction goes for settlement. If you want to do a void on sale, you can call it immediately after the sale call is made. 
  • Refund: In case of credit cards, it takes one business day for a sale transaction to be settled. If you do a sale call today, then you can test the refund of the transaction on the next business day or once the transaction is settled. You can use the inquiry call to identify whether the transaction is settled or is still in the process of settling.
  • Inquiry: This can be tested by making an inquiry call.

Direct Debit Transactions: 

  • PM creation: This can be tested by making a auth call. In case of direct debit, the auth call is used for validation of the bank account information. This is done by Worldline Global Collect Legacy against their database. 
  • Sale: This can be tested by making a sale call.
  • Void: Similar to credit card transaction, the void can be done only before the transaction goes for settlement.
  • Refund: In case of direct debit, the settlement happens from one to five business days, depending on which country direct debit you are testing for. For the UK and France, it takes four to five business days to settle on their test environment. For all other countries, it can take up to two business days to settle. Similar to credit card, you can make an inquiry call to see whether the transaction is settled. If it has settled, then you can make a refund call.
  • Inquiry: This can be tested by making an inquiry call.

Troubleshooting Gateway Errors

There are several ways to obtain information about gateway errors:

  • Look up the transaction by the transaction ID number (in the Zuora payment detail page, this is the Reference ID and Secondary Reference ID numbers) in your Worldline Global Collect Legacy payment console to see if more information is provided; often you will see more than just the response (reasons) code and response message in Zuora.
  • If you need further assistance with a specific error, please contact Worldline Global Collect Legacy support. General support information can be viewed on the Worldline Global Collect Legacy 24/7 Shopper Support web page, including phone numbers by region and email contact information. 

Make sure you are not re-trying an invalid card too many times

We recommend that you check the payment in Zuora to see how many times the same payment method has been retried for payment and failed. If there have been several retries, check the error messages from the beginning with the first failure and the more recent failures to determine if the error message is the same. If a merchant tries to process a payment against the same credit card too many times despite receiving errors, this could trigger warnings to the card issuing bank. The card issuing bank may place an alert on the account and not allow any further transactions from the merchant using that payment method. When a merchant has been flagged, the error received on the payment may be not state the reason why, instead it might be a generic error decline error. In this case, the merchant (Zuora customer) should work with Worldline Global Collect Legacy to see if they can identify the problem with the payment method. If the processor does not know, then the merchant and/or the card holder can try calling their card issuing bank to look into the issue.

Transaction Error 410110

As discussed above under Prerequisites, it is very important for your account to be configured properly to accept the two-step Sale call. If it is not configured correctly, your transactions may error with Worldline Global Collect Legacy code "410110." This error code may contain a message that can vary, but here is an example of the message: "410110 -- REQUEST 35649 UNKNOWN ORDER OR NOT PENDING."

Working with your Worldline Global Collect Legacy implementation team

Worldline Global Collect Legacy provides merchants with an implementation manager during the first 90 days of the implementation to help with the complex process of implementing and working with direct debits. Processing direct debit transactions may require management of mandates (some countries require mandates and some do not) and thus we recommend working very closely with your implementation manager to understand how direct debits work and how mandates are obtained, processed, and maintained. Your implementation manager should also review how reporting and payment reconciliation is handled, as well as provide you all the necessary documentation to get you started with using Worldline Global Collect Legacy such as: 

  • Business Guide for Direct Debit
  • WebCollect Reporting Guide
  • Documentation Containing Test Credit Card Numbers and Test Scenarios