Set up custom payment gateways and payment methods

Last updated
Save as PDF

Universal Payment Connector (UPC) and Open Payment Method (OPM) services are frameworks developed by Zuora, which allow 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. OPM offers the capabilities to create your custom payment method type and payment method. For payment operations and features that are supported or not supported by UPC and OPM services, see the information in the Compatibility table.

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, complete the following steps. Click each step for details.

Contact Zuora Global Support to request access to the custom payment gateway in your Zuora tenant.
Set up a web server outside of Zuora as the payment hub.
Create and configure your custom payment gateway through the Zuora UI.
Configure and manage your custom payment method type through the “Custom Payment Method Types” API operations.
Refresh and synchronize the custom payment method type settings through the Zuora UI.
Enable your custom payment method type through the Zuora UI.
Create your custom payment method of the defined type through the Zuora UI or the REST API.

To export data related to custom payment gateways and the custom payment methods, see Export data of custom payment gateways and custom payment methods.

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 method validation, payment, and referenced refund 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 (See the Configurable Payment Retry article for more information about the limitation.)
Payment transaction processing operations
Refund transaction processing operations
Data Source Export
Data Query (For limitations, see Export data of custom payment gateways and custom payment methods)

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
Creation of the stored credential profile for a payment method through the Zuora UI or REST APIs
Payment operations including non-referenced refund, payment cancel, and delayed capture (transaction authorization and capture)

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 the following fields of a custom payment method:

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 JSON string containing definition data 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.