Surcharging

A surcharge is an additional amount charged by the merchant to cover the cost of accepting card payments. The Suncorp Gateway's surcharging functionality allows you to apply a surcharge on a transaction based on the following parameters:

gateway entry point, for example, Hosted Checkout, API
payment method, for example, Mastercard, Visa, American Express
funding method, for example, Credit, Debit
currency

To allow the gateway to compute a surcharge for a transaction, you must configure surcharge rules in Merchant Administration. Alternatively, you can provide a pre-calculated surcharge on the order if you are integrating using API/Batch Integration.

Surcharging is only applicable for card payments made in Australia and New Zealand.

To determine whether surcharging card payments is allowed in your region, contact your payment service provider or check card scheme and regulatory rules in your region.

Prerequisites

You must be enabled for surcharging on your merchant profile with the Suncorp Gateway.
You must have surcharging rules configured in Merchant Administration to allow the gateway to calculate the surcharge.

Integrating to use Surcharging

The gateway supports surcharging on transactions using the following integration methods:

Integrating via API/Batch Integration

WSAPI usage of surcharge from version 50 to 66.

You can apply a surcharge on an order using one of the following options:

surcharge calculated by the gateway

To allow the gateway to calculate a surcharge, provide the following field in an Authorize/Pay or an Update Session request:
- order.netAmount: This is the amount payable for the order before surcharging is applied.
You can submit a Retrieve Transaction/Retrieve Order request to retrieve the following surcharging details:
- order.surchargeAmount: The surcharge calculated by the gateway based on your surcharge rules.
- order.amount: The total amount for the order, inclusive of the surcharge amount.
You can also use the Payment Options Inquiry operation to request the calculated surcharge amount by providing the fields:session.id, order.netAmount, order.currency, gatewayEntryPoint, and sourceOfFunds.provided.card.prefix.
surcharge calculated by the merchant

Provide the following fields in an Authorize/Pay/Standalone Capture or an Update Session request:
- order.amount: The total amount for the order, inclusive of the surcharge amount.
- order.surchargeAmount: The surcharge, if any, applicable to this order. This amount must be included in the total order amount that you specify in the order.amount field.
Submitting a Retrieve Transaction/Retrieve Order request will return surcharging details as provided by you in the transaction request plus order.netAmount (net amount derived as order amount minus surcharge amount).

You can use the Payment Options Inquiry operation to request card scheme/funding details to help you assess and apply the correct surcharge for a card. For more information, see FAQs below.

WSAPI usage of surcharge from version 67 and above.

surcharge calculated by the merchant

order.amount: The total amount for the order, inclusive of the surcharge amount.
order.merchantCharge.amount: The amount of the additional fee that you are charging the payer, currently this refers to the amount of surcharge only.
order.merchantCharge.type: The type of the additional fee that you are charging the payer, currently this refers to the surcharge only. The value of merchantCharge.type is surcharge.

Surcharge calculated by the gateway

order.netAmount: This is the amount payable for the order before surcharging is applied.
order.merchantCharge.type: The type of the additional fee that you are charging the payer, currently this refers to the surcharge only. The value of merchantCharge.type is surcharge.

Authorize API Reference [REST][NVP]

Retrieve Transaction API Reference [REST][NVP]

Payment Options Inquiry API Reference [REST][NVP]

Integrating via Hosted Checkout

Surcharge can be calculated by the gateway through Hosted Checkout.

WSAPI usage of surcharge from version 50 to 70.

To apply a surcharge on a Hosted Checkout payment, provide the following field in the Hosted Checkout request (Checkout.configure() function or Create Checkout Session operation depending on your checkout flow):

order.netAmount: The amount payable for the order before surcharging is applied.

Do not provide order.amount field in the request. See FAQs below.

You can submit a Retrieve Transaction/Retrieve Order request to retrieve the surcharging details:

order.surchargeAmount: The surcharge calculated by the gateway based on your surcharge rules.
order.amount: This is the net amount plus surcharge.

