Skip to main content

Set up custom payment gateways and payment methods

Zuora

Set up custom payment gateways and payment methods

  1. Last updated
  2. Save as PDF

This feature is in the Early Adopter phase. If you want to use this feature, submit a request to Zuora Global Support to enable the Universal Payment Connector and Open Payment Method services that support this feature.

Universal Payment Connector (UPC) and Open Payment Method (OPM) services are frameworks developed by Zuora, which allows you to integrate your custom payment gateway and payment method to Zuora subscription, billing, and revenue management in a dynamic and flexible manner. With the support of UPC, you are able to create and integrate your custom payment gateway, and OPM offers the capabilities to create your custom payment method type and payment method.

The custom payment method of the defined type can only be used with the custom payment gateway. It cannot be used with the Zuora out-of-box gateway integration such as GoCardless, Stripe, etc. The connections of Zuora's custom payment gateway integration are expected to be synchronous.

It is recommended to leverage a 3rd party tokenization service that is usually provided by the gateway, because payment method types requiring PCI are not supported by UPC and OPM.

Overall procedure

To set up your custom payment gateway and custom payment method:

  1. Prepare a definition file for your custom payment method type.
  2. Submit a request to Zuora Global Support to enable UPC and OPM services. In your request, enclose the definition file you created and information of the target environment.
  3. Set up a web server outside of Zuora as the payment hub.
  4. Create and configure your custom payment gateway through the Zuora UI.
  5. Enable your custom payment method type through the Zuora UI.
  6. Create your custom payment method of the defined type through the Zuora UI or the REST API.

Compatibility

The following table describes the compatibility of the custom payment gateway and payment method type with the Zuora features.

Compatible Not compatible
  • Payment run
  • Payment operations including payment, refund, and validating through UI and REST APIs
  • Creation of payment methods through the account creation and order creation REST APIs
  • Advanced Payment Manager in Zuora Collections
  • Configurable Payment Retry in Zuora Collections
  • Payment transaction processing operations
  • Refund transaction processing operations
  • Data Source Export
  • Data Query
  • Hosted Payment Pages 2.0
  • Payment Method Updater
  • Zuora out-of-box gateway integration
  • Zuora out-of-box Gateway Reconciliation
  • Zuora SOAP APIs
  • Level 2 and Level 3 card data processing
  • 3D Secure 2.0 
  • Transaction authorization
  • Voiding transactions
  • Verifying transactions

Notes for Zuora SOAP APIs

You cannot use the SOAP APIs to create, update, or delete a custom payment method. You can use the SOAP API to retrieve a custom payment method, but only the following fields that you specified in your metadata definition file can be retrieved.

  • MethodReferenceId - The identification reference of the custom payment method.
  • UserReferenceId - The identification reference of the user or customer account.
  • SubType - The identification reference indicating the subtype of the custom payment method.
  • MethodSpecificData - The field containing detailed information of the custom payment method.

If you have created a custom payment method through the Zuora UI or the REST APIs, you can then use your custom payment method in other SOAP APIs by specifying the PaymentMethodId field if it is available in the SOAP API. For example, you can specify the ID of your custom payment method in the PaymentMethodId field of the CRUD: Create a payment SOAP API and create a payment.