Dynamic Merchant ID selection for Vantiv (Now Worldpay) gateway integration
Dynamic Merchant ID (MID) and Report Group selection allows you to process transactions through a single Vantiv (Now Worldpay) gateway configuration and determine the Merchant ID and Report Group for each transaction at runtime.
Dynamic Merchant ID and Report Group selection supports organizations that manage multiple sub-merchants, stores, franchises, or business units that settle funds to different merchant accounts. Instead of creating a separate gateway configuration for each Merchant ID, you configure a single gateway instance and determine the Merchant ID and Report Group at runtime.
After Zuora associates a Merchant ID and Report Group with a transaction, it uses the same values for related downstream activities, including refunds, chargebacks, and payment retries.
Dynamic Merchant ID and Report Group routing is not enabled by default. To enable this feature in your tenant, submit a request at Zuora Global Support to enable the required tenant property.
How dynamic Merchant ID selection works
You can configure Merchant ID and Report Group values in one of the following ways:
- Configure static values on the gateway instance.
- Derive values dynamically from supported fields on business objects.
- Pass values directly through gateway options on API requests.
When Zuora processes a transaction, it determines the Merchant ID and Report Group from the configured source and submits those values to Vantiv (Now Worldpay) for processing.
Supported routing sources
You can source Merchant ID and Report Group values from the following objects, including their custom fields:
- Account
- Payment Method
- Bill To Contact
- Sold To Contact
This configuration works similarly to the field mapping available for other payment gateway integrations. For example, you can map a custom field that stores a store identifier or club identifier to the Merchant ID field.
Value resolution order
If Merchant ID or Report Group values are available from multiple sources, Zuora resolves them in the following order:
- Static value configured on the gateway instance.
- Dynamic value configured on the gateway instance. This value overrides the static value during payment runs.
gatewayOptionson the Create a payment method API operation. This value overrides configured values during payment method verification and authorization.gatewayOptionson the Payments API operation. This value overrides configured values for the specific payment.
Standard payment processing
For scheduled payments and payment runs associated with a billing account, Zuora resolves the Merchant ID and Report Group from the gateway configuration. Zuora uses dynamic values when they are configured; otherwise, it uses the static gateway values.
Payment method verification before account association
Some payment methods are verified before they are associated with a billing account. Examples include ACH account verification and credit card verification.
Because no billing account exists at that stage, pass the Merchant ID and Report Group explicitly through gatewayOptions on the Create a payment method API request. The values that you provide in the request override all configured values.
Transactions associated with a previous sub-merchant
A customer might move from one store or business unit to another. Although future transactions use the new Merchant ID, certain liabilities must continue to settle against the original Merchant ID. Examples include:
- Dunning payments for invoices created by the original store.
- Payment retries for transactions processed under the original Merchant ID.
- Reversals or adjustments associated with earlier transactions.
In these scenarios, pass the original Merchant ID and Report Group through gatewayOptions on the Create a payment method API request.
Gateway options
The following table describes the gateway options that you can specify for dynamic Merchant ID and Report Group selection.
| Gateway option | Description |
|---|---|
merchantId | The Vantiv (Now Worldpay) Merchant ID to use for the transaction. This value overrides the Merchant ID configured on the gateway instance for the request. |
reportGroup | The Report Group (TID) associated with the transaction for financial reporting. |
You can specify these values through the gatewayOptions object in the following API operations:
Error handling
Zuora does not validate dynamic Merchant ID or Report Group routing when you save the gateway configuration. Zuora resolves and validates these values when it processes a transaction.
If the mapped routing field is empty, missing, or cannot be resolved at the transaction level, Zuora does not apply a transaction-level override. Instead, Zuora falls back to the next available value in the resolution order.
Zuora resolves Merchant ID and Report Group values in the following order:
Transaction-level value
Account-level value
Gateway instance value
If Zuora cannot resolve a transaction-level or account-level value, Zuora uses the Merchant ID and Report Group configured on the gateway instance. In this case, the transaction does not fail, and Zuora does not return a routing error.
A transaction fails only if Zuora submits a resolved Merchant ID or Report Group that the gateway rejects, or if another gateway-side validation error occurs.
The following example shows a routing error returned when no Merchant ID mapping is found:
Routing Error: No MID configuration found for Unit 999.Reporting and reconciliation
Zuora stores the Merchant ID used to process a transaction on the payment record. You can use this value for reporting and reconciliation to identify the merchant account that processed and settled the transaction.
Note that:
- You can source Merchant ID and Report Group values only from supported fields on supported business objects.
Report Group has a character limit of 20.
- Zuora does not maintain mappings between business identifiers (for example, store IDs or club IDs) and Merchant IDs. You are responsible for maintaining valid Merchant ID values in the mapped fields or API requests.
- If Zuora cannot resolve a valid Merchant ID mapping, the transaction fails.
- Zuora carries forward the Merchant ID associated with a transaction to related refunds, chargebacks, and retries.