TWINT

Länder & Währungen

Unterstützte Länder

• Schweiz

Unterstützte Währungen

• Schweizer Franken

Integration

We offer this payment methods for the following integration modes. Learn in our dedicated guides about their individual differences:

• Hosted Checkout Page
• Server-to-server

Find a high level overview in the "Zahlungsablauf" chapter.

Add the following properties to a standard CreateHostedCheckout/CreatePayment request:

{
   "order":{
      "amountOfMoney":{
         "currencyCode":"CHF",
         "amount":1700
      },
      "redirectPaymentMethodSpecificInput":{
         "paymentProductId":5407,
         "requiresApproval":false
      }
   }
}

Zahlungsablauf

Depending on your customers' device(s) used, differences apply:

• With a desktop and a mobile device
• With a mobile device

With a desktop and a mobile device

This flow involves both your customers' mobile/tablet and desktop device interacting with each other.

1. Your customers finalise an order on their desktop device in your shop and select TWINT.
2. You send this CreateHostedCheckout/CreatePayment request to our platform.
3. You redirect your customers via the redirectUrl to our Hosted Checkout Page (For CreateHostedCheckout requests) or display a QR code/paring token on your checkout page using the merchantAction.showFormData.paymentProduct5407.qrCodeUrl / paringToken from our response (For CreatePayment requests).
4. Your customers scan the displayed QR code with their mobile/tablet device or type in the paring token code manually in their TWINT app.
5. The mobile/tablet device opens the TWINT app. Your customers confirm the payment in the app.
6. We receive the transaction result.
7. The mobile/tablet device opens the standard browser and redirects your customers to your returnURL. We redirect your customers to your returnURL on their desktop device.
8. You request the transaction result from our platform via GetHostedCheckout or receive the result via webhooks.
9. If the transaction was successful, you can deliver the goods / service.

With a mobile device

1. Your customers finalise an order in your shop and select TWINT.
2. You send this CreateHostedCheckout/CreatePayment request to our platform.
3. You redirect your customers via the redirectUrl to our Hosted Checkout Page where they click on the "Switch to app" button (For CreateHostedCheckout requests) or initiate the app switch (For CreatePaymentRequests)..
4. The mobile device opens the TWINT app. Your customers confirm the payment in the app.
5. We receive the transaction result. 
6. The app redirects your customers to your returnURL
7. You request the transaction result from our platform via GetHostedCheckout or receive the result via webhooks.
8. If the transaction was successful, you can deliver the goods / service.

Testdaten

In unseren Testszenarios finden Sie Testdaten und detaillierte Instruktionen. 

Zusätzliche Informationen

TWINT Recurring Payments (User-on-File)

TWINT Recurring Payments User-on-File (UoF) allows merchants to store your customers' TWINT identity as a token (alias), enabling you to bill them on a defined schedule without re-authentication.

This feature streamlines the checkout process for your customers and allows you to offer recurring payments, subscriptions, and instalments while keeping sensitive card data out of your scope.

To use this feature, you need to:

• Process a payment with token creation or create a standalone token for subscriptions.
• Use the token for subsequent Merchant-Initiated Transactions (MIT).

Payment with token creation

Process a payment and create a token simultaneously. 

Set order.amountOfMoney.amount < 0 and redirectPaymentMethodSpecificInput.tokenise=true in your initial payment request: 

{ 
    "order": { 
        "amountOfMoney": { 
            "amount": 100, 
            "currencyCode": "CHF" 
        } 
    }, 
    "hostedCheckoutSpecificInput": { 
        "returnUrl": "https://yourRedirectionUrl.com"
    }, 
    "redirectPaymentMethodSpecificInput": { 
        "paymentProductId": 5407, 
        "requiresApproval": true,
        "tokenize": true
    } 
}

For this scenario, there are two possible outcomes:

Your customers either:

1. Accept both the payment and the User-on-File (UoF) registration (thereby allowing the creation of the token).
2. Accept the payment but decline the UoF registration (thereby preventing the creation of the token).

In scenario 2, our platform will process the transaction but not create a token. As a result, our platform will not include the property paymentOutput.redirectPaymentMethodSpecificOutput.token in the CreatePayment request response or in GetHostedCheckout/GetPaymentDetails requests. Ensure you handle this case accordingly. 

