Worldpay Payment Gateway
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 gateway instance and process credit card and debit card transactions settled in a currency other than the transaction currency.
To set up the Worldpay Payment Method Updater service in Zuora, see Configure Worldpay Payment Method Updater for more information.
To enable and configure Gateway Reconciliation on Worldpay 1.4 or Access Worldpay, see Configure Worldpay Gateway Reconciliation for more information.
Supported Versions
Zuora supports the following Worldpay payment gateway versions:
- Access Worldpay: The latest gateway version. We recommend that you use this version.
- Worldpay 1.4
- WorldPay (Corporate Gateway)
The following table compares a subset of features among Access Worldpay, Worldpay 1.4, and WorldPay (Corporate Gateway).
| Feature | Access Worldpay (Latest version) | Worldpay 1.4 | WorldPay (Corporate Gateway) |
|---|---|---|---|
| Supported payment methods |
|
Worldpay 1.4's support for Credit Card Reference is in the Early Adopter phase. We are actively soliciting feedback from a small set of early adopters before releasing it as generally available. |
|
| Mandate creation | Not Supported | Among the supported payment methods, Zuora supports mandate creation for SEPA payment methods. Zuora will generate and pass the mandate to the gateway. | Not Supported |
| Gateway Reconciliation | Supported | Supported | Not Supported |
| 3D Secure 2.0 | Supported | Supported | Not Supported |
| Stored credential transactions | Supported | Supported | Not Supported |
| Non-Referenced Refunds | Supported (both external and electronic non-referenced refunds) | Supported (only external non-referenced refunds) | Supported (both external and electronic non-referenced refunds) |
Configure Payment Gateway Instance
See Access Worldpay to learn how to set up an Access Worldpay gateway integration instance.
See Worldpay 1.4 and Worldpay (Corporate Gateway) to learn how to set up Worldpay 1.4 or Worldpay (Corporate Gateway) instances.
Additional Gateway Information
Integration Notes
Order Number
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.
Reverting a Payment
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.
Email Notifications
Worldpay supports sending order notifications and financial reports by email to the merchant. This feature is implemented and maintained by Worldpay.
Functional Mapping between Zuora and 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. |
Credit Card Field Mappings
This section describes the object and field mappings between Zuora and Worldpay for Credit Card Payment Method creation and Payment creation.
Request
| 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 |
Payment.GatewayOrderId,
Payment.PaymentNumber |
|
|
/order/description | AuthBean.referenceId
PaymentBean.referenceId |
PaymentMethod.id
Payment.id |
| 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 Number | /paymentDetails/cardNumber | CreditCard.cardNumber | PaymentMethod.CreditCardNumber |
| Expiration Date | /paymentDetails/expiryDate/date/@month | CreditCard.expirationDate | PaymentMethod.CreditCardExpirationMonth |
| Expiration Date | /paymentDetails/expiryDate/date/@year | CreditCard.expirationDate | PaymentMethod.CreditCardExpirationYear |
| Card Holder Name | /paymentDetails/cardHolderName | CreditCard.cardHolderName | PaymentMethod.CreditCardHolderName |
| Card Security Code | /paymentDetails/cvc | CreditCard.cardSecurityCode | <paymentmethod.cardsecuritycode/> |
| Billing City | /cardAddress/address/city | CreditCard.cardCity | PaymentMethod.CreditCardCity |
| Billing Country | /cardAddress/address/countryCode | CreditCard.cardCountry | PaymentMethod.CreditCardCountry |
| Billing Postal Code | /cardAddress/address/postalCode | CreditCard.cardZip | PaymentMethod.CreditCardPostalCode |
| Billing State/Province | /cardAddress/address/state | CreditCard.cardState.name | PaymentMethod.CreditCardState |
| Billing Address | /cardAddress/address/address1 | CreditCard.cardAddress1 | PaymentMethod.CreditCardAddress1 |
| Billing Address | /cardAddress/address/address2 | CreditCard.cardAddress2 | PaymentMethod.CreditCardAddress2 |
| Phone | /cardAddress/address/telephoneNumber | CreditCard.phone | PaymentMethod.Phone |
Response
| 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. |
| N/A | /error/@code | error code |
| N/A | /error | error description |
| N/A | /AVSResultCode/@description | |
| N/A | /CVCResultCode/@description |