Sofort Drop-in integration

Our Web Drop-in renders Sofort in your payment form, and redirects the shopper to Sofort to complete the payment.

When making a Sofort payment, you additionally need to:

• Handle the redirect result after the shopper returns to your website.

Before you begin

This page explains how to add Sofort to your existing Web Drop-in integration. The Web Drop-in integration works the same way for all payment methods. If you haven't done this integration yet, refer to our Drop-in integration guide.

Before starting your Sofort integration:

1. Make sure that you have set up your back end implementation, and added Drop-in to your payments form.
2. Add Sofort in your test Customer Area.

Show Sofort in your payment form

Drop-in uses the countryCode and the amount.currency from your /paymentMethods request to show the available payment methods to your shopper.

To have Drop-in render Sofort in your payment form, specify in your request one of the following combinations of countryCode and amount.currency:

* If you want to offer Sofort in these countries, contact our Support Team.

Make a payment

When the shopper selects the Pay button, Drop-in calls the onSubmit event, which contains a state.data.

1. Pass the state.data to your server.

2. From your server, make a /payments request, specifying:

   • paymentMethod: The state.data.paymentMethod from the onSubmit event from your front end.
   • returnUrl: The URL where the shopper will be redirected back to after completing the payment. The URL should include the protocol: http:// or https://. For example, https://your-company.com/checkout/. You can also include your own additional query parameters, for example, shopper ID or order reference number.
   https://docs.adyen.com/payment-methods/sofort/web-drop-in#web-payments

   • curl
   • Ruby
   • Java
   • PHP
   • Python
   • C#
   • NodeJS

   curl Ruby Java PHP Python C# NodeJS

   curl https://checkout-test.adyen.com/v52/payments \
   -H "x-API-key: YOUR_X-API-KEY" \
   -H "content-type: application/json" \
   -d '{
     "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
     "reference":"YOUR_ORDER_NUMBER",
     "amount":{
       "currency":"EUR",
       "value":1000
     },
     "{hint:state.data.paymentMethod from onSubmit}paymentMethod{/hint}":{
       "type":"directEbanking"
     },
     "returnUrl":"https://your-company.com/checkout?shopperOrder=12xy.."
   }'

   # Set your X-API-KEY with the API key from the Customer Area.
   adyen = Adyen::Client.new
   adyen.api_key = "YOUR_X-API-KEY"
    
   response = adyen.checkout.payments({
     :amount => {
       :currency => "EUR",
       :value => 1000
     },
     :reference => "YOUR_ORDER_NUMBER",
     :paymentMethod => {
       :type => "directEbanking"
     },
     :returnUrl => "https://your-company.com/checkout?shopperOrder=12xy..",
     :merchantAccount => "YOUR_MERCHANT_ACCOUNT"
   })

   // Set YOUR_X-API-KEY with the API key from the Customer Area.
   // Change to Environment.LIVE and add the Live URL prefix when you're ready to accept live payments.
       Client client = new Client("YOUR_X-API-KEY", Environment.TEST);
       Checkout checkout = new Checkout(client);
   
       PaymentsRequest paymentsRequest = new PaymentsRequest();
   
       String merchantAccount = "YOUR_MERCHANT_ACCOUNT";
       paymentsRequest.setMerchantAccount(merchantAccount);
   
       Amount amount = new Amount();
       amount.setCurrency("EUR");
       amount.setValue(15000L);
       paymentsRequest.setAmount(amount);
   
       DefaultPaymentMethodDetails paymentMethodDetails = new DefaultPaymentMethodDetails();
       paymentMethodDetails.setType("directEbanking");
       paymentsRequest.setPaymentMethod(paymentMethodDetails);
   
       paymentsRequest.setReference("YOUR_ORDER_NUMBER");
       paymentsRequest.setReturnUrl("https://your-company.com/checkout?shopperOrder=12xy..");
   
       PaymentsResponse paymentsResponse = checkout.payments(paymentsRequest);

   // Set your X-API-KEY with the API key from the Customer Area.
   $client = new \Adyen\Client();
   $client->setXApiKey("YOUR_X-API-KEY");
   $service = new \Adyen\Service\Checkout($client);
   
   $params = array(
     "amount" => array(
       "currency" => "EUR",
       "value" => 1000
     ),
     "reference" => "YOUR_ORDER_NUMBER",
     "paymentMethod" => array(
       "type" => "directEbanking"
     ),
     "returnUrl" => "https://your-company.com/checkout?shopperOrder=12xy..",
     "merchantAccount" => "YOUR_MERCHANT_ACCOUNT"
   );
   $result = $service->payments($params);

   #Set your X-API-KEY with the API key from the Customer Area.
   adyen = Adyen.Adyen()
   adyen.client.xapikey = 'YOUR_X-API-KEY'
   
   result = adyen.checkout.payments({
      'amount': {
         'value': 1000,
         'currency': 'EUR'
      },
      'reference': 'YOUR_ORDER_NUMBER',
      'paymentMethod': {
         'type': 'directEbanking'
      },
      'returnUrl': 'https://your-company.com/checkout?shopperOrder=12xy..',
      'merchantAccount': 'YOUR_MERCHANT_ACCOUNT'
   })

   // Set your X-API-KEY with the API key from the Customer Area.
   var client = new Client ("YOUR_X-API-KEY", Environment.Test);
   var checkout = new Checkout(client);
   
   var amount = new Model.Checkout.Amount("EUR", 1000);
   var details = new Model.Checkout.DefaultPaymentMethodDetails{
     Type = "directEbanking"
   };
   var paymentRequest = new Adyen.Model.Checkout.PaymentRequest
   {
     Reference = "YOUR_ORDER_NUMBER",
     Amount = amount,
     ReturnUrl = @"https://your-company.com/checkout?shopperOrder=12xy..",
     MerchantAccount = "YOUR_MERCHANT_ACCOUNT",
     PaymentMethod = details
   };
   
   var paymentResponse = checkout.Payments(paymentsRequest);

   // Set your X-API-KEY with the API key from the Customer Area.
   const {Client, Config, CheckoutAPI} = require('@adyen/api-library');
   const config = new Config();
   // Set your X-API-KEY with the API key from the Customer Area.
   config.apiKey = '[API_KEY]';
   config.merchantAccount = '[YOUR_MERCHANT_ACCOUNT]';
   const client = new Client({ config });
   client.setEnvironment("TEST");
   const checkout = new CheckoutAPI(client);
   checkout.payments({
       amount: { currency: "EUR", value: 1000 },
       paymentMethod: {
           type: 'directEbanking'
       },
       reference: "YOUR_ORDER_NUMBER",
       merchantAccount: config.merchantAccount,
       returnUrl: "https://your-company.com/checkout?shopperOrder=12xy.."
   }).then(res => res);

   The /payments response contains:

   • action.method: GET or POST. The HTTP request method that you should use. After the shopper completes the payment, they will be redirected back to your returnURL using the same method.
     The redirect method depends on your payment method configuration and the length of the data included in the request, so make sure that your integration can handle both HTTP GET and HTTP POST methods.

   To verify the payment result, you also need the following from the /payments response:

   • action.paymentData: Store this on your server — this is the paymentData value that you send in your /payments/details request.
   • details: Array of parameters that you need to send in your /payments/details request. For example, payload or redirectResult.
     The parameters can vary based on the payment method configuration. Always check the details array for the parameters that you need to send in your next API request.
   https://docs.adyen.com/payment-methods/sofort/web-drop-in#-payments-response

   /payments response

     {
       "resultCode": "RedirectShopper",
        "action": {
          "method": "GET",
          "paymentData": "Ab02b4c0!BQABAgCSZT7t...",
          "paymentMethodType": "directEbanking",
          "type": "redirect",
          "url": "https://test.adyen.com/hpp/redirect.shtml?brandCode=.."
     },
       "details": [
         {
             "key": "payload",
             "type": "text"
         }
       ],
     ...
     }
