Skip to main content

Reason Codes for Payment Operations


Reason Codes for Payment Operations

Invoice Adjustment is deprecated on Production. Zuora recommends that you use the Invoice Item Adjustment to adjust invoices.

Zuora allows you to input and track a Reason Code for payment transactions that represent exceptions to the normal payment flow. These transactions include Payment Refund, Credit Balance Refund, Invoice Item Adjustment, Invoice Adjustment, and Credit Balance Adjustment.

Zuora provides a standard set of Reason Codes. Your users can create additional Reason Codes that suit your requirements. For example, the pre-populated standard reason codes include things like "Customer Satisfaction", "Chargeback", and "Payment Reversal". You might choose to add custom reasons such as "Incorrect charge", "Failed offline payment", etc.

Once the reason codes have been established, a customer service agent can record the appropriate reason code when creating a refund or adjustment, allowing you to draw reports and analyze these exception transactions by reason code.

For detailed instructions on how to create and configure reason codes for your tenant, see Creating and Editing Reason Codes

User Permissions

All users can create and configure reason codes, and can apply reason codes to transactions that support them. However, be aware that a separate Change Reason Codes permission is required in order to change the reason code on an existing transaction.  Standard Users have this permission.  To set it up for other user roles, see Setting Up User Permissions for Reason Codes.

Using Reason Codes

You can apply Reason Codes in any transaction that supports them.  For instance, see Creating a Payment Refund for detailed instructions on applying reason codes to payment refunds in Zuora, or Canceling and Refunding Credit Balances for detailed instructions about specifying reason codes for credit balance refunds.

Editing Reason Codes

If you have the Change Reason Codes permission, you can edit reason codes on existing transactions. However, the following rules apply: 

  • You cannot edit a reason code for a transaction that belongs to a closed accounting period. 
  • The transferred to accounting status for the refund must not be Processing or Yes.
  • Notifications for reason codes

You can also configure notifications to tell you whether a transaction was processed successfully, and potentially use the notification to trigger an automated or manual business process. See Notifications for more information about configuring and using notifications, and Merge field syntax for email templates for information about the merge fields designed for use with notifications.

Reporting on Reason Codes

Once you have started using reason codes, you can use data sources to export reason-code data for reporting and analysis. The Refund and Invoice Adjustment data sources include a Reason Code field that can be selected for export, used as a filter, and included in joins.

Reason Codes and the Zuora SOAP API

You can also use Reason Codes with our SOAP API. The CreditBalanceAdjustment, InvoiceAdjustment, InvoiceItemAdjustment, and Refund objects all include a ReasonCode field that you can create, update, and query.