Surcharge Configuration

A surcharge (Payment) is defined as a single entity for a given tenant; that is, though there are various dimensional elements (attributes), a surcharge definition will create one definition. This surcharge can have a permutation of values and combinations in the backend.

A new system object, ‘Surcharge,’ has been introduced. Use the standalone surcharge configuration API to configure a decision table that includes the attributes that will define the eligibility for surcharge, accounting, and taxability of surcharge on a given payment.

The following attributes are part of the standalone surcharge configuration:

Pricing information against various combinations of the attributes is stored separately. 

Attributes (Dimensions) and Mapping

Attributes: Keys or dimensions of the business that define the context of an invoice based on which the rate of surcharge is determined. A set of up to 10 attributes can be configured while defining Surcharges. All the attributes must have a valid mapping to a Zuora object. The following objects are supported for attribute mapping; that is, a standard or a custom field on any of these objects can be used to define surcharge rates:

• Account (API name: Account)
• Payment Method (API name: PaymentMethod)
• Sold to contact on Account (API name: Account.SoldToContact)
• Bill to contact (API name: Account.BillToContact)
• The user defines the attributes' names, which are used to configure the values per permutation of the surcharge rate.
• There can be up to 1,000 distinct permutations of the surcharge. 
• This limit is not applicable in the early adopter phase, but we recommend that any use case that requires a larger number of combinations must be discussed with Zuora.
• Attribute and context matching supports the equality (==) operator (exact matches); that is, the attribute values in the configuration must exactly match that of the mapped <object.field>.
• Attribute values can be String values only. 
• Payment Surcharge configuration should only have unique combinations of attribute values to avoid any race condition during retrieval and evaluation.

Key Features

• Payment Surcharge is configured under a specific surcharge model in Zuora, called “Payment Surcharge”. This model has several combinations of the rates based on the attributes that are used to define the rates (Card Type, Geo, Customer Type and so on).
• Users can define a set of attributes before configuring Surcharge.  
• Tax Mode and Tax code can be defined by combining the attributes. There is a default at the surcharge definition level, but users can modify it at the permutations of attributes like card type, brand, geolocation, and so on. 
• Reversible flags can not be modified at the level of individual combinations of attributes. 
• Accounting and revenue recognition information is maintained at the Surcharge level, not at the individual combination level. 
• Rates can be set as a percentage of the payment request amount or as a fixed fee per transaction. 
• Once set up, the surcharge configuration cannot be updated. It will need to be reconfigured (deleted and recreated). Applicable for the early adopter phase only.
• Since there is only one Payment Surcharge configuration (with n permutations on the attributes), developers can interact with the configuration using category as the handle “PAYMENT_SURCHARGE” (case sensitive).
  • Retrieval and delete can work using Category. You do not need to capture/store/retrieve Ids or keys. 

Sample Configuration 

(Note that there are other elements to the configuration such as Accounting, Revenue Recognition, and Taxation. Refer to detailed API specs for the same)