Sofort payments with Sources
Warning
Stripe doesn’t recommend using the deprecated Sources API. Use the PaymentIntents and PaymentMethods APIs to integrate with Sofort. Get started accepting Sofort payments.
Note
Before you can use Sofort, you must activate it in the Dashboard. Your use of Sofort must comply with our Sofort Terms of Service.
Stripe users in Europe and the United States can use Sources—a single integration path for creating payments using any supported method—to accept Sofort payments from customers in the following countries:
- Austria
- Belgium
- Germany
- Italy
- Netherlands
- Spain
Initiating the payment process creates a Source object and redirects your customer to the Sofort web interface for authentication of their banking credentials. After completing this, your integration uses the source to make a charge request and complete the payment.
Sofort is a push-based, single-use, and asynchronous method of payment. This means your customer takes action to send the amount to you through a redirect and it typically takes 2 business days but can take up to 14 days to confirm the success or failure of a payment.
Create a Source object
A Source object is either created client-side using Stripe.js or server-side using the Source creation endpoint, with the following parameters:
| Parameter | Value |
|---|---|
type | sofort |
amount | A positive integer in the smallest currency unit representing the amount to charge the customer (for example, 1099 for a 10.99 EUR payment). |
currency | eur (Sofort must always use Euros) |
redirect[return_url] | The URL the customer should be redirected to after the authorization process. |
sofort[country] | The ISO-3166 2-letter country code of the customer’s bank. |
sofort[preferred_language] (optional) | The preferred language of the Sofort authorization page that the customer is redirected to. Supported values are: de, en, es, it, fr, nl, or pl. |
statement_descriptor (optional) | A custom statement descriptor for the payment. |
To create a source with Stripe.js, first include the library within your website and set your publishable API key. After including the library, use the following createSource method to create a source client-side:
stripe.createSource({ type: 'sofort', amount: 1099, currency: 'eur', redirect: { return_url: '__TOKEN_PLACEHOLDER_0__', }, sofort: { country: 'DE', }, }).then(function(result) { // handle result.error or result.source });
Using either method, Stripe returns a Source object containing the relevant details for the method of payment used. Information specific to Sofort is provided within the sofort subhash.
{ "id": "src_16xhynE8WzK49JbAs9M21jaR", "object": "source", "amount": 1099, "client_secret": "src_client_secret_UfwvW2WHpZ0s3QEn9g5x7waU", "created": 1445277809, "currency": "eur", "flow": "redirect", "livemode": true, "owner": {
Source creation in mobile applications
If you’re building an iOS or Android app, you can implement sources using our mobile SDKs. Refer to our sources documentation for iOS or Android to learn more.
Optional: Providing a custom statement descriptor
Sofort requires a statement descriptor before the customer is redirected to authenticate the payment. By default, your Stripe account’s statement descriptor is used (you can review this in the Dashboard). You can provide a custom descriptor by specifying statement_descriptor when creating a source. Sofort statement descriptors support a maximum of 35 characters and cannot contain the special characters /, (, ), {, or }.
stripe.createSource({ type: 'sofort', amount: 1099, currency: 'eur', statement_descriptor: 'ORDER AT11990', redirect: { return_url: '__TOKEN_PLACEHOLDER_0__', }, sofort: { country: 'DE', }, }).then(function(result) { // handle result.error or result.source });
Providing a custom statement descriptor within a subsequent charge request has no effect.
Error codes
Source creation for Sofort payments may return any of the following errors:
| Error | Description |
|---|---|
payment_method_not_available | The payment method is currently not available. You should invite your customer to fallback to another payment method to proceed. |
processing_error | An unexpected error occurred preventing us from creating the source. The source creation should be retried. |
invalid_amount | The source amount is invalid. Sofort enforces a minimum payment amount of 1 EUR. |
invalid_sofort_country | The owner’s country is not supported by Sofort. The countries supported are listed above. |
Have the customer authorize the payment
A source initially has a status of pending and can’t be used to create a charge until your customer authorizes a Sofort payment and makes the source chargeable. To allow your customer to authorize the payment, redirect them to the URL provided within the redirect[url] attribute of the Source object.
After the authorization process, your customer is redirected back to the URL provided as a value of redirect[return_url]. This happens regardless of whether authorization was successful or not. If the customer authorizes the payment, the Source object’s status updates to chargeable and it’s ready to use in a charge request. If your customer declines the payment, the status transitions to failed.
Stripe populates the redirect[return_url] with the following GET parameters when returning your customer to your website:
source: a string representing the original ID of theSourceobjectlivemode: indicates if this is a live payment, eithertrueorfalseclient_secret: used to confirm that the returning customer is the same one who triggered the creation of the source (source IDs are not considered secret)
You can include any other GET parameters you may need when specifying redirect[return_url]. Don’t use the above parameter names yourself, as these would be overridden with the values we populate.
Mobile applications
To integrate Sofort within a mobile application, provide your application URI scheme as the redirect[return_url] value. By doing so, your customers are returned to your app after completing authorization. Refer to our Sources documentation for iOS or Android to learn more.
Testing the redirect process
When creating a Source object using your test API keys, you can follow the URL returned in the redirect[url] field. This leads to a Stripe page that displays information about the API request where you can either authorize or cancel the payment. Authorizing the payment redirects you to the URL specified in redirect[return_url].
Alternatively, to accelerate testing, use the following value for owner[email], where xxx_ is any prefix of your choice (these patterns are significant only in testmode):
| Email Address | Effect |
|---|---|
xxx_chargeable@example.com | The source will be created as pending, but automatically transition to chargeable within seconds of its creation. |
Charge the Source
After the customer authenticates the payment, the status of the source transitions to chargeable and you can use it to make a charge request. This transition happens asynchronously and may occur after the customer was redirected back to your website.
Some customers using Sofort assume that the order process is complete as soon as they’ve authenticated the payment and received confirmation from their bank. Some customers may close their browser instead of following the redirect and returning to your app or website.
For these reasons you must make sure that your integration relies on webhooks to determine when the source becomes chargeable so that the charge can be created. Refer to our best practices for more details on how to best integrate payment methods using webhooks.
Webhooks
The following webhook events notify you about changes to the status of the source:
| Event | Description |
|---|---|
source.chargeable | A Source object becomes chargeable after a customer has authenticated and verified a payment. |
source.failed | A Source object failed to become chargeable as your customer declined to authenticate the payment. |
source.canceled | A Source object expired and cannot be used to create a charge. |
Make a charge request using the source
As soon as the source is chargeable, from your source.chargeable webhook handler, you can make a charge request using the source ID as the value for the source parameter to complete the payment.
Sofort Sources are single-use which can’t be used for recurring or additional payments. For recurring payments, you can use this source to create a reusable SEPA Direct Debit source.
Refer to our Sources & Customers guide for more information on how single-use Sources interact with Customers.
Confirm that the charge has succeeded
Because Sofort is an asynchronous payment method, the Charge object’s status remains in a pending state for up to 14 days from its creation (also known as the cut-off date). After the charge is confirmed—and the funds guaranteed—its status updates to succeeded. Either of the following events are sent when the status of the charge updates:
| Event | Description |
|---|---|
charge.succeeded | The charge succeeded and the payment is complete. |
charge.failed | The charge failed and the payment couldn’t be completed. |
We recommend that you rely on these webhook events to notify your customer of their payment status. Refer to our best practices for more details on how to best integrate payment methods using webhooks.
Disputed payments
The risk of fraud or unrecognized payments is low because the customer must authenticate the payment with their bank. As a result, you won’t have disputes that turn into chargebacks, with funds withdrawn from your Stripe account.
Failed charges
If a charge hasn’t been confirmed within the cut-off time, the status of the charge automatically transitions from pending to failed. Additionally, if the funds are received after the cut-off date, the customer is automatically refunded.
On average, you can expect approximately 0.2% of Sofort charges to fail. This number can vary based on your industry or customer base. Depending on your average payment amount, the type of products or service being provided, and the risk associated with your business, you might prefer to fulfill orders only after you receive the charge.succeeded webhook.
Refunds
Payments made with Sofort can only be submitted for a refund within 180 days from the date of the original charge. After 180 days, it’s no longer possible to refund the charge.
You can submit a refund against charges that are still pending and haven’t been confirmed yet. If you create a full or partial refund on a pending charge, the refund is performed only after the status of the charge transitions to succeeded. If the charge transitions to failed, full and partial refunds are marked as canceled, as the money never left the customer’s bank account.
Source expiration
A source must be used within six hours of becoming chargeable. If it’s not, its status automatically transitions to canceled and your integration receives a source.canceled webhook event. Additionally, pending sources are canceled after one hour if they aren’t used to authenticate a payment.
After a source is canceled, the customer’s authenticated payment is refunded automatically—no money is moved into your account. For this reason, make sure the order is canceled on your end and the customer is notified as soon as you receive the source.canceled event.
Testing charge success and failure
You can mimic a successful or failed charge by creating a test source with one of the following values for the owner[name] parameter. Use this source to create a test charge that either succeeds or fails.
- succeeding_charge: The charge status transitions from pending to succeeded
- failing_charge: The charge status transitions from pending to failed
When creating a test charge with this source, the status of the charge is initially set to pending before automatically transitioning. Using test sources and charges also trigger Webhook events. The charge.pending event is first triggered, followed by either the charge.succeeded or charge.failed event immediately thereafter.