# Surcharging source: https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/funding-and-fee-information/surcharging/index.md ## Overview {#overview} A surcharge is an extra fee that merchants add to cover the cost of accepting card payments. Mastercard Gateway allows you to add this fee based on: * How the integration works, for example, through Hosted Checkout or API or Hosted Batch. * 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. To let the gateway calculate a surcharge for a transaction, you need to set up surcharge rules in Merchant Administration. If you are using API or Batch, you can also provide a pre-calculated surcharge on the order. Alert: Surcharging is not applicable for card payments made in the US. To find out if you can add surcharges to card payments in your region, contact your payment service provider or check the card scheme for card payments and regulations in your region. ## Prerequisites {#prerequisites} * Your payment service provider must enable you for surcharging on your merchant profile with Mastercard Gateway. * Configure surcharging rules in Merchant Administration that allow the gateway to calculate the surcharge. ## Integration methods to use surcharging {#integration-methods-to-use-surcharging} The gateway supports surcharging on transactions using the following integration methods: * [Integrating through API](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/funding-and-fee-information/surcharging/index.md#integrating-through-api) * [Integrating through Hosted Checkout](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/funding-and-fee-information/surcharging/index.md#integrating-through-hosted-checkout) * [Integrating through Hosted Batch](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/funding-and-fee-information/surcharging/index.md#integrating-through-hosted-batch) ### Integrating through Mastercard Gateway API versions 50 to 66 {#integrating-through-mastercard-gateway-api-versions-50-to-66} You can apply a surcharge on an order using one of the following options: * [The surcharge is calculated by the gateway](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/funding-and-fee-information/surcharging/index.md#the-surcharge-calculated-by-the-gateway) * [The surcharge is calculated by the merchant](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/funding-and-fee-information/surcharging/index.md#the-surcharge-calculated-by-the-merchant) #### The surcharge is calculated by the gateway {#the-surcharge-is-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 the `merchantCharge.type` field is a surcharge. Alert: Do not provide `order.amount` field in the request. For more information, see the [FAQs](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/funding-and-fee-information/surcharging/index.md#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` Warning: 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` * `sourceOfFunds.provided.card.prefix` #### The surcharge is calculated by the merchant {#the-surcharge-is-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 the `order.amount` field. 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'). Warning: You can use the 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 the [FAQs](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/funding-and-fee-information/surcharging/index.md#faqs) section.
### Integrating through Mastercard Gateway API versions 67 and later {#integrating-through-mastercard-gateway-api-versions-67-and-later} The following tables show the fields and their descriptions for the integration through the API. **The surcharge calculated by the merchant** | Field | Description | |-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `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** | Field | Description | |-----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `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\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction) **Retrieve Transaction API Reference** [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#transaction) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#transaction) **Payment Options Inquiry API Reference** [\[REST\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#gateway) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#gateway) ### Integrating through Hosted Checkout {#integrating-through-hosted-checkout} The gateway can calculate the surcharge for you through Hosted Checkout as well. ### Integrating through Hosted Checkout API versions 50 to 66 {#integrating-through-hosted-checkout-api-versions-50-to-66} To apply a surcharge on a [Hosted Checkout](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-batch/index.md) payment, provide the following field in the Hosted Checkout. This can be done using the `INITIATE_CHECKOUT` request or the Create Checkout Session operation (available for versions 27 to 62), depending on your checkout flow: * `order.netAmount`: This is the amount payable for the order before surcharging is applied. Alert: Do not provide `order.amount` field in the request. For more information, see the [FAQs](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/funding-and-fee-information/surcharging/index.md#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. ### Integrating through Hosted Checkout API versions 71 and later {#integrating-through-hosted-checkout-api-versions-71-and-later} The gateway calculates the surcharge for the following fields: * `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. Alert: Do not provide `order.amount` field in the request. For more information, see the [FAQs](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/funding-and-fee-information/surcharging/index.md#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. Warning: The payment receipt shows the surcharge amount applied. For orders placed through Hosted Checkout that incur a surcharge, the surcharge source in the Order and Transaction Search or Details and Order CSV Export are displayed as **Gateway**. ### Integrating through Hosted Batch {#integrating-through-hosted-batch} If you send a net amount instead of the full order amount when doing batch payments (like Authorize or Pay), either through the API or by uploading a file, the payment gateway will automatically figure out and add the correct surcharge. This calculation is done in the same way as for Mastercard Gateway API Authorize or Pay transactions and is used to determine the order amount for processing the transaction. Surcharging on batch transactions is 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 Mastercard Gateway API transactions also apply to batch transactions. For more information about the Hosted Batch functionality available with the gateway, see the [Hosted Batch](https://developer.mastercard.com/mastercard-gateway/documentation/integrations-types/hosted-batch/index.md) and Batch management sections in the Merchant Administration User guide. #### Sample Batch Request for the Surcharge calculated by the gateway {#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 {#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 {#use-cases} Following are the use cases with API requests for surcharge calculation. ### Use case 1: Merchant manually calculates the Surcharge for version 67 and later {#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, Mastercard Gateway validates it to ensure that `order.amount = order.merchantCharge.amount + order.netAmount`. ##### Sample API request version 67 and later - Surcharge manually set to USD $3.00 {#sample-api-request-version-67-and-later---surcharge-manually-set-to-usd-300} ```json { "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 {#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 the following API fields in the Pay API operation: * `netAmount`: This is the sales amount without a surcharge * `merchantCharge.type = SURCHARGE`: This is a new required field for version 67 and later. ##### Sample API request version 67 and later {#sample-api-request-version-67-and-later} ```json { "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 {#faqs} 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. It will instead use the surcharge amount that you provided. Merchants can submit a Payment Option Inquiry (POI) request with a net amount, using the payment details obtained through Hosted Session. 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: 1. Creating the session in your server. 2. Updating the session in your server with any non-sensitive information you want to store in the session 3. Using the session on your web site or app to allow the gateway to gather payment details from the payer. 4. Retrieve the session content using the Retrieve Session operation and take note of the first 6 digits of the card number. 5. Submit Payment Option Inquiry with the values for gatewayEntryPoint and card prefix with the first 6 digits and pad with zero to meet length up to nine digits with those set for Auth or Pay transactions are mapped to the Gateway Entry Point values in the Surcharge rules configuration. 6. Referencing the session in payment transactions. Yes. For opting out of surcharging, provide the order.amount field in your transaction request to show the total order amount. For API: * Mastercard Gateway API version 50 to 66: * If the merchant calculates the surcharge, do not provide values for order.netAmount and order.surchargeAmount. * If the gateway calculates the surcharge, do not provide a value for order.netAmount. * Mastercard Gateway API version 67 and above: * If the merchant calculates the surcharge, do not provide values for order.netAmount, order.merchantCharge.amount, and order.merchantCharge.type as surcharge. * If the gateway calculates the surcharge, do not provide values for order.netAmount and order.merchantCharge.type as surcharge. For Hosted Checkout: * Mastercard Gateway API version 50 to 70: * The gateway always calculates the surcharge, so do not provide a value for order.netAmount. * Mastercard Gateway API version 71 and above: * Do not provide values for order.netAmount and order.merchantCharge.type as surcharge since the gateway always calculates the surcharge. 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. 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. 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. Alert: 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\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/rest/api-ops/index.md#gateway) [\[NVP\]](https://developer.mastercard.com/mastercard-gateway/documentation/api-reference/v100/nvp/api-ops/index.md#gateway)