TWINT

Countries & currencies

Supported countries

• Switzerland

Supported currencies

• Swiss franc (CHF)

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 "Process flows" chapter.

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

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

Process flows

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 request to our platform.
3. You redirect your customers on their desktop device via the redirectUrl   to our Hosted Checkout Page.
4. Your customers scan the displayed QR code with their mobile/tablet device or type in displayed the 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 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.
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.

Testing

Refer to our Test cases for test data and detailed instructions.

Additional information

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"
   }
}