Surcharge

Requirements

Compliance

How it works

When your user's customer pays:

1. You collect the customer's card details on your checkout page.
2. From your server, you make a /cardDetails request using the customer's card details, to get the information that helps to make a decision about the surcharge.
3. The logic you implemented decides if a surcharge is allowed and calculates the surcharge amount, using the data from the /cardDetails response.
4. You display the surcharge amount on your checkout page.
5. When the customer proceeds to pay, you make a /payments request that includes the surcharge amount.

Get card details

Use the customer's raw or encrypted card number to make an API request that retrieves the details of the card that helps to determine whether you can apply surcharge to a payment.

1. In your payment form, collect the card number of the customer with either of the following:

   • Custom payment form to collect raw card data
   • Custom Card Component integration to collect encrypted card data

2. From your server, make a /cardDetails request, including:

   Parameter	Required	Description
   cardNumber		If you accept card payments using raw card data, pass this field. Minimum length: first eight digits of the card number. We recommend to pass the full card number for the best result. You must be fully PCI compliant to collect raw card data.
   encryptedCardNumber		If you accept card payments using our Custom Card Component with encrypted card data, pass this field. The encrypted card number you get in the state.data when the Component calls the onSubmit event.
   merchantAccount		The name of your merchant account.

3. In the response, note the following data to:

   • Determine whether a surcharge is applicable for a payment.
   • Calculate the surcharge amount that you can apply.

   Response parameter	Description
   brands.type	The name of the card brand.
   fundingSource	The funding source of the card, for example, DEBIT, CREDIT, or PREPAID.
   isCardCommercial	Indicates if this is a commercial card or a consumer card. When true, it is a commercial card. When false, it is a consumer card.
   issuingCountryCode	The two-letter country code of the country where the card was issued.

4. Use the data from the response to build your logic that determines whether you can apply surcharge on a payment with this card, and calculate the surcharge amount. Refer to our Surcharge compliance guide when determining to which transactions you can apply a surcharge.

Make a payment with a surcharge

A surcharge is a type of transaction fee imposed by the card scheme, paid by your user's customer. Similar to the other transaction fees, you can use split instructions to define how to book the surcharge. You can book the surcharge amount either to your user's balance account, or to your liable balance account.

1. Make a /payments request with your API only with raw card data integration, or with your API only with encrypted card data integration.
2. In your request include a surcharge object, that specifies the value of the surcharge you apply to the transaction.
3. Calculate the value you need to pass in the amount.value field in your /payments request by adding the surcharge amount to the original transaction amount.
4. In the splits array, add a split item for the surcharge.

5. For the split item of the surcharge, specify the following fields:

   Parameter	Required	Description
   account		The balanceAccountId of one of your user's balance accounts that will receive the surcharge amount.
   amount.currency		The currency of the part of the surcharge you want to book the specified account.
   amount.value		The value of the surcharge you want to book to the specified account.
   type		Defines the part of the payment you want to book to the specified account. Set to Surcharge.
   reference		Your reference for the surcharge, reflected in the Balance Platform Accounting Report. You need this for reconciliation purposes.
   description		Your description for the surcharge, reflected in the Balance Platform Accounting Report.

Example split payment with surcharge

Here is an example of how you can split the payment and surcharge amount at the time of payment, when a customer pays EUR 400.00.

• EUR 394.00 are booked to your user's balance account as payment for the goods or services.
• EUR 2.00 are booked to your user's balance account as the surcharge.
• EUR 4.00 are booked to your liable balance account as your marketplace's commission.
• All transaction fees are booked to your user's balance account, deducted from the sale amount.

In the response, note that your reference from the request is returned as the merchantReference. You need this information for reconciliation.

Track fund movements

To track the status of the fund transfers initiated by a surcharge:

1. Listen to the following webhooks:
   • Transfer webhooks: Adyen sends a balancePlatform.transfer.created webhook to inform your server that funds will be credited to balance accounts, and balancePlatform.transfer.updated webhooks after every status change.
   • Transaction webhooks: Adyen sends a balancePlatform.transaction.created webhook to inform your server that funds have been credited to a balance account.
2. Acknowledge the webhooks. We send these webhooks for every split item in the payment.
3. In the balancePlatform.transfer.updated webhook payload, note that the event array includes all previous transfer events, and the sequenceNumber defines the number of webhooks sent for the transfer, including the current one.

Webhook examples

The following examples show the webhooks you receive for a surcharge. We send webhooks for each balance account involved in the payment, and each split of the payment amount, including the surcharge.

You can identify surcharge-related transfer webhooks by the following values:

Reports and reconciliation

See also