Best practices for installing CPR
Best practices to configure Configurable Payment Retry (CPR), including required custom fields, consistent deployments, retry scheduling, and response code mappings.
Configurable Payment Retry (CPR) uses OAuth credentials to authenticate to your Zuora tenant and to deploy the required custom fields. The following best practices help you set up CPR correctly the first time, avoid common configuration gaps, and maintain predictable retry behavior as your payment operations evolve.
Create the required custom fields manually after you add OAuth credentials
Adding OAuth credentials to an existing CPR app instance does not create the required custom fields automatically. Create the following custom fields manually, because CPR requires them to process any application:
Object and category | Field label | API name | Data type |
|---|---|---|---|
Account fields (indexed) | Retry Status |
| Text (255) |
|
Debit memo fields Note: This field is available only if Invoice Settlement is enabled on your tenant.
| Retry Status |
| Text (255) |
Invoice fields (indexed) | Retry Status |
| Text (255) |
Always deploy the production build, in every environment
When you deploy CPR, install the production build in all tenant environments, including testing and production. Using the same build across environments ensures that test results accurately reflect production behavior and prevents environment-specific configuration drift.
Stop scheduled retries explicitly when you stop a CPR app instance
Stopping a CPR app instance does not stop retries that are already scheduled. To stop further retries, complete both of the following actions:
For invoices and accounts that have existing retry cycles, use the CPR APIs to remove the cycles. For more information, see the Zuora Developer Center.
Deactivate the callout notification to prevent new cycles from starting. For more information, see CPR configuration details.
Design response code mappings around decline severity
Map gateway response codes to retry categories so that CPR can determine which payment failures to retry and how often. When you create the CPR app, Zuora provides a list of response codes from each gateway configured in your tenant. To add more response codes or gateways, see Configure response codes.
For more flexible retry logic, create additional mapping headers that reflect the severity of each decline. For example:
Hard decline: CPR does not retry the payment.
Medium decline: CPR retries the payment less frequently than a soft decline, for example, twice.
Soft decline: CPR retries the payment until all retry attempts are exhausted.
If you are unsure whether to retry a specific payment error, map the error as a soft decline and monitor the results to determine whether the error is recoverable. You can change mappings at any time.
Update mappings whenever you add a new gateway
If you add a new gateway to your payment operations after you install CPR, add the response codes for the new gateway to your existing mapping. To keep mappings consistent, use the master code list as your source of truth:
In the app instance, navigate to , and then select Master Code List.
Copy the response codes for the new gateway.
Add the codes to your My Code List export.
Upload the updated list to your CPR instance.
Plan for the timing of mapping changes
After you modify a mapping (for example, change a hard decline to a soft decline), CPR applies the change to future scheduled retry attempts. The next retry attempt is not affected if it was scheduled before the change. Retry cycles that are already complete do not restart.
To stop further retries immediately, manually stop the retry cycle. For more information about using the CPR APIs, see the Zuora Developer Center.
Maintain a versioned My Code List for audits and migrations
When you bulk edit response codes or migrate CPR app instance configurations between environments, always download and save the current mapping list, which is referred to as My Code List. After you edit the list, save the updated My Code List for future reference. Keeping a versioned history of My Code List makes it easier to audit changes, roll back unintended edits, and replicate configurations across environments.