CreateSurchargeConfigurationDto
A model the API reference uses in a request or a response. The operation pages link every field typed as this model here.
Input for creating a merchant's initial surcharge configuration. One configuration exists per merchant; creating a second for the same merchant is rejected.
Values
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
Fields
| Field | Type | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
defaultRate
required |
number (double) | Default surcharge rate (decimal fraction, 0.03 = 3%) when no network override applies.
Conditional: When DefaultRate is not null. Range: 0 to 0.03.
Conditional: When DefaultRate is not null and AttestedCostOfAcceptanceRate is not null. Must be <= .
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||
attestedCostOfAcceptanceRate
required |
number (double) | The merchant's attested effective cost of acceptance (decimal fraction, 0.024 = 2.4%), sourced
from their statement analysis. A surcharge may never exceed this, so a configured rate above it
(or above the 3% network cap) is rejected at save. Supplying a value records the attestation with
the acting user and a timestamp; null leaves it unattested and withdraws any prior attestation.
Conditional: When AttestedCostOfAcceptanceRate is not null. Range: 0 to 1.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||
channelRestrictions
required |
SurchargeChannelFlags SurchargeChannelFlags | A combination of channel flags. Send member names separated by a comma and a space (for example
"Api, HostedPaymentPage") or the integer sum (VirtualTerminal = 1, Api = 2, HostedPaymentPage = 4,
RecurringBilling = 8). None (0) turns surcharging off on every channel. Replaced on update; null
or omitted stores no channels.
Conditional: When ChannelRestrictions is not null. Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||
networkPolicies
required |
array of SurchargeNetworkPolicyDto array of SurchargeNetworkPolicyDto | Per-network surcharge policies. Replaces the stored set in full on update.
Conditional: When NetworkPolicies is not null.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||
Fields of each SurchargeNetworkPolicyDto: This body has no documented fields. | ||||||||||||
differentialNetworkRatesAttested
required |
boolean | Attests that differing surcharge rates across the allowed card networks carry documented legal
signoff. Must be true whenever `networkPolicies` resolves to more than one distinct
rate across the allowed networks; ignored otherwise. Card-brand non-discrimination and parity
provisions are what make the signoff necessary.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||
disclosureCopyTemplate
required |
string | The merchant's own surcharge disclosure copy, written in the token grammar defined by
`SurchargeDisclosureCopy`: it must carry `{rate}` and `{costOfAcceptance}`,
may carry `{amount}`, and may carry no other brace-delimited placeholder. Null or blank
leaves every surface on its platform default copy.
Conditional: When IsConfigured(DisclosureCopyTemplate) is true.
nullablemax length 1000
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||
merchantId
required |
string (uuid) | The merchant to create the configuration for.
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||
holdPromotion
required |
boolean | Whether to place an explicit promotion hold on the configuration as it is created, so it can
never be promoted out of the waiting period until the hold is released.
nullable
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||
promotionHoldReason
required |
string | Why the promotion is being withheld, recorded when `holdPromotion` is set. Ignored
when it is not.
nullablemax length 500
Values:
Values combine: send one or more member names separated by a comma and a space, or the integer sum of their values. Responses carry the names.
| ||||||||||
This model has no documented fields.