Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in
OverviewUpgrade your integration
Online payments
OverviewFind your use caseManaged Payments
Payment Methods
Payment interfaces
Payment scenarios
In-person payments
Beyond payments

TWINT payments

Learn how to accept TWINT, a popular payment method in Switzerland.

Caution

The content of this section refers to a Legacy product. You should use the Accept a payment guide for the most recent integration path instead. While Stripe still supports this product, this support might end if the product is deprecated.

TWINT is a single-use payment method used in Switzerland. It allows customers to authenticate and approve payments using an approved TWINT mobile app.

You get immediate notification on whether the payment succeeded or failed.

Set up Stripe
Server-side

First, you need a Stripe account. Register now.

To access the Stripe API from your application, use our official libraries:

Command Line
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Available as a gem
sudo gem install stripe
Gemfile
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Create a PaymentIntent
Server-side

A PaymentIntent is an object that represents your intent to collect a payment from a customer and tracks the payment process. To create a PaymentIntent that accepts a TWINT payment method, specify the amount to collect, chf as the currency, and twint in the payment_method_types list. If you maintain a list of payment method types that you pass when creating a PaymentIntent, add twint to it.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1000 \
  -d currency=chf \
  -d "payment_method_types[]"=twint

Retrieve the client secret

The PaymentIntent includes a client secret that the client side uses to securely complete the payment process. You can use different approaches to pass the client secret to the client side.

Retrieve the client secret from an endpoint on your server, using the browser’s fetch function. This approach is best if your client side is a single-page application, particularly one built with a modern front-end framework such as React. Create the server endpoint that serves the client secret:

main.rb
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
get '/secret' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end

And then fetch the client secret with JavaScript on the client side:

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

Collect payment method details and submit the payment
Client-side

When a customer clicks to pay with TWINT, use Stripe.js to submit the payment to Stripe. Stripe.js is the foundational JavaScript library for building payment flows. It automatically handles complexities like the redirect described below, and enables you to extend your integration to other payment methods. Include the Stripe.js script on your checkout page by adding it to the head of your HTML file.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>

Create an instance of Stripe.js with the following JavaScript on your checkout page.

client.js
// Set your publishable key. Remember to change this to your live publishable key in production!
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx'
);

When you confirm the payment, pass the client secret.

Caution

Handle the client secret carefully, because it allows access to the PaymentIntent. Don’t log it, embed it in URLs, or expose it to anyone but the customer.

Use stripe.confirmTwintPayment to handle the redirect from your page to the local payment page. You must specify the return_url, which redirects the user after they complete the payment.

The customer selects the specific payment method on the local processor’s page.

script.js
// Redirects from the client to the payment processor
stripe.confirmTwintPayment(
  '{{PAYMENT_INTENT_CLIENT_SECRET}}',
  {
    payment_method: {
      // Billing details is optional.
      billing_details: {
        name: 'Jenny Rosen',
        email: 'jenny@example.com'
      },
    },
    // Return URL where the customer should be redirected after the authorization.
    return_url: 'https://example.com/checkout/complete',
  }
).then(function(result) {
  if (result.error) {
    // Inform the customer that there was an error.
    console.log(result.error.message);
  }
});

Point return_url to a page that provides the payment status by verifying the status of the PaymentIntent. When Stripe redirects the customer to that page, we append the following URL query parameters to the return_url for use in the verification call. You can also append your own query parameters when you specify the return_url. These parameters persist through the redirect process.

ParameterDescription
payment_intentThe unique identifier for the PaymentIntent
payment_intent_client_secretThe client secret of the PaymentIntent object

Test TWINT integration

Test your TWINT integration with your test API keys by viewing the redirect page. You can test the successful payment case by authenticating the payment on the redirect page. The PaymentIntent transitions from requires_action to succeeded. To test the case where the user fails to authenticate, use your test API keys and view the redirect page. On the redirect page, click Fail test payment. The PaymentIntent transitions from requires_action to requires_payment_method.

OptionalHandle the TWINT redirect manually

We recommend relying on Stripe.js to handle TWINT redirects and payments client-side with confirmTwintPayment. Using Stripe.js allows you to extend your integration to other payment methods. However, you can also manually redirect your customers on your server by following these steps:

  1. Create and confirm a PaymentIntent with payment_method_data of type twint. By specifying payment_method_data, we create a PaymentMethod and immediately use it with this PaymentIntent.

    You must also specify the return_url, which redirects the user after they complete the payment. You can provide your own query parameters in this URL. At the end of the redirect flow, the final URL includes these parameters.

    Command Line
    cURL
    Stripe CLI
    Ruby
    Python
    PHP
    Java
    Node.js
    Go
    .NET
    No results
    curl https://api.stripe.com/v1/payment_intents \
  -u "
    sk_test_BQokikJOvBiI2HlWgH4olfQ2
    :"     \
  -d amount=1000 \
  -d currency=chf \
  -d "payment_method_types[]"=twint \
  -d confirm=true \
  -d "payment_method_data[type]"=twint \
  --data-urlencode return_url="https://example.com/checkout/complete"

    The created PaymentIntent has a status of requires_action and a next_action of type redirect_to_url.

    {
  "status": "requires_action",
  "next_action": {
    "type": "redirect_to_url",
    "redirect_to_url": {
      "url": "https://hooks.stripe.com/...",
      "return_url": "https://example.com/checkout/complete"
    }
  },
  "id": "pi_xxx",
  "object": "payment_intent",
  "amount": 1000,
  "client_secret": "pi_xxx_secret_xxx",
  "confirm": "true",
  "confirmation_method": "automatic",
  "created": 1687432192,
  "currency": "chf",
  "livemode": true,
  "charges": {
    "data": [],
    "object": "list",
    "has_more": false,
    "url": "/v1/charges?payment_intent=pi_xxx"
  },
  "payment_method_types": [
    "twint"
  ]
}

  2. Redirect the customer to the URL provided in the next_action.redirect_to_url.url property. The code example here is approximate; your web framework’s redirect method might be different.

    When the customer finishes the payment process, we redirect them to the return_url specified when you created the PaymentIntent. The URL includes payment_intent and payment_intent_client_secret URL query parameters. If you included other parameters when you specified the return_url, they’re also appended here.

    We recommend that you rely on webhooks to confirm the status of a payment.

OptionalHandle post-payment events

Stripe sends a payment_intent.succeeded event when the payment completes. Use the Dashboard, a custom webhook, or a partner solution to receive these events and run actions, like sending an order confirmation email to your customer, logging the sale in a database, or starting a shipping workflow.

Listen for these events rather than waiting on a callback from the client. On the client, the customer could close the browser window or quit the app before the callback executes, and malicious clients could manipulate the response. Setting up your integration to listen for asynchronous events also helps you accept more payment methods in the future. Learn about the differences between all supported payment methods.

  • Handle events manually in the Dashboard

    Use the Dashboard to View your test payments in the Dashboard, send email receipts, handle payouts or retry failed payments.

  • Build a custom webhook

    Build a custom webhook handler to listen for events and build custom asynchronous payment flows. Test and debug your webhook integration locally with the Stripe CLI.

  • Integrate a prebuilt app

    Handle common business events, such as automation or marketing and sales, by integrating a partner application.

Was this page helpful?
YesNo