--- title: "Surcharge" description: "Pass on payment acceptance fees to your customers as a surcharge to their payments." url: "https://docs.adyen.com/online-payments/surcharge" source_url: "https://docs.adyen.com/online-payments/surcharge.md" canonical: "https://docs.adyen.com/online-payments/surcharge" last_modified: "2024-11-12T17:18:00+01:00" language: "en" --- # Surcharge Pass on payment acceptance fees to your customers as a surcharge to their payments. [View source](/online-payments/surcharge.md) 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. Usually, businesses include the costs for payment-related fees in the prices they charge. But in some countries/regions it is common to pass on these costs as a surcharge when the customer uses a card for payment. ## Requirements | Requirement | Description | | | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | | **Integration type** | Make sure that you have an [API-only online payments](/online-payments/build-your-integration/advanced-flow?platform=Web\&integration=API%20only\&version=latest) integration that can accept card payments with either:- [Raw card data](/payment-methods/cards/raw-card-data/) - [Encrypted card data](/payment-methods/cards/custom-card-integration/) | | | **[API credential roles](/development-resources/api-credentials/roles/)** | You need an API credential with an API key and the **Checkout webservice role**. | | | **[Webhooks](/development-resources/webhooks)** | Subscribe to Standard 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](/online-payments/adjust-authorisation/) or [overcaptures](/get-started-with-adyen/adyen-glossary#overcapture). 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](/development-resources/surcharge-compliance/). - We recommend consulting your own legal advisor on compliance with regulatory requirements, and reviewing the scheme rules for the latest information. | | ## Compliance ## How it works When your shopper proceeds to pay: 1. Collect the shopper's card details on your checkout page. 2. From your server, make a [/cardDetails](https://docs.adyen.com/api-explorer/Checkout/latest/post/cardDetails) request using the shopper's card details, to get the information that helps to make a decision about the surcharge. 3. Implement logic to decide if a surcharge is allowed, and to calculate the surcharge amount, using the data from the [/cardDetails](https://docs.adyen.com/api-explorer/Checkout/latest/post/cardDetails) response. 4. Display the surcharge amount on your checkout page. 5. When the shopper proceeds to pay, from your server, make a [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/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](/payment-methods/cards/raw-card-data/#build-your-payment-form-for-cards) * [Custom Card Component integration to collect encrypted card data](/payment-methods/cards/custom-card-integration/) 2. From your server, make a [/cardDetails](https://docs.adyen.com/api-explorer/Checkout/latest/post/cardDetails) request, including: | Parameter | Required | Description | | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [cardNumber](https://docs.adyen.com/api-explorer/Checkout/latest/post/cardDetails#request-cardNumber) | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | If you accept card payments using [raw card data](/payment-methods/cards/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](/development-resources/pci-dss-compliance-guide/) to collect raw card data. | | [encryptedCardNumber](https://docs.adyen.com/api-explorer/Checkout/latest/post/cardDetails#request-encryptedCardNumber) | ![Conditionally required](/user/pages/reuse/image-library/01.icons/conditionally-required/conditionally-required.svg?decoding=auto\&fetchpriority=auto) | If you accept card payments using our [Custom Card Component with encrypted card data](/payment-methods/cards/custom-card-integration/), pass this field. The encrypted card number you get in the `state.data` when the [Component](/payment-methods/cards/custom-card-integration/#show-the-available-cards-in-your-payment-form) calls the `onSubmit` event. | | [merchantAccount](https://docs.adyen.com/api-explorer/Checkout/latest/post/cardDetails#request-merchantAccount) | ![Required](/user/pages/reuse/image-library/01.icons/required/required.svg?decoding=auto\&fetchpriority=auto) | The name of your merchant account. | **Make a request to get information about the card** #### curl ```bash curl https://checkout-test.adyen.com/v71/cardDetails \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "encryptedCardNumber": "adyenjs_0_1_18$MT6ppy0FAMVMLH..." }' ``` #### Java ```java // Adyen Java API Library v40.0.0 import com.adyen.Client; import com.adyen.enums.Environment; import com.adyen.model.checkout.*; import java.time.OffsetDateTime; import java.util.*; import com.adyen.model.RequestOptions; import com.adyen.service.checkout.*; // For the LIVE environment, also include your liveEndpointUrlPrefix. Client client = new Client("ADYEN_API_KEY", Environment.TEST); // Create the request object(s) CardDetailsRequest cardDetailsRequest = new CardDetailsRequest() .encryptedCardNumber("adyenjs_0_1_18$MT6ppy0FAMVMLH...") .merchantAccount("YOUR_MERCHANT_ACCOUNT"); // Send the request PaymentsApi service = new PaymentsApi(client); CardDetailsResponse response = service.cardDetails(cardDetailsRequest, new RequestOptions().idempotencyKey("UUID")); ``` #### PHP ```php setXApiKey("ADYEN_API_KEY"); // For the LIVE environment, also include your liveEndpointUrlPrefix. $client->setEnvironment(Environment::TEST); // Create the request object(s) $cardDetailsRequest = new CardDetailsRequest(); $cardDetailsRequest ->setEncryptedCardNumber("adyenjs_0_1_18\$MT6ppy0FAMVMLH...") ->setMerchantAccount("YOUR_MERCHANT_ACCOUNT"); $requestOptions['idempotencyKey'] = 'UUID'; // Send the request $service = new PaymentsApi($client); $response = $service->cardDetails($cardDetailsRequest, $requestOptions); ``` #### C\# ```cs // Adyen .NET API Library v32.2.1 using Adyen; using Environment = Adyen.Model.Environment; using Adyen.Model; using Adyen.Model.Checkout; using Adyen.Service.Checkout; // For the LIVE environment, also include your liveEndpointUrlPrefix. var config = new Config() { XApiKey = "ADYEN_API_KEY", Environment = Environment.Test }; var client = new Client(config); // Create the request object(s) CardDetailsRequest cardDetailsRequest = new CardDetailsRequest { EncryptedCardNumber = "adyenjs_0_1_18$MT6ppy0FAMVMLH...", MerchantAccount = "YOUR_MERCHANT_ACCOUNT" }; // Send the request var service = new PaymentsService(client); var response = service.CardDetails(cardDetailsRequest, requestOptions: new RequestOptions { IdempotencyKey = "UUID"}); ``` #### NodeJS (JavaScript) ```js // Adyen Node API Library v30.0.0 const { Client, CheckoutAPI } = require('@adyen/api-library'); // For the LIVE environment, also include your liveEndpointUrlPrefix. const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const cardDetailsRequest = { merchantAccount: "YOUR_MERCHANT_ACCOUNT", encryptedCardNumber: "adyenjs_0_1_18$MT6ppy0FAMVMLH..." } // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.PaymentsApi.cardDetails(cardDetailsRequest, { idempotencyKey: "UUID" }); ``` #### Go ```go // Adyen Go API Library v21.1.0 import ( "context" "github.com/adyen/adyen-go-api-library/v21/src/common" "github.com/adyen/adyen-go-api-library/v21/src/adyen" "github.com/adyen/adyen-go-api-library/v21/src/checkout" ) // For the LIVE environment, also include your liveEndpointUrlPrefix. client := adyen.NewClient(&common.Config{ ApiKey: "ADYEN_API_KEY", Environment: common.TestEnv, }) // Create the request object(s) cardDetailsRequest := checkout.CardDetailsRequest{ EncryptedCardNumber: common.PtrString("adyenjs_0_1_18$MT6ppy0FAMVMLH..."), MerchantAccount: "YOUR_MERCHANT_ACCOUNT", } // Send the request service := client.Checkout() req := service.PaymentsApi.CardDetailsInput().IdempotencyKey("UUID").CardDetailsRequest(cardDetailsRequest) res, httpRes, err := service.PaymentsApi.CardDetails(context.Background(), req) ``` #### Python ```py # Adyen Python API Library v14.0.0 import Adyen adyen = Adyen.Adyen() adyen.client.xapikey = "ADYEN_API_KEY" # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.client.platform = "test" # The environment to use library in. # Create the request object(s) json_request = { "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "encryptedCardNumber": "adyenjs_0_1_18$MT6ppy0FAMVMLH..." } # Send the request result = adyen.checkout.payments_api.card_details(request=json_request, idempotency_key="UUID") ``` #### Ruby ```rb # Adyen Ruby API Library v11.0.0 require "adyen-ruby-api-library" adyen = Adyen::Client.new adyen.api_key = 'ADYEN_API_KEY' # For the LIVE environment, also include your liveEndpointUrlPrefix. adyen.env = :test # Set to "live" for live environment # Create the request object(s) request_body = { :merchantAccount => 'YOUR_MERCHANT_ACCOUNT', :encryptedCardNumber => 'adyenjs_0_1_18$MT6ppy0FAMVMLH...' } # Send the request result = adyen.checkout.payments_api.card_details(request_body, headers: { 'Idempotency-Key' => 'UUID' }) ``` #### NodeJS (TypeScript) ```ts // Adyen Node API Library v30.0.0 import { Client, CheckoutAPI, Types } from "@adyen/api-library"; // For the LIVE environment, also include your liveEndpointUrlPrefix. const config = new Config({ apiKey: "ADYEN_API_KEY", environment: EnvironmentEnum.TEST }); const client = new Client(config); // Create the request object(s) const cardDetailsRequest: Types.checkout.CardDetailsRequest = { encryptedCardNumber: "adyenjs_0_1_18$MT6ppy0FAMVMLH...", merchantAccount: "YOUR_MERCHANT_ACCOUNT" }; // Send the request const checkoutAPI = new CheckoutAPI(client); const response = checkoutAPI.PaymentsApi.cardDetails(cardDetailsRequest, { idempotencyKey: "UUID" }); ``` 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](https://docs.adyen.com/api-explorer/Checkout/latest/post/cardDetails#responses-200-brands-type) | The name of the card brand. | | [fundingSource](https://docs.adyen.com/api-explorer/Checkout/latest/post/cardDetails#responses-200-fundingSource) | The funding source of the card, for example, **DEBIT**, **CREDIT**, or **PREPAID**. | | [isCardCommercial](https://docs.adyen.com/api-explorer/Checkout/latest/post/cardDetails#responses-200-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](https://docs.adyen.com/api-explorer/Checkout/latest/post/cardDetails#responses-200-issuingCountryCode) | The two-letter country code of the country where the card was issued. | **Example /cardDetails response** ```json { "brands": [ { "type": "visa", "supported": true }, { "type": "cartebancaire", "supported": true } ], "fundingSource": "CREDIT", "isCardCommercial": false, "issuingCountryCode": "US" } ``` 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](/development-resources/surcharge-compliance/) when determining to which transactions you can apply a surcharge. ## Make a payment including the surcharge After you calculate the surcharge amount, disclose the surcharge amount to your shopper and include the surcharge in your payment request. 1. Make a [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request with your [API only with raw card data integration](/payment-methods/cards/raw-card-data/#make-a-payment), or with your [API only with encrypted card data integration](/payment-methods/cards/custom-card-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` object in your [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request by adding the surcharge amount to the original transaction amount. **Make a payment with encrypted card details including a surcharge** ```bash curl https://checkout-test.adyen.com/v72/payments \ -H 'x-api-key: ADYEN_API_KEY' \ -H 'content-type: application/json' \ -d '{ "amount":{ "currency":"USD", "value":1100 }, "surcharge":{ "value":100 }, "reference":"YOUR_ORDER_NUMBER", "returnUrl": "https://your-company.example.com/...", "merchantAccount":"ADYEN_MERCHANT_ACCOUNT", "paymentMethod:{ "type":"scheme", "encryptedCardNumber": "test_4111111111111111", "encryptedExpiryMonth": "test_03", "encryptedExpiryYear": "test_2030", "encryptedSecurityCode": "test_737", "holderName": "S. Hopper" }, "riskData":{ "clientData": "eyJ0cmFuc1N0YXR1cy...I6IlkifQ==" } }' ``` The [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) response contains: * `pspReference`: Our unique identifier for the transaction. * `resultCode`: Use this to present the payment result to your shopper. * `merchantReference`: The reference from the `/payments` request. * `additionalData`: Additional information about the transaction. You can optionally enable [receiving the surcharge amount](#receive-surcharge-in-additional-data) in additional data. For transactions where you apply a surcharge, when you make a [capture](/online-payments/capture/), or [refund](/online-payments/refund/) request, pass the full amount that includes the surcharge amount. ### Receive the surcharge in additional data To receive the amount of surcharge you apply to a transaction in the `additionalData` object of the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) response, or in the [AUTHORISATION](https://docs.adyen.com/api-explorer/Webhooks/latest/post/AUTHORISATION) webhook: 1. In your [Customer Area](https://ca-test.adyen.com/), go to **Developers** > **Additional data**. 2. Select **Surcharge amount**. 3. Select **Save configuration**. ## Reporting ## Test and go live Before going live with your integration, use our [test card numbers](/development-resources/test-cards-and-credentials/test-card-numbers/) to test that you make a successful payment that includes a surcharge. ## See also * [API only integration guide](/online-payments/build-your-integration/advanced-flow/?platform=Web\&integration=API%20only\&version=71) * [Surcharge compliance guide](/development-resources/surcharge-compliance/) * [Surcharge with in-person payments](/point-of-sale/surcharge)