TWINT for Unified Payments API
Last updated: November 4, 2026
To accept TWINT payments, you must follow these steps:
- Request a payment.
- Redirect the customer.
- If you are using a manual capture payment, you must also capture the payment.
To send a payment request, call the Request a payment endpoint:
Information
Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see API endpoints.
post
https://{prefix}.api.checkout.com/payments
If you receive a 202 Accepted response with a payment id value and the status field set to Pending, your request was successful.
The redirection step varies depending on whether you request the payment from:
- A desktop browser
- A mobile browser
- Ensure that the TWINT App is installed on your customer's phone.
- Redirect your customer to the
_links.redirect.hrefURL provided in the response.
The URL displays a QR code. - Your customer must scan the code using their TWINT app and confirm the payment on their device.
- After confirming the payment, they are redirected to either your success or failure URL.
Information
The code becomes invalid after five minutes. The payment expires if the customer does not confirm the payment within this time frame.
To request a payment from a mobile browser:
- Ensure that the TWINT app is installed on your customer's phone.
- Redirect your customer to the
_links.redirect.hrefURL provided in the response.
The URL displays the various TWINT apps that your customer can choose from. - The chosen TWINT app opens on your customer's device for them to authorize the payment.
- After authorizing the payment, they are redirected to either your success or failure URL.
The manual capture flow enables you to manually trigger the capture of the authorized funds at a later time. For example, if you need to verify that the item is in stock.
TWINT only supports full captures. You must send a capture request for the full authorized amount including "capture_type": "Final".
The standard authorization validity period for TWINT is seven days. However, you can extend this period up to 30 days during setup, or after going live. To request an extension, contact your account manager or request support.
To retrieve details about the payment, call the Get payment details endpoint, setting the payment_id value from the payment response as the {id} path parameter:
get
https://{prefix}.api.checkout.com/payments/{id}
See Get payment details for more information.
TWINT supports both partial and full refunds.
You can refund the payment in the Dashboard or by calling the Refund a payment endpoint, setting the payment_id value from the payment response as the {id} path parameter:
post
https://{prefix}.api.checkout.com/payments/{id}/refunds
TWINT recommends that you also provide the original payment's reference ID:
If the customer does not complete the payment, it expires and you receive a payment_expired webhook within five minutes.
If the customer cancels their payment, you also receive a payment_expired webhook.
See Void a payment for more information.
To test TWINT payments, you need the TWINT test app instead of the production TWINT app. The production app cannot process test payments. You install the test app through the TWINT Configurator app.
You also need a Swiss mobile phone number to register the test app. Additionally, for some payment flows you must complete an account verification with TWINT and contact TWINT support to activate your test account.
- On your test device, download the TWINT Configurator app:
- iOS – TWINT Configurator for iOS
- Android – TWINT Configurator for Android
- When the download page opens, select Install. On Android, if prompted, select Download anyway and then install the app from your downloads.
- Allow the installation:
- On iOS, go to Settings > General > VPN & Device Management, select TWINT AG, and then select Trust.
- On Android, go to Settings > Security > More settings > Install apps from external sources, select Configurator, and then select Allow app installs.
- Open the TWINT Configurator app, select Environment, and then select PAT or INT, depending on your test environment.
- Select Wallet, select the latest version, and then select the latest build.
- Select Install.
Warning
Only install the TWINT test app on your test device. If both the TWINT test app and the production TWINT Prepaid app are on the same device, you can run into issues during testing.
- Open the TWINT test app and select Continue with prepaid app.
- Enter your Swiss mobile phone number.
- Enter the five-digit code you receive by text message.
- If this is your first installation, select Onboarding. Otherwise, select Log in.
- Complete the registration steps in the app. For step 1 of 7, you can photograph any item as identification.
- Open the TWINT test app and select Credit code.
- Enter your voucher code, or scan the voucher QR code.
A green screen with Credit successful confirms the credit is in your account.
- Request a payment in your sandbox environment.
- Redirect your customer to the
_links.redirect.hrefURL, and then scan the QR code or select the TWINT test app. - Confirm the payment in the TWINT test app.
- Check that you're redirected to your success URL and that you receive a Payment captured webhook.