3. Pass the action object to your front end.

Handle the redirect result

Drop-in uses dropin.handleAction(action) to redirect the shopper to Sofort. After the shopper is redirected back to your website, check the redirect result.

• From your server, make a POST /payments/details request, specifying:
  • paymentData: Value you received in the /payments response.
  • details: Object that contains the URL-decoded values of the parameters that were returned when the shopper was redirected back to your site. For example, payload. To check the parameters that you should submit, refer to the details array that you received in the /payments response.
  https://docs.adyen.com/payment-methods/paymaya/web-drop-in#-payments-details-request

  /payments/details request

  {
       "paymentData":"Ab02b4c0!BQABAgCJN1wRZuGJmq8dMncmypvknj9s7l5Tj...",
       "details":{
         "{hint:Verify the parameters from /payments response}payload{/hint}":"Ab02b4c0!BQABAgCW5sxB4e/=="
       }
  }

  You receive a response containing:
  • resultCode: Use this to present the result to your shopper.
  • pspReference: Our unique identifier for the transaction.
  https://docs.adyen.com/payment-methods/paymaya/web-drop-in#-payments-details-response

  /payments/details response

   {
     "resultCode": "Authorised",
     "pspReference": "88154795347618C"
   }

Present the payment result

Use the resultCode that you received in the /payments/details response to present the payment result to your shopper.

