Surcharging
A surcharge is an extra fee that merchants add to cover the cost of accepting card payments. [[_term_paymentGateway_]] allows you to add this fee based on:
- How does the integration work, for example, through [[_term_checkout_]] or [[_term_webServicesIntegration_]] or Hosted [[_term_batchIntegration_]].
- The type of card used, for example, Mastercard, Visa, or American Express.
- Whether the card is a credit or debit card.
- The currency used for the transaction.
- line of business
To let the gateway calculate a surcharge for a transaction, you need to set up surcharge rules in [[_term_merchantUI_]]. If you're using [[_term_webServicesIntegration_]] or [[_term_batchIntegration_]], you can also provide a pre-calculated surcharge on the order.
Prerequisites
- [[_term_paymentServiceProviderInitCap_]] must enable you for surcharging on your merchant profile with [[_term_paymentGateway_]].
- You must configure surcharging rules in [[_term_merchantUI_]] that allow the gateway to calculate the surcharge.
Integration methods to use surcharging
The gateway supports surcharging on transactions using the following integration methods:
- Integrating through [[_term_webServicesIntegration_]]
- Integrating through [[_term_checkout_]]
- Integrating through Hosted [[_term_batchIntegration_]]
Integrating through [[_term_webServicesIntegration_]]
You can apply a surcharge on an order using one of the following options:
The 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.order.merchantCharge.type: This is the type of additional fee that you are charging the payer, currently this refers to the surcharge only. The value of themerchantCharge.typefield is a surcharge.
order.amount field in the request. For more information, see
the FAQs section.You can submit a Retrieve Transaction/Retrieve Order request to retrieve the following surcharging details:
order.surchargeAmount: This is the surcharge calculated by the gateway based on your surcharge rules.order.amount: This is the total amount for the order, inclusive of the surcharge amount.order.merchantCharge.calculatedBy
Payment Options Inquiry operation to request the calculated surcharge amount by providing the fields:
session.idorder.netAmountorder.currencygatewayEntryPointsourceOfFunds.provided.card.prefix
The surcharge calculated by the merchant
To allow the merchant to calculate the surcharge, provide the following fields in an Authorize/Pay/Standalone Capture or an Update Session request:
order.amount: This is the total amount for the order, inclusive of the surcharge amount.order.surchargeAmount: This is the surcharge, if any, applicable to this order. This amount must be included in the total order amount that you specify in theorder.amountfield.
When you submit a Retrieve Transaction or Retrieve Order request, it returns the surcharging details you provided in the transaction request. Additionally, it displays the order.netAmount,which represents the total order amount minus the surcharge amount. You can see the order.surchargeSource, indicating whether the surcharge amount was provided by the merchant (value = 'CLIENT') or calculated by the gateway (value = 'GATEWAY').
Payment Options Inquiry operation to request card scheme or funding
details to help you assess and apply the correct surcharge for a card. For more information, see FAQs section.The following tables show the fields and their descriptions for the integration through [[_term_webServicesIntegration_]].
The surcharge calculated by the merchant
order.amount |
This is the total amount for the order, inclusive of the surcharge amount. |
order.merchantCharge.amount |
This is the amount of the additional fee that you are charging the payer, currently, this refers to the amount of the surcharge only. |
order.merchantCharge.type |
This is the type of additional fee that you are charging the payer, currently this refers to the surcharge only. The value of the merchantCharge.type field is a surcharge. |
The surcharge calculated by the gateway
order.netAmount |
This is the amount payable for the order before surcharging is applied. |
order.merchantCharge.type |
This is the type of additional fee that you are charging the payer, currently this refers to the
surcharge only. The value of the merchantCharge.type field is a surcharge. |
Authorize API Reference [REST][NVP]
Retrieve Transaction API Reference [REST][NVP]
Payment Options Inquiry API Reference [REST][NVP]
Integrating through [[_term_checkout_]]
The gateway can calculate the surcharge for you through [[_term_checkout_]] as well.
To apply a surcharge on a [[_term_checkout_]] payment, provide the following field in the [[_term_checkout_]]. This can be done using the INITIATE_CHECKOUT request or the Create Checkout Session operation, depending on your checkout flow:
order.netAmount: This is the amount payable for the order before surcharging is applied.
order.amount field in the request. For more information, see FAQs section.You can submit a Retrieve Transaction or Retrieve Order request to retrieve the
surcharging details:
order.surchargeAmount: This is the surcharge calculated by the gateway based on your surcharge rules.order.amount: This is the net amount plus the surcharge.
The fields for the surcharge calculated by the gateway are:
order.netAmount: This is the amount payable for the order before surcharging is applied.order.merchantCharge.type: This is the type of additional fee that you are charging the payer, currently, this refers to the surcharge only. The value of themerchantCharge.typefield is a surcharge.
order.amount field in the request. For more information, see FAQs section.The payer can view the surcharge for their card and then decide to:
- Proceed with the new total amount.
- Use a different card.
- Cancel the order.
The order details or order summary panel displays:
- The Surcharge as a line item.
- The revised payable amount as the TOTAL amount.
Integrating through Hosted [[_term_batchIntegration_]]
When a net amount is provided instead of an order amount for batched Authorize or Pay transactions, whether through REST integration or a [[_term_merchantUI_]] file upload, the gateway calculates the applicable surcharge amount. This calculation is done in the same way as for WSAPI Authorize or Pay transactions and is used to determine the order amount for processing the transaction.
Surcharging on batch transactions is particularly important for recurring transactions, where surcharge rules may change over time and need to be applied dynamically at the time of each subsequent recurring Authorize or Pay transaction.
Merchants can choose to include the calculated surcharge amount directly in the batch request file.
The same functionality and amount validations that apply to surcharging on WSAPI transactions also apply to batch transactions. For more details, refer to the section on Surcharging on WSAPI.
For more information about the Hosted Batch functionality available with the gateway, see the Hosted [[_term_batchIntegration_]] and Batch management sections in [[_term_merchantUI_]] User Guide.
Sample Batch Request for the Surcharge calculated by the gateway
apiOperation,order.id,order.reference,transaction.id,order.netAmount,order.currency,order.merchantCharge.type,sourceOfFunds.type,sourceOfFunds.provided.card.number,sourceOfFunds.provided.card.expiry.month,sourceOfFunds.provided.card.expiry.year,transaction.amount,transaction.currency,result,response.gatewayCode,error.cause,error.explanation,error.field,error.supportCode AUTHORIZE,10006008461,20170228PTSAPT0001,20170228PTSATA0001S01,31,USD,SURCHARGE,CARD,512345678901xx46,1,39,,,,,,,,
Sample Batch Request for the Surcharge calculated by the merchant
apiOperation,order.id,order.reference,transaction.id,order.amount,order.currency,order.merchantCharge.type,order.merchantCharge.amount,sourceOfFunds.type,sourceOfFunds.provided.card.number,sourceOfFunds.provided.card.expiry.month,sourceOfFunds.provided.card.expiry.year,transaction.amount,transaction.currency,result,response.gatewayCode,error.cause,error.explanation,error.field,error.supportCode AUTHORIZE,10006008462,20170228PTSAPT000A1,20250218MERCALSURC,31,USD,SURCHARGE,03,CARD,512345678901xx46,1,39,,,,,,,,
Use cases
Following are the examples of use cases with API Requests for surcharge calculation.
Use case 1: Merchant manually calculates the Surcharge for version 67 and later
The merchant is required to submit the following API fields in the Pay API operation together with the mandatory fields:
amount: This is inclusive of the surcharge.merchantCharge.amount: This is the surcharge amount.merchantCharge.type = SURCHARGE: This is a new required field for version 67 and later.netAmount: This is the sales amount without surcharge and is automatically calculated. If the merchant submits this field in the API, [[_term_paymentGateway_]] validates it to ensure thatorder.amount = order.merchantCharge.amount + order.netAmount.
Sample API request version 67 and later - Surcharge manually set to USD $3.00:
{
"apiOperation": "PAY",
"order": {
"amount": "10.00",
"merchantCharge": {
"type": "SURCHARGE",
"amount": "3.00"
},
"currency": "USD"
},
"transaction": {
"source": "INTERNET"
},
"sourceOfFunds": {
"type": "CARD",
"provided": {
"card": {
"number": "{{fpan}}",
"expiry": {
"month": "01",
"year": "39"
},
"securityCode": "100",
"storedOnFile": "TO_BE_STORED"
}
}
}
}
Use case 2: Mastercard Gateway calculates the Surcharge on behalf of the merchant for version 67 and later based on the surcharge rule configured
The merchant is required to submit following API fields in the Pay API operation:
netAmount: This is the sales amount without surchargemerchantCharge.type = SURCHARGE: This is a new required field for version 67 and later.
Sample API request version 67 and later
{
"apiOperation": "PAY",
"order": {
"netAmount": "10.00",
"merchantCharge": {
"type": "SURCHARGE"
},
"currency": "USD"
},
"transaction": {
"source": "INTERNET"
},
"sourceOfFunds": {
"type": "CARD",
"provided": {
"card": {
"number": "{{fpan}}",
"expiry": {
"month": "01",
"year": "39"
},
"securityCode": "100",
"storedOnFile": "TO_BE_STORED"
}
}
}
}
FAQs
Will the gateway calculate the surcharge if I provide both order.netAmount and order.amount fields in my request?
If you provide both order.netAmount and order.amount fields without order.surchargeAmount, it 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.
Is there any alternative workflow to support [[_term_hostedSession_]] merchants?
Merchants can submit a Payment Option Inquiry (POI) request with a net amount, using the payment details obtained through [[_term_hostedSession_]]. The POI will return the applicable surcharge and order amount, which the merchant can display on their screen. These amounts can then be submitted or referenced from the session in the transaction operation.
The lifecycle of a single session includes:
- Creating the session in your server.
- Updating the session in your server with any non-sensitive information you want to store in the session
- Using the session on your web site or app to allow the gateway to gather payment details from the payer.
- Retrieve the session content using the Retrieve Session operation and take note of first 6 digit of card number.
- Submit Payment Option Inquiry with the values for
gatewayEntryPointand card prefix with first 6 digit and pad with zero to meet length up to 9 digits with those set for Auth or Pay transactions are mapped to the Gateway Entry Point values in the Surcharge rules configuration. - Referencing the session in payment transactions.
Can I opt out of surcharging card payments when submitting a transaction?
Yes. For opting out of surcharging, provide the order.amount field in your transaction request to show the
total order amount.
For [[_term_webServicesIntegration_]]:
- WSAPI version 50 to 66:
- If the merchant calculates the surcharge, do not provide values for
order.netAmountandorder.surchargeAmount. - If the gateway calculates the surcharge, do not provide a value for
order.netAmount.
- If the merchant calculates the surcharge, do not provide values for
- WSAPI version 67 onwards:
- If the merchant calculates the surcharge, do not provide values for
order.netAmount,order.merchantCharge.amount, andorder.merchantCharge.typeas surcharge. - If the gateway calculates the surcharge, do not provide values for
order.netAmountandorder.merchantCharge.typeas surcharge.
- If the merchant calculates the surcharge, do not provide values for
For [[_term_checkout_]]:
- WSAPI version 50 to 70:
- The gateway always calculates the surcharge, so do not provide a value for
order.netAmount.
- The gateway always calculates the surcharge, so do not provide a value for
- WSAPI version 71 onwards:
- Do not provide values for
order.netAmountandorder.merchantCharge.typeas surcharge since the gateway always calculates the surcharge.
- Do not provide values for
If the payer requests a refund, will the surcharge amount be refunded?
Yes, since the surcharge is included in the order.amount field, the entire amount, including the surcharge,
will be refunded to the payer. For partial refunds, the surcharge will be refunded proportionally.
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. This 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 or 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.
You can use these details to calculate a surcharge based on the card presented by the payer.