Worldline Global Online Pay

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!

This feature is available for
All integration modes
Card payment methods

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

"Pass Through" is only available for integration modes Server-to-server/Hosted Tokenization Page/Mobile/Client Integration

The following properties define the surcharge of your order in a CreateHostedCheckout/CreatePayment request for Hosted Checkout Page/Hosted Tokenization Page/ Server-to-server/Mobile/Client Integration 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

Properties surchargeAmount.amount/currencyCode are only mandatory for mode="pass-through" in the CreatePayment request. When using mode="on-behalf-of", our platform will add the allowable surcharge automatically when processing the order

Apply Surcharging

Depending on the integration mode 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 AUD for the actual order
A surcharge amount of $0.33 AUD

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

Make sure to contact us before using this feature, as we will have to preconfigure your account

If you follow-up on processed transactions, consult the dedicated chapters to make sure you do it correctly:
Capture transactions
Refund transactions

Apply "On Behalf Of" surcharging

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

Hosted Checkout Page
Hosted Tokenization Page
Server-to-server/Mobile/Client Integration

Hosted Checkout Page

Follow these steps to create a request for this order:

This is a high-level payment flow covering only the mandatory steps for this feature. Read our dedicated chapter in our Hosted Checkout Page guide for detailed information, code samples and optional steps in the flow

Your customers go to your check-out page and finalises the order
You send this CreateHostedCheckout request to our platform, including the net amount (10 AUD 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":"AUD"
      },
      "surchargeSpecificInput":{
         "mode":"on-behalf-of"
      }
   }
}
```
You redirect the customers in the browser to the redirectUrl. The redirectUrl displays the net amount in field "Total charge" ($10 AUD 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 AUD in this example). If the customer updates their payment details, the payment page will update any changes to the surcharge automatically
The customers confirm the payment
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:

This is a high-level payment flow covering only the mandatory steps for this feature. Read our dedicated chapter in our Hosted Tokenization Page guide for detailed information, code samples and optional steps in the flow

Your customers go to your check-out page and finalise the purchase
You send a CreateHostedTokenization request to our platform. Our platform returns a hostedTokenizationURL
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 AUD in this example) for this tokenizer instance:
```
    var tokenizer = new Tokenizer(
   hostedTokenizationUrl,
   'div-hosted-tokenization',
    {	
   surchargeCallback: mySurchargeCallback, 
	   // other properties omitted
    });

tokenizer.setAmount(1000, "AUD");
```
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
Your customers submit the card data to our platform by invoking submitTokenization() function from the JavaScript code snippet
Our platform tokenises the card data

You send this CreatePayment request to our platform, including the net amount ($10 AUD 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":"AUD"
      },
      "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"
            }
         }
      }
   }
}

We process the transaction and receive the result from the acquirer

Server-to-server/Mobile/Client Integration

Follow these steps to create a request for this order:

This is a high-level payment flow covering only the mandatory steps for this feature. Read our dedicated chapter in our Server-to-server guide for detailed information, code samples and optional steps in the flow

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
You send this SurchargeCalculation request to our platform, including the net amount ($10 AUD 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":"AUD"
   }
}
```
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

You send this CreatePayment request to our platform, including the net amount ($10 AUD 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":"AUD"
      },
      "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"
            }
         }
      }
   }
}

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 modes:

Hosted Tokenization Page
Server-to-server/Mobile/Client Integration

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:

Your customers go to your check-out page and finalise the purchase
You send a CreateHostedTokenization request to our platform. Our platform returns a hostedTokenizationURL
You invoke the initialize() function from the JavaScript code snippet to add the payment form in an <iframe>
Your customers submit the card data to our platform by invoking submitTokenization() function from the JavaScript code snippet
Our platform tokenises the card data

You send this CreatePayment request to our platform, including the net amount $10 AUD in this example) in property order.amountOfMoney.amount, the surcharge to be added ($0.33 AUD 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":"AUD"
      },
      "surchargeSpecificInput":{
         "mode":"pass-through",
         "surchargeAmount":{
            "amount":33,
            "currencyCode":"AUD"
         }
      },
      "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"
            }
         }
      }
   }
}

We process the transaction and receive the result from the acquirer

Server-to-server/Mobile/Client Integration

Follow these steps to create a request for this order:

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

You send this CreatePayment request to our platform, including the net amount ($10 AUD in this example) in property order.amountOfMoney.amount , the surcharge to be added ($0.33 AUD 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":"AUD"
      },
      "surchargeSpecificInput":{
         "mode":"pass-through",
         "surchargeAmount":{
            "amount":33,
            "currencyCode":"AUD"
         }
      },
      "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"
            }
         }
      }
   }
}

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 AUD 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 AUD plus the surcharge ($0.33 AUD 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.

This feature supports only a single partial capture

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

Surcharging

Introduction

Understand Surcharging

Apply Surcharging

Apply "On Behalf Of" surcharging

Hosted Checkout Page

Hosted Tokenization Page

Server-to-server/Mobile/Client Integration

Apply "Pass Through" surcharging

Hosted Tokenization Page

Server-to-server/Mobile/Client Integration

Follow-up on Surcharging transactions

Capture transactions

Refund transactions

Get feedback on processed transactions

Was this page helpful?

Do you have any comments?