The resultCode values you can receive for Sofort are:

Recurring payments

We support recurring transactions for Sofort through SEPA Direct Debit. To make recurring payments, you need to:

1. Create a shopper token.
2. Use the token to make future payments for the shopper.

Create a token

To create a token, include in your /payments request:

• storePaymentMethod: true
• shopperReference: Your unique identifier for the shopper.

When the payment has been settled, you receive a webhook notification containing:

• eventCode: RECURRING_CONTRACT
• originalReference: The pspReference of the initial payment.
• pspReference: This is the token that you need to make recurring payments for this shopper.

Make a payment with a token

To make a payment with the token, include in your /payments request:

• paymentMethod.storedPaymentMethodId: The pspReference from the RECURRING_CONTRACT.

• shopperReference: The unique shopper identifier that you specified when creating the token.
• shopperInteraction: ContAuth.
• recurringProcessingModel: Subscription or UnscheduledCardOnFile.

For more information about the shopperInteraction and recurringProcessingModel fields, refer to Recurring transaction types.

curl https://checkout-test.adyen.com/v52/payments \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
       "amount":{
          "value":1000,
          "currency":"EUR"
       },
       "paymentMethod":{
          "type":"sepadirectdebit",
          "recurringDetailReference":"7219687191761347"
       },
       "reference":"YOUR_ORDER_NUMBER",
       "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
       "shopperReference":"YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j",
       "shopperInteraction":"ContAuth",
       "recurringProcessingModel": "Subscription"
}'

# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen::Client.new
adyen.api_key = "YOUR_X-API-KEY"
 
response = adyen.checkout.payments({
  :amount => {
    :currency => "EUR",
    :value => 1000
  },
  :reference => "YOUR_ORDER_NUMBER",
  :paymentMethod => {
    :type => "sepadirectdebit",
    :recurringDetailReference => "7219687191761347"
  },
  :returnUrl => "https://your-company.com/checkout?shopperOrder=12xy..",
  :shopperReference => "YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j",
  :merchantAccount => "YOUR_MERCHANT_ACCOUNT",
  :shopperInteraction => "ContAuth",
  :recurringProcessingModel => "Subscription"
})

// Set YOUR_X-API-KEY with the API key from the Customer Area.
// Change to Environment.LIVE and add the Live URL prefix when you're ready to accept live payments.
Client client = new Client("YOUR_X-API-KEY", Environment.TEST);
Checkout checkout = new Checkout(client);

PaymentsRequest paymentsRequest = new PaymentsRequest();

String merchantAccount = "YOUR_MERCHANT_ACCOUNT";
paymentsRequest.setMerchantAccount(merchantAccount);

Amount amount = new Amount();
amount.setCurrency("EUR");
amount.setValue(15000L);
paymentsRequest.setAmount(amount);

DefaultPaymentMethodDetails paymentMethodDetails = new DefaultPaymentMethodDetails();
paymentMethodDetails.setRecurringDetailReference("7219687191761347");
paymentMethodDetails.setType("sepadirectdebit");
paymentsRequest.setPaymentMethod(paymentMethodDetails);

paymentsRequest.setReference("YOUR_ORDER_NUMBER");
paymentsRequest.setReturnUrl("https://your-company.com/checkout?shopperOrder=12xy..");
paymentsRequest.setShopperInteraction("ContAuth");
paymentsRequest.setRecurringProcessingModel("Subscription");

PaymentsResponse paymentsResponse = checkout.payments(paymentsRequest);

// Set your X-API-KEY with the API key from the Customer Area.
$client = new \Adyen\Client();
$client->setXApiKey("YOUR_X-API-KEY");
$service = new \Adyen\Service\Checkout($client);

