Surcharging

Introduction

Managing costs is essential for an effective business, which also applies to transactions themselves. Accepting payments can come with many types of variable fees.

Rather than building these into the price of your goods or services, our surcharging feature allows you to increase transparency of these fees to your customers.

Using our Surcharging feature, you can:

• Pass on a surcharge to your customer to recover your cost of acceptance
• Comply with rules imposed by payment networks and local regulators
• Query surcharge rates and amounts via our API and webhooks

We will be happy to get you started!

Understand Surcharging

We support two modes of surcharging. Contact us to configure your account(s) for this feature:

• "On Behalf Of": Our platform automatically calculates and applies a surcharge to a transaction, easing your integration efforts. We calculate the amount based on
  • The card itself (i.e. brand, issuing country, credit/debit card type)
  • Your preconfigured surcharging rates. Contact us to set this up
• "Pass Through": You calculate the amount based on
  • On your own calculation and ensure it complies to the local / card scheme's regulations
  • Some preconfigured settings on our side. Contact us to set this up

The following properties define the surcharge of your order in a CreateHostedCheckout/CreatePayment request for Hosted Checkout Page/Hosted Tokenization Page/ Server-to-server/Integration für Mobilgeräte modes. 

Properties	Remarks
order.amountOfMoney      amount      currencyCode	amount: The net amount (without the surcharge) you want to charge for this order currencyCode: The ISO 4217 currency code for this amount
order.surchargeSpecificInput      mode      surchargeAmount           amount           currencyCode	mode: Depending on your preferences, set to either "on-behalf-of" or "pass-through" amount: The surcharge amount on top of the net amount (order.amountOfMoney.currencyCode) currencyCode: The ISO 4217 currency code for this amount

Apply Surcharging

Depending on the integration methods and the chosen surcharge mode, differences apply.

To get a full understanding of how this feature works for any given setup, we use an example with

• A fixed net amount of 10 EUR for the actual order
• A surcharge amount of 0.33 EUR 

Use this hands-on scenario to apply surcharges to your payment requests.

Apply "On Behalf Of" surcharging

We offer "On Behalf Of" surcharge mode for the following integration methods:

• Hosted Checkout Page
• Hosted Tokenization Page
• Server-to-server/Integration für Mobilgeräte

Hosted Checkout Page

Follow these steps to create a request for this order:

1. Your customers go to your check-out page and finalises the order
2. You send this CreateHostedCheckout request to our platform, including the net amount (10 EUR in this example) in property amount and the chosen surcharge mode in mode. Our platform will then automatically enable surcharging on that order:

   {
      "order":{
         "amountOfMoney":{
            "amount":1000,
            "currencyCode":"EUR"
         },
         "surchargeSpecificInput":{
            "mode":"on-behalf-of"
         }
      }
   }
   

3. You redirect the customers in the browser to the redirectUrl. The redirectUrl displays the net amount in field "Total charge" (10 EUR in this example). Once the customer enters their card number on the payment page, our platform calculates the surcharge amount and displays it on a new line "Card surcharge" within the page. At the same time, the "Total charge" field is updated to the final amount including the surcharge (10.33 EUR in this example). If the customer updates their payment details, the payment page will update any changes to the surcharge automatically
4. The customers confirm the payment
5. We process the transaction and receive the result from the acquirer

Hosted Tokenization Page

To use this feature, you need to include the following JavaScript element in addition to the standard ones:

function mySurchargeCallback(result) {
	if (result.surcharge.success) {
		console.log(result.surcharge.result);
    }
	else {
		console.log(result.surcharge.error)
	}
}

The mySurchargeCallback function returns the applicable chargeback rate once your customer fills in the iframe with their card number.

Follow these steps to create a request for this order:

1. Your customers go to your check-out page and finalise the purchase
2. You send a CreateHostedTokenization request to our platform. Our platform returns a hostedTokenizationURL
3. You invoke the initialize() function from the JavaScript code snippet to add the payment form in an <iframe>. Make sure to add the mySurchargeCallback  property when creating the tokenizer instance and to define the net amount and currency (10 EUR in this example) for this tokenizer instance: 

   
       var tokenizer = new Tokenizer(
      hostedTokenizationUrl,
      'div-hosted-tokenization',
       {	
      surchargeCallback: mySurchargeCallback, 
   	   // other properties omitted
       });
   
   tokenizer.setAmount(1000, "EUR");

