Configuration
Configure Zuora and the Vantiv (Worldpay) gateway to process eCheck Return and NOC reports from the Vantiv SFTP server and update ACH payments accordingly.
Before enabling Vantiv eCheck Return processing, ensure that:
You have a configured Vantiv (Worldpay) gateway in Zuora.
The gateway has an active reconciliation schedule.
Vantiv SFTP credentials (username, password, merchant ID) are configured on the gateway.
The reconciliation schedule's creator has appropriate permissions; the hourly file sync runs under this user's session.
On the Vantiv side, the eCheck Return report and the eCheck NOC Update report must be configured to be generated and placed in the SFTP folder used by Zuora.
Zuora must configure the following tenant properties for your environment:
enable.vantiv.echeckreturn.processing | false | Yes | Enables processing of Vantiv eCheck Return CSV reports and updates ACH payments accordingly. |
enable.vantiv.echecknoc.processing | false | Optional | Enables processing of the Vantiv eCheck NOC Update report so Zuora can update matching ACH payment methods with corrected account details. |
gateway.gr.file.sync.enabled.gateway.types | empty | Yes | Comma‑separated list of gateway types that use the hourly file sync. Must include "Vantiv" to activate hourly polling for Vantiv. Currently, only "Vantiv" is supported. |
The hourly file sync must also be enabled for Vantiv by including
Vantivingateway.gr.file.sync.enabled.gateway.types.Zuora processes only files whose filenames contain the current date in PST. Older files are skipped.
NOC files are encrypted at rest because they contain sensitive ACH data.
eCheck NOC Update behavior
If enable.vantiv.echecknoc.processing is enabled, Zuora downloads the Vantiv eCheck NOC Update report during hourly file sync and applies supported corrections to matching ACH payment methods.
Supported corrections:
Account number
Routing number
Account holder name
Important:
ACH account type updates are not supported for Vantiv eCheck NOC processing.
Zuora applies an update only when the original value in the report matches the current value on the payment method.
Zuora skips updates for closed, scrubbed, or non-ACH payment methods.
Vantiv gateway properties
On the Vantiv gateway configuration in Zuora, the following properties control how Zuora reads reports from the Vantiv SFTP server:
config.vantiv.report.folder.name | "reports" | Folder on the Vantiv SFTP server where eCheck Return and eCheck NOC files are stored. |
enable.new.vantiv.gr.endpoint | false | When true, uses a newer Vantiv reports host instead of the legacy host. Exact hostnames are Not specifie. |
eCheck Return CSV field mapping
The table below summarizes how Zuora uses the key columns in the Vantiv eCheck Return report:
| Worldpay Payment ID | Matches the report row to a Zuora payment by gateway reference ID. | Rows with blank or null IDs are skipped. |
| Chargeback Amt | Return amount used when updating the payment and, where applicable, creating a refund. | |
| Reason Code | NACHA return code recorded on the payment's gateway result code field. | Examples: R01, R02. |
| Reason Description | Human‑readable reason recorded on the payment's gateway result message field. | |
| Date Issued | Date of the return; used as the event date on the payment. | Parsed as MM/dd/yyyy in PST; if parsing fails, Zuora uses the current time. |