Skip to main content

Opayo Direct Gateway

Zuora

Opayo Direct Gateway

  1. Last updated
  2. Save as PDF

Zuora partners with Elavon to provide a gateway integration called Opayo Direct for online credit card transaction processing. This article describes payment operations, payment methods, and other features that are supported by the Opayo Direct gateway integration. It also provides instructions on setting up and confusing an Opayo Direct gateway instance in Zuora.

This feature is in Limited Availability. If you want to have access to the feature, submit a request at Zuora Global Support.

Supported payment operations

The following payment operations are available through Opayo Direct:

  • Payment method validation
  • Payment
  • Payment cancel (void)
  • Referenced refund

Supported payment methods

Opayo Direct supports credit card payment methods, including the following card brands:

  • Visa
  • MasterCard
  • Discover
  • American Express
  • JCB
  • Diners Club

Supported features

Stored credential transactions

Opayo Direct gateway integration includes support for the Stored Credential Transactions framework. For details about the supported payment methods, see Support for stored credential transactions overview.

Set up and configure an Opayo Direct gateway instance

Register IP addresses

The Opayo Direct gateway requires adding Zuora EU or US Cloud Data Center outbound IP addresses to the whitelist for each of your gateway merchant accounts, depending on which data center your tenant is located at. These Zuora IP addresses are used as part of a verification process for the Opayo Direct gateway to ensure that transactions are from a recognized source.

Therefore, before you start using this gateway on Zuora EU or US Cloud Data Center, you must add Zuora EU or US Cloud Data Center outbound IP addresses to the gateway's whitelist for both Zuora Sandbox and Production environments so that they can work properly. For more information about the Zuora EU or US Cloud Data Center outbound IP addresses, see Outbound IP Addresses Whitelisting.

To register IP addresses in Elavon Opayo Direct:

  1. Access the Opayo Direct merchant account through Sign in to MySagePay.
  2. Navigate to the merchant account and click the Settings tab.
  3. Click Valid IPs in the left navigation pane.
  4. Click Add in the lower right of the window, add the IP information, and complete the IP address registration.

Create and configure an Opayo Direct gateway instance in Zuora

After the Opayo Direct gateway integration is enabled in your tenant by submitting a request to Zuora Global Support, follow these steps to create and configure an Opayo Direct gateway instance in Zuora:

  1. Navigate to Settings > Payments > Setup Payment Gateway. 
  2. Select Opayo Direct from the Gateway Type drop-down menu.
  3. Click Create Gateway.
  4. On the gateway settings page, specify values for the configuration fields, and then click Save Gateway Information. For details about the fields, see Configuration fields in the following section.

Configuration fields 

There are some common fields you must configure for every gateway instance. Review Setting Up Payment Gateways for information about the following common configuration fields and complete your configuration:

  • Name
  • Use Gateway Test Environment
  • Cards Accepted
  • Default Authorization Amount: The value of this field must be greater than 0.
  • Verify new payment method (optional)
  • Verify updated payment method (optional)

In addition to the common fields, the following credentials provided by Opayo must be configured:

  • Vendor Name
    When a merchant account is set up with the Opayo Direct gateway, a vendor name is assigned by the gateway. The vendor name is a mixture of alphanumeric characters without spaces or special characters. The vendor name is sent in the transaction registration post and is used by Opayo Direct gateway to identify the account through which the transaction will be processed. Without this value, the gateway cannot identify the correct account and therefore cannot process transactions.
  • User Name
    The username created for the merchant account when setting it up with the Opayo Direct gateway. This field is used to authenticate your account.
  • Password
    The password was created for the merchant account when setting it up with the Opayo Direct gateway. This field is used to authenticate your account.

Additional Opayo merchant account settings

The following merchant account settings are disabled by default, and cannot be configured through the Opayo console. These settings need to be enabled by Opayo Support.

  • Support for Additional Card Types (American Express, Discover)
  • Configuration of the merchant account to the desired currency

To enable these settings, make your request through support@Opayo.com.

Supported Gateway Option fields

You can submit additional information to the Opayo gateway using gateway options. Currently, Opayo Direct gateway integration supports the following gateway option field:

Gateway option field Zuora API field Zuora Payment Page client parameter Description
AccountType gatewayOptions.AccountType param_gwOptions_AccountType Specify the type of the account as either E for Ecommerce or M for MOTO.

If AccountType is E, the end customers might be challenged by 3D Secure.

See Opayo’s documentation for more information.
  • CustomerIpAddress
  • UserAgent
  • AcceptHeader
  • AcceptLanguage
  • BrowserJavaEnabled
  • BrowserJavascriptEnabled
  • gatewayOptions.CustomerIpAddress
  • gatewayOptions.UserAgent
  • gatewayOptions.AcceptHeader
  • gatewayOptions.AcceptLanguage
  • gatewayOptions.BrowserJavaEnabled
  • gatewayOptions.BrowserJavascriptEnabled
  • param_gwOptions_CustomerIpAddress
  • param_gwOptions_UserAgent
  • param_gwOptions_AcceptHeader
  • param_gwOptions_AcceptLanguage
  • param_gwOptions_BrowserJavaEnabled
  • param_gwOptions_BrowserJavascriptEnabled