$params = array(
  "amount" => array(
    "currency" => "EUR",
    "value" => 1000
  ),
  "reference" => "YOUR_ORDER_NUMBER",
  "paymentMethod" => array(
    "type" => "sepadirectdebit",
    "recurringDetailReference" => "7219687191761347"
  ),
  "returnUrl" => "https://your-company.com/checkout?shopperOrder=12xy..",
  "shopperReference" => "YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j",
  "recurringProcessingModel" => "Subscription",
  "shopperInteraction" => "ContAuth",
  "merchantAccount" => "YOUR_MERCHANT_ACCOUNT"
);
$result = $service->payments($params);

#Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen.Adyen()
adyen.client.xapikey = 'YOUR_X-API-KEY'

result = adyen.checkout.payments({
   'amount': {
      'value': 1000,
      'currency': 'EUR'
   },
   'reference': 'YOUR_ORDER_NUMBER',
   'paymentMethod': {
      'type': 'sepadirectdebit',
      'recurringDetailReference': '7219687191761347'
   },
   'returnUrl': 'https://your-company.com/checkout?shopperOrder=12xy..',
   'shopperReference': 'YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j'
   'merchantAccount': 'YOUR_MERCHANT_ACCOUNT',
   'shopperInteraction':'ContAuth',
   'recurringProcessingModel': 'Subscription'
})

// Set your X-API-KEY with the API key from the Customer Area.
var client = new Client ("YOUR_X-API-KEY", Environment.Test);
var checkout = new Checkout(client);

var amount = new Model.Checkout.Amount("EUR", 1000);
var details = new Model.Checkout.DefaultPaymentMethodDetails{
  Type = "sepadirectdebit",
  RecurringDetailReference = "7219687191761347"
};
var paymentsRequest = new Model.Checkout.PaymentRequest
{
  Reference = "YOUR_ORDER_NUMBER",
  Amount = amount,
  ReturnUrl = @"https://your-company.com/checkout?shopperOrder=12xy..",
  MerchantAccount = "YOUR_MERCHANT_ACCOUNT",
  ShopperReference = "YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j",
  RecurringProcessingModel = "Subscription",
  ShopperInteraction = "ContAuth",
  PaymentMethod = details
};

var paymentResponse = checkout.Payments(paymentsRequest);

// Set your X-API-KEY with the API key from the Customer Area.
const {Client, Config, CheckoutAPI} = require('@adyen/api-library');
const config = new Config();
// Set your X-API-KEY with the API key from the Customer Area.
config.apiKey = '[API_KEY]';
config.merchantAccount = '[YOUR_MERCHANT_ACCOUNT]';
const client = new Client({ config });
client.setEnvironment("TEST");
const checkout = new CheckoutAPI(client);
checkout.payments({
    amount: { currency: "EUR", value: 1000 },
    paymentMethod: {
        type: 'sepadirectdebit',
        recurringDetailReference: "7219687191761347"
    },
    reference: "YOUR_ORDER_NUMBER",
    merchantAccount: config.merchantAccount,
    shopperReference: "YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j",
    returnUrl: "https://your-company.com/checkout?shopperOrder=12xy..",
    shopperInteraction: "ContAuth",
    recurringProcessingModel: "Subscription"
}).then(res => res);

Chargebacks

In extremely rare scenarios (around 0.2% of all cases), it can happen that you will not receive the funds, even after receiving a successful AUTHORISATION notification. The successful AUTHORISATION notification means that the payment has passed the verifications that Sofort runs on the shopper account, and that the bank transfer was initiated successfully. The payment could still fail at this point, for example because:  

• The shopper cancelled the transaction.  A number of German banks offer shoppers the possibility to cancel bank transfers until midnight of the day of the transaction. In Switzerland, banks are required by law to allow shoppers to reverse bank transfers for 48 hours. 
• Some banks process transactions with a delay. For example, if the shopper completes a Sofort payment on a Saturday, the bank might only process it on Monday. If the shopper has withdrawn sufficient funds in the meantime, the payment will fail. 

In case of the above scenarios, Adyen is not informed about the transaction having failed. This means that we do not know whether the transaction has failed, or whether the bank might still process it later. 

On our side, the status of the payment is SentForSettle until we receive the funds. You can check the status of the payment in your Customer Area.

If we have not received the funds after 8 business days, the status of the payment becomes Settled, then Chargeback, and you will receive a CHARGEBACK notification. In case we receive the money after this point, you will receive a CHARGEBACK_REVERSED notification. 

Test and go live

Sofort does not have a specialized test environment. This means that you are redirected to the Sofort live environment even when making a payment from the Adyen test environment.
To test your integration, use the following details: 

To check the status of a Sofort test payment, go to your Customer Area > Transactions > Payments.

See also