WorldPay offers market-leading online payments and fraud protection to corporate businesses globally, and supports a wide range of processing and settlement currencies.
Zuora is pre-integrated with WorldPay, allowing you to create a WorldPay Corporate Gateway instance and process credit card and debit card transactions settled in a currency other than the transaction currency.
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.
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 then extra charges may be captured by Zuora.
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. To enable this optional feature please contact WorldPay Support.
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 Z-Payments UI as well as through the API. In these cases, you should increase the default authorization amount.
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.
Note: Zuora does not perform these checks for you; WorldPay must be configured to do so if required.
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.
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.
Contact your WorldPay representative or refer to the help guides in the WorldPay Support Center for more information.
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: It is not possible to use the Zuora SOAP API field softDescriptor, as WorldPay doesn’t support this through their API.
WorldPay supports payments by Discover card, but this is disabled by default. If you would like to issue payments with Discover cards in Zuora, please contact WorldPay Support to enable this feature.
To set up WorldPay as your gateway, enter your WorldPay credentials in the Z-Payments Settings > Setup Payment Gateway page. When selecting a Gateway Type, choose WorldPay.
There are some common fields you must complete for every gateway configuration. We recommend reviewing Setting Up Payment Gateways for information on these fields:
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.
Your credentials should be obtained from WorldPay and configured in Zuora.
The Merchant Code is a unique value that identifies a merchant account in the WorldPay system. The code is submitted with every payment transaction sent from Zuora to WorldPay. WorldPay uses the same Merchant code for test and live transactions (but different XML passwords).
It is possible to have more than one merchant code under an administration code, which is a unique code that identifies a WorldPay merchant. The administration code is a reference under which all the merchant codes that a merchant has with the WorldPay payment service are stored, however it is not used in the API calls.
Merchant code switching is not supported. If you would like to process transactions for different types of customer interactions (e.g. e-commerce or moto) or to have multiple settlement currencies, then you need to create separate WorldPay gateway instances for each. Each gateway instance has its own unique WorldPay merchant code.
The password here is your XML password, used for making calls to the WorldPay API. It is not the password used for logging into the Merchant Interfaces.
For security reasons, the passwords for the live and test environments are different. Log in to the WorldPay Merchant Interface to find the XML password for the live environment, and log in toWorldPay Merchant Test Interface for the test environment.
When you enable either or both of the Verify new credit card and Verify updated credit card options, Z-Payments (within the Zuora Application and Zuora API) submits key information to the payment gateway to authorize all credit cards for authenticity and fraud prevention.
For more information see Verifying the Credit Card Gateway Options.
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.
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.
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.
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).
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
For failed payments processed using the WorldPay payment gateway, Z-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 Z-Payments this is the Reference ID) for the failed payment. This Transaction ID is an alphanumeric number (for example, CLEF4CGE8AB8).
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.
If an order ID is passed in a Zuora API call, this ID has to be unique for each payment. If no ID is passed in, Zuora will generate a 32-character random alphanumeric value for Payment Method creation, or use our internal IDs (constructed as tenant ID + payment number) for Payment creation requests, to ensure uniqueness.
It’s recommended to use the void payment option within 15 minutes of the payment request, and only use the refund option after 90 minutes has elapsed. WorldPay doesn’t indicate if an order qualifies for void or refund in the void/refund response, so Zuora marks the void/refund request as processed to indicate the gateway received the request, regardless of whether the request will succeed or fail later on.
WorldPay supports sending order notifications and financial reports by email to the merchant. This feature is implemented and maintained by WorldPay.
This section describes the functional mapping between the Zuora API and the WorldPay API.
|Zuora API||WorldPay API|
|Payment Method creation by passing in Credit Card information||Submitting an order with a Credit Card, and then issue a ‘cancelOrRefund’ type of order modification on the same order.|
|Payment Creation||Authorize an order with credit card, and issue a ‘capture’ type of order modification.|
|Void the Authorization||Issue a ‘cancelOrRefund’ type of order modification on the payment order.|
|Void the Payment||Issue a ‘cancel’ type of order modification on the payment order.|
|Refund Creation||Issue a ‘refund’ type of order modification on the payment order.|
|Payment Inquiry||Inquiry on the payment order.|
This section describes the object and field mappings between Zuora and WorldPay for Credit Card Payment Method creation and Payment creation.
|Zuora UI||API field passed to WorldPay (XPath)||Source of this infoRmation in Zuora (object.field)||Zuora PaymentMethod API field|
|Gateway setup > Merchant Code||//paymentService/@merchantCode|| |
|Gateway setup > user name||http basic auth: user|| |
|Gateway setup page > xml password||http basic auth: password|| |
|//order/@orderCode||AuthBean.orderId, or 32-digit random string |
PaymentBean.orderId, or PaymentBean.paymentNumber
|New Customer Account > Currency||//amount/@currencyCode||CustomerInfo.currency.code||Account.Currency|
|New Customer Account > Currency||//amount/@exponent||CustomerInfo.currency.exponent||Account.Currency|
|Gateway setup > Default Authorization Amount||//amount/@value||AuthBean.amount||?|
|Credit Card Type||<VISA-SSL> <ECMC-SSL> etc. tag||CreditCard.cardType||PaymentMethod.CreditCardType|
|Card Holder Name||//paymentDetails/cardHolderName||CreditCard.cardHolderName||PaymentMethod.CreditCardHolderName|
|Card Security Code||//paymentDetails/cvc||CreditCard.cardSecurityCode||<paymentmethod.cardsecuritycode/>|
|Billing Postal Code||//cardAddress/address/postalCode||CreditCard.cardZip||PaymentMethod.CreditCardPostalCode|
|Zuora UI||WorldPay API (XPath)||Description|
|Reference Id||//(orderStatus|captureReceived)/@orderCode||transactionId, orderId|
|N/A||lastEvent>||For PaymentMethod creation only: successful if lastEvent is AUTHORISED, otherwise fails.|
|N/A||<reply><ok>||Payment request (sale call) is successful if this tag is present in response, otherwise fails.|