Skip to main content

Access Worldpay gateway integration

Zuora

Access Worldpay gateway integration

The Access Worldpay gateway integration is an Early Adopter feature. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available.

This article describes the functionalities of the Access Worldpay gateway integration, how to configure this gateway, and known limitations.

To set up the Worldpay Payment Method Updater service in Zuora, see Configure Worldpay Payment Method Updater for more information.

Supported Payment Methods

Access Worldpay supports the following payment methods:

  • Credit Cards, including:
    • Visa
    • Mastercard
    • Discover
    • American Express
    • JCB
    • Diners Club
  • Credit Card Reference
  • ACH

Stored Credential Transactions

Access Worldpay includes support for the Stored Credential Transaction framework of all supported credit card brands.

Supported Payment Operations

Access Worldpay supports the following payment operations for Credit Cards:

  • Authorization and verification
  • Full and partial payment capture
  • Referenced and non-referenced refunds or partial refunds
  • Payment cancel (void)

The following payment operations are supported for ACH payment methods:

  • Payment
  • Payment cancel (void)

Configure Worldpay Merchant Account

Before creating your Worldpay gateway in Zuora, you need to configure the settings in Worldpay. These settings must be configured in both the Worldpay Merchant Interface (for the live production environment) and the Worldpay Merchant Test Interface (for the test environment). Contact your Worldpay representative or refer to the help guides in the Worldpay Support Center if you require assistance.

Disable Capture Delay

It is very important that you disable capture delay in Worldpay, as Zuora issues a separate capture call after the authorization occurs. Log in to the Merchant Interface for the desired environment, and locate the setting Capture delay (days). Set this to -off to disable capture delay.

If capture delay is not turned off, extra charges may be captured by Zuora.

$0 Authorization Support

As is common with payment gateways, Worldpay can check that customer's credit card is valid by issuing an authorization for an amount of money. Worldpay provides you with the option to enable $0 authorization, so that authorizations can be issued without leaving a trace on the customer's card history. Contact Worldpay Support to enable this optional feature.

Whether or not requests for $0 amounts are authorized depends on the specific bank and currency the customer uses. Although many financial institutions accept small authorization amounts (for example, $0.01 or $0), there are a number of banks that do not. These banks will reject cards that may or may not be valid simply due to the size of the authorization amount. This will affect cards entered in the Zuora Payments UI as well as through the API. In these cases, you should increase the default authorization amount.

Risk Screening

Worldpay authorization supports Address Verification Service (AVS), and Card Verification Value / Card Verification Code (CVV2, CVC). These provide a mechanism for checking the authenticity of a transaction by comparing information entered by the shopper during the payment process, with details held by the card issuer. You can also configure whether to receive the AVS/CVC result code or message in the authorization response. If enabled, Zuora will record the value returned without interpretation.

Zuora does not perform these checks for you; Worldpay must be configured to do so if required. Contact your Worldpay representative or refer to the help guides in the Worldpay Support Center for more information.

Worldpay offers two fraud screening products; Risk Management Module (RMM) and Risk Guardian (RG). Both of these allow you to configure the mapping from the risk check results to the authorization result. If you choose to use either of these products, you must configure the settings in the Merchant Interface for both live and test environments.

Define Shop Name and Shop URL

Worldpay allows you to set values for ‘Shop name’ and ‘Shop Url’ (which define the name of your business and URL of your website). To do this, visit the Merchant Interface for the live or test environment and set the values in your profile, or contact Worldpay Support to request that they do this on your behalf.

Note that it is not possible to use the Zuora SOAP API field SoftDescriptor because Worldpay does not support it through their API.

Discover Card Support

Worldpay supports payments by Discover card, but this is disabled by default. If you would like to issue payments with Discover cards in Zuora, contact Worldpay Support to enable this feature.

Tokenization 

The payment method used for tokenization is the Credit Card Reference (CCRef) payment method. Zuora uses the shopper token and not the merchant token. The following are supported by the Credit Card Reference payment method:

  • Credit token
  • Verify a token - The Token ID and Second Token ID fields in Zuora are required by Worldpay in order to verify a token.
  • Capture a payment using a token
  • Refund payment

To turn on additional credit card payment methods, contact Zuora Global Support.

Configure the Gateway in Zuora

To set up Worldpay as your gateway, enter your Worldpay credentials by clicking your username at the top right, navigate to Settings > Payments > Setup Payment Gateway. In the Gateway Type drop-down menu, select Worldpay1.4 or Worldpay (Corporate Gateway).

Common Fields for Configuration

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

  • Name: Choose a name that identifies this payment gateway. We recommend using a name that helps your users identify the gateway.
  • Use Gateway Test Environment: Select this check box if you want Billing to use the payment gateway's test service URL. This allows you to test payment transactions while you are setting up your Billing.
  • Cards Accepted: Worldpay accepts the following cards: Visa, Mastercard, American Express, Discover, Diners Club, and JCB.
  • Default Authorization Amount: Enter the minimum default amount used to process a payment. If the verify credit card checkboxes are selected, this amount will be used to validate the payment method by first authorizing the amount and then voiding the authorization when the amount is greater than zero.. 
  • Verify new payment method (optional): When you select either or both of the Verify new payment method and Verify updated payment method check boxes, Zuora Payments (within the Zuora Application and Zuora API) submits key information to the payment gateway to authorize all payment methods for authenticity and fraud prevention. For more information see Verifying the Credit Card Gateway Options.
  • Verify updated payment method (optional): See text above.

