No momento, esta página não está disponível em português
Adyen-for-platform icon

Surcharge

Enable your users to pass on payment acceptance fees to their customers as a surcharge to their payments.

Payment brands, such as card schemes and debit network providers, charge a fee for accepting payments on their payment network, called a payment acceptance fee. As a platform, you must have agreements in place with your users about how the payment acceptance fee is charged for each payment.

Your users can pass on these costs to their customers by adding a surcharge to their payments.

Requirements

Requirement Description
Integration type Make sure that you have an Adyen for Platforms implementation with an API-only online payments integration that can accept card payments with either:
API credential roles You need an API credential with an API key and the Checkout webservice role.
Webhooks Ensure that your server can receive and accept standard webhooks.
To track fund movements in your platform, you can subscribe to any of the following webhooks:
Limitations Make sure that you take into account the following:
  • The surcharge feature is in pilot, and restrictions may apply. Reach out to your Adyen contact to be part of the pilot.
  • Surcharges cannot be applied to authorization adjustments or overcaptures. The surcharge amount cannot be higher than the surcharge amount that was shown to the customer at the moment of purchase.
Setup steps Before you begin:
  • Make sure you comply with the general and regional compliance requirements mentioned in our Surcharge compliance guide.
  • We recommend consulting your own legal advisor on compliance with regulatory requirements, and reviewing the scheme rules for the latest information.

Compliance

Surcharges must comply with general requirements. For example, you need to provide signage to inform customers about the payment methods that are subject to surcharges, and the related costs such as the surcharge percentage.

Surcharges must also comply with regional requirements. For example, in the European Economic Area (EEA) surcharges are not allowed on payments made with a consumer card that was issued in the EEA. And in the US surcharges are not allowed on payments made with a debit card.

The Adyen surcharge feature does not enforce compliance. It is your responsibility to apply surcharges correctly.

For more information about requirements, see our Surcharge compliance guide.

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:

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

    Parameter Required Description
    cardNumber Conditionally required 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 Conditionally required 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 Required 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 Required The balanceAccountId of one of your user's balance accounts that will receive the surcharge amount.
    amount.currency Required The currency of the part of the surcharge you want to book the specified account.
    amount.value Required The value of the surcharge you want to book to the specified account.
    type Required Defines the part of the payment you want to book to the specified account.
    Set to Surcharge.
    reference Recommended 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 platform'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:
  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:

Parameter Description Value
category Specifies the category of the transfer. platformPayment
direction The direction of the transfer based on the balance account. incoming
type Specifies the type of the transfer. payment
platformPaymentType Specifies the nature of each transfer on the balance platform. This parameter helps categorize transfers so you can reconcile transactions at a later time using the Balance Platform Accounting Report. Surcharge

1. Incoming transfer received

When a transfer request is received to credit funds for the surcharge to your user's balance account, Adyen sends a balancePlatform.transfer.created webhook with status received and direction incoming. The webhook provides information about the transfer, such as the payment and split references and which user and balance account is credited with the funds.

2. Incoming transfer authorized

When the transfer request is authorized, Adyen sends a balancePlatform.transfer.updated webhook with status authorised.

3. Incoming transfer captured

When the funds are credited to your user's balance account, Adyen sends a balancePlatform.transfer.updated webhook with status captured and the transactionId.

4. Transaction booked

When the funds are credited, Adyen also sends a balancePlatform.transaction.created webhook, which includes information about the related transaction.

Reports and reconciliation

To have full visibility of the surcharge amounts that were added to payments, we strongly recommend you add an extra column Surcharge Amount to the following reports:

If you specify the split type Surcharge in the payment request or in the split configuration, a separate incoming transfer is generated for the surcharge amount. The following reports are affected:

See also