These fields are required only if AccountType is E.

See Opayo’s documentation for detailed description.
  • BrowserColorDepth
  • BrowserScreenHeight
  • BrowserScreenWidth
  • BrowserTZ
  • gatewayOptions.BrowserColorDepth
  • gatewayOptions.BrowserScreenHeight
  • gatewayOptions.BrowserScreenWidth
  • gatewayOptions.BrowserTZ
  • param_gwOptions_BrowserColorDepth
  • param_gwOptions_BrowserScreenHeight
  • param_gwOptions_BrowserScreenWidth
  • param_gwOptions_BrowserTZ

These fields are required only if BrowserJavascriptEnabled is 1.

See Opayo’s documentation for detailed description.
  • RecurringFrequency
  • RecurringExpiry
  • gatewayOptions.RecurringFrequency
  • gatewayOptions.RecurringExpiry
  • param_gwOptions_RecurringFrequency
  • param_gwOptions_RecurringExpiry

These fields are used for the stored credential transactions.

See Opayo’s documentation for detailed descriptions.

You can use these fields in Payment Pages 2.0, SOAP API, or the following REST API:

Testing your configuration

We recommend that you test your payment gateway using both your payment gateway's test 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.

You can use the test card information and testing scenarios provided by the gateway vendor to test your integration. For more information, see the following Opayo’s documentation:

Credit Card field mapping

The following table describes the object and field mappings between Zuora and Opayo for Credit Card payment methods. 

Opayo Direct API field Zuora UI field Zuora API field (object.field) Additional information
VendorTxCode

In payment method creation: N/A 

In payment processing: Payment Number 

In refund processing: Refund Number

In payment method creation: N/A

In payment processing:  Payment.PaymentNumber

In refund processing:  Refund.RefundNumber

During payment method creation and validation, Zuora generates a random ID for VendorTxCode.

In payment or refund processing, Zuora Payment Number or Refund Number is used as VendorTxCode.
BillingSurname Credit Card > Card Holder Name PaymentMethod.CreditCardHolderName  
BillingFirstnames Credit Card > Card Holder Name PaymentMethod.CreditCardHolderName  
BillingAddress1 Credit Card > Billing Address (line 1) PaymentMethod.CreditCardAddress1  
BillingAddress2 Credit Card > Billing Address (line 2) PaymentMethod.CreditCardAddress2  
BillingCity Credit Card > Billing City PaymentMethod.CreditCardCity  
BillingState Credit Card > Billing State/Province PaymentMethod.CreditCardState  
BillingCountry Credit Card > Billing Country PaymentMethod.CreditCardCountry  
BillingPostCode Credit Card > Billing Postal Code PaymentMethod.CreditCardPostalCode  
BillingPhone Credit Card > Phone PaymentMethod.Phone  
DeliverySurname Credit Card > Card Holder Name PaymentMethod.CreditCardHolderName  
DeliveryFirstnames Credit Card > Card Holder Name PaymentMethod.CreditCardHolderName  
DeliveryAddress1 Credit Card > Billing Address (line 1) PaymentMethod.CreditCardAddress1  
BillingAddress2 Credit Card > Billing Address (line 2) PaymentMethod.CreditCardAddress2  
DeliveryCity Credit Card > Billing City PaymentMethod.CreditCardCity  
DeliveryState Credit Card > Billing State/Province PaymentMethod.CreditCardState  
DeliveryCountry Credit Card > Billing Country PaymentMethod.CreditCardCountry  
DeliveryPostCode Credit Card > Billing Postal Code PaymentMethod.CreditCardPostalCode  
DeliveryPhone Credit Card > Phone PaymentMethod.Phone  
CustomerEMail Credit Card > Email PaymentMethod.Email  
Currency Account Currency Account.Currency  
Amount Gateway Instance > Default Authorization Amount N/A  
CV2 Credit Card > Card Security Code PaymentMethod.CreditCardSecurityCode  
CardHolder Credit Card > Card Holder Name PaymentMethod.CreditCardHolderName  
ExpiryDate Credit Card > Expiration Date PaymentMethod.CreditCardExpirationMonth concatenated MMYY
ExpiryDate Credit Card > Expiration Date PaymentMethod.CreditCardExpirationYear concatenated MMYY
CardType Credit Card > Credit Card Type PaymentMethod.CreditCardType  
CardNumber Credit Card > CardNumber PaymentMethod.CreditCardNumber  
Amount Payment Amount Payment.Amount  
Amount Refund Amount Refund.Amount  
Description Payment Number Payment.PaymentNumber  
VPSTxId

In payment processing: Reference ID

In payment void: Payment Reference ID

In payment processing: Payment.GatewayReferenceId

In payment void: Payment.ReferenceId

  
SecurityKey +  TxAuthNo Second Payment Reference Payment.GatewaySecondReferenceId These 2 response fields are needed for Payment Void and Refund in addition to the VPSTxId.
RelatedVendorTxCode In refund processing: Payment Number Payment.PaymentNumber  
RelatedVPSTxId In refund processing: Payment Reference ID Payment.ReferenceId  
RelatedSecurityKey + RelatedTxAuthNo In refund processing: Second Payment Reference ID Payment.SecondPaymentReferenceId