In addition to the common fields, every gateway has unique requirements and information (such as credentials and certain rules) that you must provide to configure the gateway in Zuora. 

Worldpay Credentials

Your credentials should be obtained from Worldpay and configured in Zuora. 

  • User Name and Password: The username and password used to access the Access Worldpay API.
  • Merchant Entity: This field is created as part of onboarding and used to route the request to Access Worldpay.

Worldpay Rules 

The following fields are specific to the Access Worldpay payment gateway:

  • Enable Fast Access Payouts (optional): Select this check box if you want to enable Fast Access payouts. Fast Access payouts support for the user’s API credentials must be enabled to use this feature.
  • Narrative: Enter the basic information about the merchant (you). The specified value shows up on customer statements. Allows for up to 24 characters.
  • Additional Narrative (optional): Enter the additional context about the payment or merchant, such as order number or merchant phone number. Allows for up to 24 characters.

Testing Your Configuration

We recommend testing your Worldpay payment gateway using both its test and production (live) environments.  Once you have completed testing in the gateway's test environment, Zuora recommends 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

Some payment gateways provide separate credentials for merchants to access their testing environment, some gateways use the same credentials for testing as for the production (live) environment but direct test transactions to a different URL, and other gateways do a little of both. Worldpay uses the same Merchant ID for test and live transactions, but a different XML password for each.

Accessing Test or Live Environment from Zuora

When configuring the Worldpay payment gateway in Zuora, you can indicate whether you would like to use the Worldpay test environment or the Worldpay live environment. 

  • If you select Use Gateway Test Environment, Zuora will direct payment transactions to your Worldpay test environment.
  • If you do not select Use Gateway Test Environment, Zuora will direct payment transactions to your Worldpay live environment.

Your Merchant Code will be the same for both test and production environments, but your XML password will be different. Log in to the Worldpay Merchant Interface or Worldpay Merchant Test Interface to discover the XML password for each environment.

For additional information, visit the Worldpay Support Center. Visit the Worldpay Developer Portal where you will find what you need to quickly start using Worldpay payment gateway and value-added services. 

General Testing Information

Integration Testing

Zuora maintains the integration with Worldpay on an ongoing basis, thoroughly testing the integration with every new release. The Worldpay integration documentation is helpful if you are integrating Worldpay directly with your website, however, you do not need to perform any integration or certification testing to submit transactions to Worldpay 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 (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 stress on a shared test environment may receive a warning from the gateway or have their access to the testing environment suspended

Troubleshooting Gateway Errors

For failed payments processed using the Worldpay payment gateway, Zuora Payments will provide the gateway Response Reason Code (for example, 203) and Response Reason text (for example, general decline of the card).

To obtain more information on gateway errors, look up the transaction ID number (called Reference ID in the Zuora payment detail page) in the Worldpay Merchant Interface or Worldpay Merchant Test Interface to see if more information is provided; often you will see more than just the response code and response message in Zuora.

If you require additional information, you can log a case in the Worldpay Support Center. All Worldpay merchants have access to online support, and depending on your support package with Worldpay, you may also have access to phone support. Please work with your Worldpay contacts to understand your options for contacting Worldpay Support. Be sure to have your reason code as well as your Transaction ID (in Zuora Payments this is the Reference ID) for the failed payment. This Transaction ID is an alphanumeric number (for example, CLEF4CGE8AB8).

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 mechant has been flagged, the error received on the payment may be not state the reason why, instead it might be a generic decline error. In this case, the merchant (Zuora customer) should work with their merchant acquirer/processor 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.

Limitations

  • The value for the Narrative field is texts that will appear on customer’s statements and is used to provide identifying information about the merchant. The first line is required while the second line is used to optionally provide additional information such as phone numbers of the merchant. If soft descriptors are present, they will override what has been entered in the Narrative field.
  • JCB, Diners Club, and Discover credit cards are available only for US transactions. Access Worldpay has acquiring capabilities for US domestic for only these 3 card types.
  • JCB and Diners Club cards do not currently support the $0 default authorization amount.
  • 3DS2 offering will fallback to 3DS1 if the card issuer does not yet support 3DS2 or the deviceData.collectionReference value is not included in the authentication request.
  • Payouts (credit transactions) are only supported by Visa and Mastercard card brands.
  • A delay of up to 15 minutes is applicable after you successfully verify a payment method before you can actually make a payment. Attempting to create a payment immediately after verifying a payment method will result in a 404 error. Similarly, this delay is also applicable between successfully submitting a payment and attempting to immediately refund or cancel the payment.
  • Your Access Worldpay credentials must have Fast Access supported to enable the Fast Access payouts feature. Fast Access allows payouts or credit operations to be received within 30 minutes for supported payment methods. Payment methods that do not support Fast Access will default to Standard Payouts which process within 3-5 days. To find out if your credentials are enabled for Fast Access, contact an implementation manager for Access Worldpay.