Surcharging

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

void addSurchargeListener(SurchargeListener listener)
void removeSurchargeListener(SurchargeListener listener)

iOS

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.