The payer will be able to view the applicable surcharge for the card they have entered and may choose to proceed with the new total amount, use a different card, or cancel the order. The payment receipt presented to the payer will display the surcharge amount that has been applied.

WSAPI usage of surcharge from version 71 and above.

order.netAmount: The amount payable for the order before surcharging is applied.
order.merchantCharge.type: The type of the additional fee that you are charging the payer, currently this refers to the surcharge only. The value of merchantCharge.type is surcharge.

Do not provide order.amount field in the request. See FAQs below.

You can submit a Retrieve Transaction/Retrieve Order request to retrieve the surcharging details:

order.merchantCharge.amount: The amount of the additional fee that you are charging the payer, currently this refers to the amount of surcharge only.
order.amount: This is the net amount plus surcharge.

FAQs

Will the gateway calculate the surcharge if I provide both order.netAmount and order.amount fields in my request?

Providing both order.netAmount and order.amount fields without order.surchargeAmount will return an error because the gateway does not have sufficient information to calculate the surcharge. The gateway requires you to provide either the order.netAmount field OR the order.amount field.

If you provide all three fields then the gateway will not calculate the surcharge instead use the surcharge amount as provided by you.

Can I opt out of surcharging card payments when submitting a transaction?

Yes, to opt out of surcharging,

provide the order.amount field in your transaction request to indicate the total amount for the order.

for Direct API from WSAPI version 50 to 66,

when the surcharge is calculated by the merchant, do not provide value in the fields order.netAmount and order.surchargeAmount.
when the surcharge is calculated by the gateway, do not provide value in the field order.netAmount.

for Direct API from WSAPI version 67 and above,

when the surcharge is calculated by the merchant, do not provide value in the fields order.netAmount, order.merchantCharge.amount, and order.merchantCharge.type as surcharge.
when the surcharge is calculated by the gateway, do not provide value in the fields order.netAmount and order.merchantCharge.Type as surcharge.

for Hosted Checkout from WSAPI version 50 to 70,

surcharge is always calculated by the gateway, do not provide value in the field order.netAmount.

for Hosted Checkout from WSAPI version 71 and above,

surcharge is always calculated by the gateway, do not provide value in the field order.netAmount and order.merchantCharge.type as surcharge.

If the payer requests a refund, will the surcharge amount be refunded?

Yes. Because the surcharge is included in the order.amount field, and it is this amount that's refunded to the payer, the surcharge amount will be refunded too. In case of partial refunds, the surcharge amount will be refunded on a pro rata basis.

If I have Dynamic Currency Conversion (DCC) enabled, will the gateway calculate the surcharge in both the payer's billing currency and my preferred currency?

Yes, the gateway will include the applicable surcharge in the order amount, which will be returned as paymentTypes.card.currencyConversion.payerAmount in the payer's billing currency and as order.amount field in your preferred currency (in the Payment Options Inquiry operation response).

Can I retrieve card type identification data to help calculate a surcharge for an order?

You can provide the sourceOfFunds.provided.card.prefix field in the Payment Options Inquiry request to retrieve the following scheme/funding details about the card used for payment, which may assist you in surcharging decisions:

paymentTypes.card.scheme: The organization that owns a card brand and defines operating regulations for its use.
paymentTypes.card.brand: The brand name used to describe the card that is recognized and accepted globally. For many major card types this will match the scheme name. In some markets, a card may also be co-branded with a local brand that is recognized and accepted within its country/region of origin (see Local Brand).
paymentTypes.card.localBrand: The brand name used to describe a card that is recognized and accepted within its country/region of origin. The card may also be co-branded with a brand name that is recognized and accepted globally.
paymentTypes.card.fundingMethod: The method used by the payer to provide funds for the payment.

This information is gathered from third-party sources and may not be accurate in all circumstances.

You can use these details to calculate a surcharge based on the card presented by the payer.

Payment Options Inquiry API Reference [REST][NVP]