4. Your customers enter their credit card data in the <iframe>. Our platform returns the allowable surcharge amount for the card by invoking the mySurchargeCallback function. This also applies every time the customers update the card number. Make sure to display the surcharge in real time for maximum transparency to your customers before the actual payment
5. Your customers submit the card data to our platform by invoking submitTokenization() function from the JavaScript code snippet
6. Our platform tokenises the card data
7. You send this CreatePayment request to our platform, including the net amount (10 EUR in this example) in property amount and the chosen surcharge mode in mode:

   
   {
      "CardPaymentMethodSpecificInput":{
         "PaymentProductId":1,
         "SkipAuthentication":false,
         "Token":"tokenId",
         "ThreeDSecure":{
            "RedirectionData":{
               "ReturnUrl":"https://yourRedirectionUrl.com"
            }
         }
      },
      "Order":{
         "AmountOfMoney":{
            "Amount":1000,
            "CurrencyCode":"EUR"
         },
         "surchargeSpecificInput":{
            "mode":"on-behalf-of"
         },
         "Customer":{
            "Device":{
               "AcceptHeader":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3",
               "Locale":"en_EN",
               "TimezoneOffsetUtcMinutes":-180,
               "UserAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36",
               "Browserdata":{
                  "ColorDepth":24,
                  "JavaScriptEnabled":false,
                  "ScreenHeight":"1080",
                  "ScreenWidth":"1920"
               }
            }
         }
      }
   }
   

8. We process the transaction and receive the result from the acquirer

!{dv.get('direct.S2S')}/!{dv.get('direct.title.mobile-client-integration')}

Follow these steps to create a request for this order:

1. Your customers go to your check-out page and enters their credit card data to finalise the purchase
   1'(optional). You send a GetIINDetails request to our platform to receive information about the customer's card BIN. Our response will contain both the card’s issuing country (countryCode) and the brand (paymentProductId), allowing you to assess the allowable surcharge
2. You send this SurchargeCalculation request to our platform, including the net amount (10 EUR in this example) in the property amount and your customer’s card in the property cardNumber

   {
      "cardsource":{
         "card":{
            "cardNumber":"4330264936344675",
            "paymentProductId":1
         }
      },
      "amountOfMoney":{
         "amount":1000,
         "currencyCode":"EUR"
      }
   }
   

   
   Our platform returns the allowable surcharge amount in the property surcharges.surchargeAmount.amount and the total amount including the surcharge in the property surcharges.totalAmount.amount. Make sure to display the surcharge amount in real time for maximum transparency to your customers before the actual payment
3. You send this CreatePayment request to our platform, including the net amount (10 EUR in this example) in property amount and the chosen surcharge mode in mode. Our platform will automatically add the allowable surcharge to the order:

   {
      "CardPaymentMethodSpecificInput":{
         "PaymentProductId":1,
         "SkipAuthentication":false,
         "Card":{
            "CardholderName":"John Doe",
            "CardNumber":"4330264936344675",
            "Cvv":123,
            "ExpiryDate":1236
         },
         "ThreeDSecure":{
            "RedirectionData":{
               "ReturnUrl":"https://yourRedirectionUrl.com"
            }
         }
      },
      "Order":{
         "AmountOfMoney":{
            "Amount":1000,
            "CurrencyCode":"EUR"
         },
         "surchargeSpecificInput":{
            "mode":"on-behalf-of"
         },
         "Customer":{
            "Device":{
               "AcceptHeader":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3",
               "Locale":"en_EN",
               "TimezoneOffsetUtcMinutes":-180,
               "UserAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36",
               "Browserdata":{
                  "ColorDepth":24,
                  "JavaScriptEnabled":false,
                  "ScreenHeight":"1080",
                  "ScreenWidth":"1920"
               }
            }
         }
      }
   }
   

4. We process the transaction and receive the result from the acquirer

Apply "Pass Through" surcharging

We offer "Pass Through" surcharge mode for the following integration methods:

• Hosted Tokenization Page
• Server-to-server/Integration für Mobilgeräte

When using this mode, you take full ownership of calculating and adding the allowable surcharge to your customers’ orders. Therefore, make sure to comply with any surcharge regulations applicable to you.

Hosted Tokenization Page

Follow these steps to create a request for this order:

1. Your customers go to your check-out page and finalise the purchase
2. You send a CreateHostedTokenization request to our platform. Our platform returns a hostedTokenizationURL
3. You invoke the initialize() function from the JavaScript code snippet to add the payment form in an <iframe>
4. Your customers submit the card data to our platform by invoking submitTokenization() function from the JavaScript code snippet
5. Our platform tokenises the card data
6. You send this CreatePayment request to our platform, including the net amount 10 EUR in this example) in property order.amountOfMoney.amount, the surcharge to be added (0.33 EUR in this example) in property surchargeAmount.amount and the chosen surcharge mode in mode:

   
   {
      "CardPaymentMethodSpecificInput":{
         "PaymentProductId":1,
         "SkipAuthentication":false,
         "Token":"tokenId",
         "ThreeDSecure":{
            "RedirectionData":{
               "ReturnUrl":"https://yourRedirectionUrl.com"
            }
         }
      },
      "Order":{
         "AmountOfMoney":{
            "Amount":1000,
            "CurrencyCode":"EUR"
         },
         "surchargeSpecificInput":{
            "mode":"pass-through",
            "surchargeAmount":{
               "amount":33,
               "currencyCode":"EUR"
            }
         },
         "Customer":{
            "Device":{
               "AcceptHeader":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3",
               "Locale":"en_EN",
               "TimezoneOffsetUtcMinutes":-180,
               "UserAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36",
               "Browserdata":{
                  "ColorDepth":24,
                  "JavaScriptEnabled":false,
                  "ScreenHeight":"1080",
                  "ScreenWidth":"1920"
               }
            }
         }
      }
   }
   

7. We process the transaction and receive the result from the acquirer

Server-to-server/Integration für Mobilgeräte

Follow these steps to create a request for this order:

1. Your customers goes to your check-out page and enters their credit card data to finalise the purchase
   1'(optional). You send a GetIINDetails request to our platform to receive information about the customer's card BIN. Our response will contain both the card’s issuing country (countryCode) and the brand (paymentProductId), allowing you to assess the allowable surcharge
2. You send this CreatePayment request to our platform, including the net amount (10 EUR in this example) in property order.amountOfMoney.amount , the surcharge to be added (0.33 EUR in this example) in property surchargeAmount.amount and the chosen surcharge mode in mode:

   {
      "CardPaymentMethodSpecificInput":{
         "PaymentProductId":1,
         "SkipAuthentication":false,
         "Card":{
            "CardholderName":"John Doe",
            "CardNumber":"4330264936344675",
            "Cvv":123,
            "ExpiryDate":1236
         },
         "ThreeDSecure":{
            "RedirectionData":{
               "ReturnUrl":"https://yourRedirectionUrl.com"
            }
         }
      },
      "Order":{
         "AmountOfMoney":{
            "Amount":1000,
            "CurrencyCode":"EUR"
         },
         "surchargeSpecificInput":{
            "mode":"pass-through",
            "surchargeAmount":{
               "amount":33,
               "currencyCode":"EUR"
            }
         },
         "Customer":{
            "Device":{
               "AcceptHeader":"text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3",
               "Locale":"en_EN",
               "TimezoneOffsetUtcMinutes":-180,
               "UserAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36",
               "Browserdata":{
                  "ColorDepth":24,
                  "JavaScriptEnabled":false,
                  "ScreenHeight":"1080",
                  "ScreenWidth":"1920"
               }
            }
         }
      }
   }
   

3. We process the transaction and receive the result from the acquirer

Follow-up on Surcharging transactions

Capture transactions

When capturing a transaction with surcharge, make sure to capture only the net amount (10 EUR from our example for the actual order). Our platform will automatically capture the surcharge amount on top of the net amount, resulting in a total gross amount of 10 EUR plus the surcharge (0.33 EUR in our example). Send the capture with standard properties as defined in our API reference. For partial captures, our platform automatically adds a pro-rated surcharge on top of the net amount you send in order.amount.amountOfMoney.

Refund transactions

When refunding a transaction with surcharge, our platform will always process the exact amount defined in property order.amountOfMoney.amount. For full discretion and certainty, our platform will not perform any additional surcharging calculations. Send the refund request with standard properties as defined in our API reference.

Get feedback on processed transactions

Our platform provides information about surcharges for processed transactions via both webhooks and GetPayment/GetPaymentDetails calls. Any webhooks/GET call will contain the following properties:

paymentOutput.surchargeSpecificOutput
     mode
     surchargeAmount
         amount
     surchargeAmount
          currencyCode