--- updatedAt: 2026-08-06T14:18:20.000Z agentTools: projectIndex: https://docs.nmi.com/llms.txt --- # Surcharging Apply compliant, gateway-verified surcharges to VP3350 card-present transactions in real time. Surcharging applies a merchant-permitted fee to a card-present transaction taken on the VP3350. To opt in, pass the `Surcharge` parameter with the value `TRUE` into `startTransaction()` (it defaults to `FALSE`). The SDK then fetches the merchant's surcharge limits from the gateway, fires the surcharge callback, and the amount to apply is returned to the SDK with a call to `continueSurcharge()`. ## Eligibility Surcharging is US-only, online-only, and available for **Sale**, **Auth**, and **Linked Refund** transactions. It must be enabled for the merchant account on the gateway, and a surcharge callback observer must be registered before `startTransaction()` is called — otherwise `SurchargeObserverRequired` is returned. * Passing the `Surcharge` parameter into `startTransaction()` for a transaction type that does not support surcharging returns `SurchargeNotSupported`. * `SurchargeNotSupported` is also returned when the merchant account is not enabled for surcharging on the gateway (for example, a non-US merchant), or when the SDK is operating offline. ## Transaction address and surcharge limits Surcharge limits are based on the location where the transaction takes place. This location can be supplied using the following parameters: * `TransactionAddressLine1` * `TransactionAddressLine2` * `TransactionAddressCity` * `TransactionAddressState` * `TransactionAddressZip` * `TransactionAddressCountry` If none are supplied, the merchant address on file is used. If any address component is supplied, the full address must be provided, and `TransactionAddressCountry` is always required — if not supplied, the transaction fails with the error `TransactionAddressMissing`. > **Note:** The integrating application is responsible for the accuracy of the transaction address. It should be the location where the transaction takes place — for example, the store or job-site address for a card-present sale, or the customer's billing address for e-commerce and recurring payments. An inaccurate address may result in an incorrect surcharge limit or eligibility response. ## Surcharge Callback The Payment Device SDK fires a `Surcharge` event carrying the surcharge limits returned by the gateway. The integrating application responds by calling `continueSurcharge()`. A surcharge observer must be registered before `startTransaction()` is called. **Methods to add or remove the callback delegate in ChipDnaMobile:** **Android** ```java void addSurchargeListener(SurchargeListener listener) void removeSurchargeListener(SurchargeListener listener) ``` **iOS** ```objc void addSurchargeTarget:(id)self action:(SEL)@selector(onSurcharge:) void removeSurchargeTarget:(id)self ``` The callback provides: * The maximum surcharge amount the merchant may apply (in minor units) * The maximum percentage * The surcharge currency * Whether an operator PIN is required If a surcharge cannot be applied (for example, an ineligible card or a gateway communication failure), the maximum values are returned as `0` and an error such as `ServerCommunicationError` is included — in this case, respond with `Result` set to `FALSE`. ## ContinueSurcharge ``` Parameters continueSurcharge(Parameters) ``` Call `continueSurcharge()` from the surcharge callback to tell the SDK whether to apply a surcharge, once the callback has indicated `ResponseRequired` is `TRUE`. Set the `Result` parameter to `TRUE` to apply a surcharge, or `FALSE` to apply none; `Result` is required whenever a surcharge can be applied. When applying a surcharge, supply the amount in the `SurchargeAmount` parameter, in minor units. The amount must be zero or greater and must not exceed the maximum returned in the callback. If the callback indicated `OperatorPinRequired` was `TRUE`, the `OperatorPin` parameter must also be supplied; an incorrect PIN may be retried, and once retries are exhausted the surcharge is declined and the transaction terminates. This method is synchronous and returns a `Parameters` object containing the `Result` and, if present, any `Errors` — for example `SurchargeAmountExceedsMaximum` — in which case `continueSurcharge()` may be called again with a valid amount. ## Surcharge and transaction results When a surcharge has been applied, the `SurchargeAmount` and the `SubtotalAmount` (the amount before surcharge) are provided, in minor units, in both the `transactionFinished` callback and the response from `getTransactionInformation()`. In both cases, `Amount` reflects the total inclusive of the surcharge. `SurchargeAmount` is omitted when no surcharge was applied, and its absence should be treated as no surcharge. ## Refunding a surcharged transaction To refund a surcharged transaction, the portion of the surcharge to be refunded should be supplied in the `SurchargeAmount` parameter to `linkedRefundTransaction()`, in minor units and pro-rated in the case of a partial refund. Supplying a surcharge amount where the original transaction carried none returns `SurchargeRefundNotSupported`. ## Partial approvals Surcharging does not support partial approvals. If the acquirer partially approves a surcharged transaction, the SDK voids the transaction rather than completing it for the partially approved amount. ## Confirming a lower amount The surcharge percentage is stored with the transaction data so that surcharge limits can be evaluated correctly when an approved transaction is later confirmed for a lower amount. When a lower amount is confirmed with `confirmTransaction()`, the stored percentage is applied to the total and surcharge amount being confirmed.