This article explains how to use the Zuora Payment Method Updater, or PMU. It goes over how the PMU works, how to view batches, export data, and troubleshoot issues.
The PMU service is a process that runs daily in the background to proactively keep your credit card payment methods up to date as opposed to a process that runs only when you get a credit card failure - that is to say PMU is a proactive approach to fixing credit card failure issues. Conversely, updating credit cards after failed payments is considered a reactive approach that can waste up to an entire bill cycle to discover and to fix. The proactive approach is one reason why the Zuora PMU is so beneficial to customers.
The pricing for the updater (payable to the updater service provider) is optimized to run as frequently as needed -- only credit card matches have fees.
For example, suppose that a merchant sends 100,000 credit cards to check for updates and finds that 5 matches that are updated. The merchant is charged for the 5 credit cards that required updating.
When you set up the PMU, Zuora will start a daily automated scheduler process which searches for eligible credit cards which may require updates. This scheduler process will collect all applicable credit card information and send it to the updater service in a batch request file. The updater service receives the file, validates it, then sends it to the card networks networks checking for updates. Once the batch has been submitted, users can view the status of all files from within the PMU console in Zuora.
The Zuora PMU service includes a console to view batches and to troubleshoot issues. You can also export data using the data export service. The PMU is configured to run a specific number of days before the bill is sent to customers (the bill cycle day), and the merchant can also choose the updater services to use. The following sections explain using the PMU service in more detail.
Now that you have setup the PMU, the operations of PMU will be explained in detail. The diagram below shows a detailed view of how the Zuora PMU service operates for a single batch in one billing cycle.
In this example, the PMU service runs 7 days or more before the bill cycle day (BCD).
On Day 1, the PMU Service begins by submitting a batch to the account updater service. The PMU Service creates a batch of credit cards for active billing account according to the rule settings configured for the PMU service. This batch is then sent to the updater service. Since submission is based on the BCD, it's possible that batches will be created and sent daily. Once the batch has been sent to the updater service, the processing and turnaround time is typically 3-5 days. Upon completion, the batch is sent back to Zuora and cards are automatically updated. The merchant may wish to review the completed batch file, and if any errors occur the merchant also has time to troubleshoot the issues and contact Zuora for support before the BCD.
On Day 7, the PMU Service completes. The cards have been updated, and the merchant has reviewed the batch and performed any tasks that were required to ensure all cards were updated.
On Day N, the bill cycle day, bills are sent to customers and the merchant can be assured that all accounts have been updated, thereby assuring that the impact of credit card information problems have been minimized.
The PMU Console is used typically for Day 5 - Day 7 in the diagram, for reviewing and troubleshooting batches and credit card information. This will be discussed in more detail in another section.
Setting the Start Date and Understanding the Bill Cycle Day
Every day at 2:00 a.m. PST, Zuora executes a scheduler process to prepare a request file for the PMU service. This request file contains payment methods which belong to customer accounts where the bill cycle day is a specified number of days in the near future. The number of days is specified in the payment method updater configuration under Rules.
Zuora's PMU can be flexibly configured to choose when the update run should kick off relative to the bill cycle day (BCD). We often get questions about when PMUs should be configured to run and this solution will provide guidance on the most optimal timing.
With the Zuora PMU, you can define when you want to submit the payment methods for update. Depending on the vendor, PMUs take 4 days or 7 or more days to completely update accounts. Zuora predefines the recommended number of days you should use on the payment method updater (with a default value) which accounts for this latency, but you have the freedom to select another date if you have a specific need to complete the update process at a different time than the default Zuora provides.
Each account in Zuora has a BCD which could be any day of the month (for example, 1st of the month or 5th of the month). The Zuora PMU will submit the payment methods based on what you defined on the PMU configuration. For instance, if you configure the PMU to submit 9 days prior to the Bill Cycle Day and the update process takes 7 days, a customer with Bill Cycle Day of 8th of the month will complete 2 days ahead of the Bill Cycle Date, or on the 6th of the month.
The Zuora PMU runs daily and automatically selects the default payment method for any account to be updated. If you run billing daily or at other intervals, the PMU will run in the background and proactively keep your payment methods updated.
Choosing Payment Methods to Update
You can choose whether to update Visa and/or MasterCard credit cards simply by checking the boxes on the configuration page.
Once all the payment methods are compiled, Zuora will filter out the payment methods which do not match this validation. Zuora filters out the following credit cards:
- Card type is not eligible
Zuora will filter out ineligible credit cards from the batch file based on the card types supported by the PMU provider. For most providers, this is Visa and Mastercard only.
- American Express can only be updated through the American Express PMU. This card type is not available on other providers' PMU.
- Zuora may also filter out Visa or MasterCard payment methods if either the Visa Account Updater or MasterCard Automatic Billing Updater are not enabled in the payment method updater configuration under Updater Services.
- Card number does not follow the luhn algorithm for credit card numbers. The lunh algorithm is used to verify accuracy and validity of credit card numbers.
- Card number length must be valid for the credit card type.
- Card type must match the card number format. For example, a card cannot be marked as Visa but have a credit card number that matches the MasterCard format. This is a mismatch and such cards will not be a considered payment method to submit for updates.
- Card must have an expiration date that is valid. For example, the expiration date cannot be 00/00.
Once invalid credit cards are excluded from the batch file, the batch file is ready to be submitted as a request to the PMU service for updates. Zuora will automatically format the file and submit it.
Running Multiple Updater Instances
You can configure multiple PMUs to run simultaneously by making them active. Only the PMUs marked active will be scheduled and run. There will no longer be a default PMU.
If the PMU rules are not set correctly, and there are multiple active PMUs,, the same credit cards may be submitted multiple times.
Batch Summary List View
Once you have logged into the payment method updater, you will see a summary list view of all batches submitted from Zuora to the account updater. To the right, under Views, there are three statuses that correspond to the table headers on the summary list view. Zuora defines a processing flow which includes a set of steps and transitions that a batch of payment method updater goes through during its lifecycle. The three statuses are defined for a Payment Method Updating Batch. They are Processing, Completed, and Error.
To view the detail information for a batch, click on the link for the applicable Zuora Batch Number.
Creating PMU batches
You can manually create a PMU batch except for American Express through the Zuora UI or the Create a Payment Method Updater batch asynchronously API operation. The batch will be created asynchronously.
To create a batch through the UI, complete the following steps:
- Navigate to Payments > Payment Method Updater.
- On the right, click Create a Batch.
- In the New Payment Method Updater Batch dialog:
- From the Updater Name list, select the configured PMU.
- Select a value from the Bill Cycle Day list.
- Click Create Batch.
To create a batch through the API operation, see Create a Payment Method Updater batch asynchronously.
Understanding Batch Information and Updater Summary
In the multiple batch view mode, you can click a single batch to view more information. When viewing a single batch, there are a number of fields included in the summary.
File identifier that is used to indicate which request file that the batch is included in. It's used to reconcile Zuora's batch with the report file generated by updater service provider. For example, when updater request id is 110502 and merchant ID is zuoramerchant, a response file named zuoramerchant.11052.au.response.pan.csv shall be found in the Report Search window of the Business Center.
|Zuora Batch Number||Batch identifier that is generated by Zuora. It is unique and sent in the request file.|
|Updater Request ID||File identifier that is used to indicate which request file that the batch is included in. It's used to reconcile Zuora's batch with the report file generated by updater service provider. For example, when updater request id is 110502 and merchant ID is zuoramerchant, a response file named zuoramerchant.11052.au.response.pan.csv shall be found in the Report Search window of the Business Center.|
|Post Date||Date the updater batch status was posted on.|
|Account Updater Service||The account updater company you are using for this batch update.|
|Started On||The time when batch started. It's same as the time that batch was created|
|Completed On||The time when batch finished to be processed. This field is empty when batch is in Processing status.|
|Status||Possible values: Processing, Completed, Error.|
|Processing||Updater batch has been created, but not finished the processing. Normally, Batch stays in Processing status for several days. when batch fails in submitting or retrieving stage, it stays in Processing status. It will be automatically retried. After max retry times are exceeded, batch is changed to Error status. By default, the max retry times is 3.|
|Completed||The response file of Updater batch has been received and processed. The changes to payment methods has been updated into database.|
|Error||Updater batch failed. This is a rare condition. The user shall check response code and response message in batch detail page. Then take action according trouble shooting guideline.|
|Response Code||Zuora-defined response code once updater batch is completed. See the CyberSource PMU Troubleshooting document for a list of response codes and actions.|
|Response Message||Along with the response code, there is a response message for more details. See the CyberSource PMU Troubleshooting document for a list of response codes and actions.|
|Total Payment Methods Selected||Total number of payment methods that are selected in a batch.|
|Payment Methods Processing||Number of payment methods still processing.|
|Payment Methods Updated||Number of payment methods that were updated. The payment methods updated are the ones the merchant pays for. The reasons for update include: credit card number updated, credit card closed, and expiration date changed.|
|No Updates Available||Payment methods were checked and no update was required.|
Review the payment methods for possible errors. There are warnings for two scenarios. The first scenario is that the batch processing failed, and all records in the batch will be marked as warning. The batch will need to be submitted again. The second scenario is that the batch processing completed successfully. The records marked as warning are divided into the following categories: invalid credit card, contact card holder, no match, or other reasons.
Re-submitting a Batch Manually
When creating a batch, the Updater automatically submits the data to the service. That process can occasionally fail. If the automatic retries are not frequent enough or have run their course, you can manually resubmit batches by clicking on more > Re-submit batch.
The more menu will not be present if the batch status is Completed or Cancelled.
You can only resubmit a batch if the batch status is Error due to submission failure. Create a data source export to view the submission status.
Retrieving Batch Results Manually
After the data has been submitted to the service, the results usually take a couple of days to be available. The Updater automatically retrieves the information, and even retries to ensure retrieval. However, you can manually retrieve batch results, clicking on more > Retrieve results.
The more menu will not be present if the batch status is Completed or Cancelled.
You can only retrieve a batch if the batch status is Error but the submission succeeded. Create a data source export to view the submission status.
Retrieving information of PMU instances
To retrieve the detailed information of all PMU instances on your tenant except for American Express, use the List Payment Method Updater instances API operation.