TWINT is a popular mobile wallet supported by the main banks in Switzerland. Users can link their bank account or debit/credit cards with the TWINT app and pay at participating online and offline merchants.

Payment Method Properties

Make a TWINT Payment

One-time TWINT payments follow our standard redirect payment flow, so you can add TWINT to your integration in seconds.

To make a TWINT payment, you'll need to provide the following data at minimum when calling our /v1/payment-charges API:

Request

POST /v1/payment-charges

{
    "paymentMethod": "TWINT",
    "amount": {
        "value": 1000,
        "currency": "CHF"
    },
    "consumer": {
        "name": "John Smith",
        "country": "DE"
    },
    "authenticationSettings": [
        {
            "type": "REDIRECT",
            "settings": {
                "returnUrl": "https://www.your-merchant-success-page.com/"
            }
        }
    ],
    "merchantPaymentChargeReference": "YOURPAYMENTREFERENCEHERE",
}

Response

You'll receive one of our standard payment charge responses (see potential responses in the API Reference)

{
  "id": "charge_X0O78tadFHrZCbGhkycPk",
  "status": "AUTHENTICATION_PENDING",
  
  // ...
  
  "authenticationMethods": [
    {
      "type": "REDIRECT",
      "details": {
        "requestUrl": "https://twint-page.com",
        "requestMethod": "GET"
      }
    }
  ]
}

Consumer Authentication

TWINT requires a consumer authentication step before the payment is authorized and captured.

In your response to your charge creation request, you will receive the authenticationMethods list with an authentication method of standard type REDIRECT

Redirect the consumer to the page url specified in the requestUrl field. The consumer will use the token from that page to navigate to their TWINT app and confirm the payment.

The payment charge will remain in the AUTHENTICATION_PENDING state until the consumer confirms the payment in their app. After this, the charge will transition to the CAPTURED state.

Handling the Payment Result

The consumer will be redirected to the authenticationMethods.settings.returnUrl provided in the initial payment charge creation request, depending on whether the authorization is a success, a failure, or if the user cancelled/aborted the flow.

If the consumer fails to authenticate the payment within the timeout window, the charge will transition to the DISCARDED state.

You can receive webhooks for all changes to the payment charge state and use these to build business logic such as delivering the goods when the charge is CAPTURED.

Recurring Payments

TWINT offers recurring payment support - we simplify this flow for you with our Payment Agreements API.

Create the Payment Agreement

To set up a recurring agreement for SEPA DD, you'll need to provide at minimum the following data when calling our /v1/payment-agreements API:

You can also include the initialPaymentCharge object in this agreement creation call to immediately initiate the first payment without making a separate call. If you include this object, you'll need to specify:

• The exact amount.value and amount.currency of the first payment

If you don't include an initialPaymentCharge during agreement creation, you'll need to make a separate API call to /v1/payment-agreements/{agreement_id}/payment-charges to create the first charge.

Request

{
    "paymentMethod": "TWINT",
    "startDate": "2023-03-26T20:24:27Z",
    "consumer": {
        "name": "John Smith",
        "country": "DE"
    },
    "authenticationSettings": [
        {
            "type": "REDIRECT",
            "settings": {
                "returnUrl": "https://www.your-merchant-success-page.com/"
            }
        }
    ],
    "initialPaymentCharge": {
        "amount": {
            "value": 1000,
            "currency": "CHF",
            "merchantPaymentChargeReference": "YOURREFERENCEHERE"
        }
    }
}

Response

You'll receive one of our standard payment agreement responses (see responses in the API Reference)

{
  "id": "agrmt_X0O78tadFHrZCbGhkycPk",
  "status": "AUTHENTICATION_PENDING",
  "startDate": "2023-03-26T20:24:27Z",
  "initialPaymentChargeId": "charge_X0O78tadFHrZCasfhkycPk",

  "authenticationMethods": [
    {
      "type": "REDIRECT",
      "details": {
        "requestUrl": "https://twint-page.com",
        "requestMethod": "GET"
      }
    }
  ]
}

Redirect the consumer to url specified in requestUrl. They will navigate from the hosted page to their TWINT app and either confirm just the recurring token creation, or both the recurring token creation and the initial payment if initialPaymentCharge was included.

Once the consumer has confirmed the recurring agreement creation, the agreement status will transition to ACTIVE, and subsequent payments can be made without consumer interaction.

Make Subsequent Recurring Charges

Once you've set up a payment agreement once, it's simple to create subsequent charges against it. In your /v1/payment-agreements/{agreement-id}/payment-charges/ request, you just need to include:

{  
    "amount": {  
        "amount": 9000,  
        "currency": "EUR"  
    },  
    "paymentChargeMerchantReference": "external-identifier", //optional  
		"autoCapture": true  
}

You will receive webhooks for all charges created under a Payment Agreement the same way you would for individual charges, and can respond accordingly.