Standalone token for subscriptions

Process a 0-amount transaction to create a token for later use only. 

Set order.amountOfMoney.amount=0 and redirectPaymentMethodSpecificInput.tokenise=true in your initial payment request: 

{ 
    "order": { 
        "amountOfMoney": { 
            "amount": 0, 
            "currencyCode": "CHF" 
        } 
    }, 
    "hostedCheckoutSpecificInput": { 
        "returnUrl": "https://yourRedirectionUrl.com"
    }, 
    "redirectPaymentMethodSpecificInput": { 
        "paymentProductId": 5407, 
        "requiresApproval": true,
        "tokenize": true
    } 
}

Token usage for subsequent Merchant-initiated transactions (MIT)

Use an existing token for processing subsequent payments according to the Card On File (COF) framework. 

{
   "order":{
      "amountOfMoney":{
         "currencyCode":"CHF",
         "amount":100
      }
   },
   "redirectPaymentMethodSpecificInput":{
      "paymentProductId":5407,
      "requiresApproval":false,
      "token":"your_TWINT_token"
   }
}

Transaction processing via Server-to-server

When processing TWINT transaction via Server-to-server, you need to implement additional mechanisms to ensure both process flows work out as intended.

Device detection

In both scenarios—desktop plus mobile, and mobile-only—you must identify the device type (desktop or mobile) that initialised the transaction. This is crucial to adapt the flow accordingly, either by

• Displaying a QR code / paring token for transactions initialised on a desktop device.
• Executing a web-to-app switch for transactions initialised on a mobile device.

Transaction initialisation on desktop device: QR code/pairing token management

For transactions involving a desktop and mobile device, you need to display both the merchantAction.showFormData.paymentProduct5407.qrCodeUrl and pairingToken from our platform's CreatePayment response:

• qrCodeUrl: A base64-encoded QR code to be displayed on your checkout page on the desktop device. Upon scanning the code with a mobile device, it opens the TWINT app.
  If you are currently creating your own QR codes, we strongly recommend changing your integration by using qrCodeUrl instead.
  
  
• pairingToken: A token value to be displayed on your checkout page on the desktop device. To continue the transaction on the mobile device, your customers must open their TWINT app on their mobile device and type in this token.

Transaction initialisation on mobile device: Web-to-app switch

For transactions involving only a mobile device, you need to execute a web-to-app switch to open the TWINT app on the mobile device. This also includes passing the pairingToken from the CreatePayment response in the web-to-app switch.
Refer to TWINT's documentation for detailed instructions.

For mobile-only process flows, make sure to implement fallback mechanisms if the TWINT app not installed on the mobile device:

• Display a clear message instructing your customers to install the app before retrying.
• Render the QR code on your checkout page to allow processing the transaction on a second mobile device with the TWINT app installed.

QR code rendering guidelines

When displaying the QR code on your checkout page, make sure to follow TWINT's guidelines:

• Set the QR code size for clarity. Scale the width of 200–300 px for desktop devices via CSS to match your checkout layout.
• Generate a new QR code for every transaction. Each QR code is unique to a transaction. Do not cache or reuse QR code images across payment sessions.
• Poll for status updates. After rendering the QR code, keep polling GetPaymentDetails to detect when the shopper completes payment in their TWINT app, then update your checkout page accordingly.

TWINT Pay Later

TWINT's portfolio includes a “Buy Now Pay Later” option, guaranteeing you receive the funds even in case of payment defaults.

As this payment option comes with an extra charge, TWINT offers two modes:

1. The merchant pays the fee: Your customers can choose between the standard "Pay now" or the "Buy Now Pay Later" in the TWINT app. For any "Buy Now Pay Later" transaction.
   This option requires updating your existing Worldline contract. Contact us to activate this option.
2. Your customer pays the fee: Your customers can choose between the standard "Pay now" or the "Buy Now Pay Later" in the TWINT app. If they choose "Buy Now Pay Later", TWINT applies an additional fee to the customers. Before confirming the transaction, this fee will be clearly presented to the customers in the TWINT app.
   
   This option leaves your existing Worldline contract unchanged. Contact TWINT to activate this option. Make sure to communicate your TWINT Terminal ID. If you do not have your TWINT Terminal ID at hand, we are happy to help you.

Refer to TWINT's official offer for further information.