# TWINT for Unified Payments API
To accept TWINT payments, you must follow these steps:
1. [Request a payment](#Request_a_payment).
2. [Redirect the customer](#Redirect_the_customer).
* If you are using a manual capture payment, you must also [capture the payment](#Manually_capture_the_payment).
## Request a payment
To send a payment request, call the [Request a payment](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout) 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](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).
**Production**
`POST` `https://{prefix}.api.checkout.com/payments`
**Sandbox**
`POST` `https://{prefix}.api.sandbox.checkout.com/payments`
### Request example
```json
{
"source": {
"type": "twint"
},
"amount": 6540,
"currency": "CHF",
"reference": "ORD-5023-4E89",
"capture": true,
"success_url": "https://example.com/payments/success",
"failure_url": "https://example.com/payments/failure",
"processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq"
}
```
### Response example
If you receive a `202 Accepted` response with a payment `id` value and the `status` field set to `Pending`, your request was successful.
```json
{
"id": "pay_zsoov3umgscetdq66zkrxfijpu",
"status": "Pending",
"reference": "ORD-5023-4E89",
"payment_type": "Regular",
"_links": {
"self": {
"href": "https://gwc.ckotech.co/payments/pay_zsoov3umgscetdq66zkrxfijpu"
},
"redirect": {
"href": "https://pay-pat.twint.ch/static-page/?orderUUID=712f8d2d-3e54-4ed9-bd0e-52a4b7941e79&type=PAYMENT&jwt=eyJ4NXQiOiJqUXNnUlJFUGtuMlEtdWRHXzk2OVVUOUQyWG8iLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiI3ZmE1Yjg5Yi0yYzc5LTQyYzgtODA4OS1iYTg3YzliYWMxOGMiLCJqdGkiOiJrc3R4UlloMnZ0SEJnQmlNVmhPOWpRIiwiZXhwIjoxNzM3MTMwNzQ4LCJpYXQiOjE3MzcxMjk4NDgsIm5iZiI6MTczNzEyOTc4OCwic3ViIjoiUFNQLWNoZWNrb3V0IiwiT3JkZXJVVUlEIjoiNzEyZjhkMmQtM2U1NC00ZWQ5LWJkMGUtNTJhNGI3OTQxZTc5In0.k2YJFMgC2Jpq4F0foKKwhFJIi0RWhRPjI35gIiQfCA-IP_jyqtUR0M4NEWhAl6pUy7nP17iksPrhl4OucLmHTU5mZpQb4UrMBgrObP5TpT-zfiExtnnY-yMDCUstjUL93YmDgPaPt7qInfFHE-EKvO8MApJJSLykMdtnS5hAJ1UEY8D7ensDYVrP8DaNuYL-B8OX1iujVCVKVZHaH8nUvs-sqp3C31Ve-Rbr9Q4n2yWCPil7-0S5RUuNlhqtrNH0WHEl4A6yxJ5A5U8qLQ_7jv3URcXo_C3UvrJq5__d8XPhU_l4o1AGTGCmHL7FmRGDtRPXeNe18UguAtQUc0tJmw&redirectURL=https://gwc.ckotech.co/apms/twint/redirect/tok_YTZmNjg3MWMtZTgzZC00NTFiLWFkMDEtYjRhYTliYjViYzU5"
}
}
}
```
---
## Redirect the customer
The redirection step varies depending on whether you request the payment from:
- A desktop browser
- A mobile browser
### Desktop
1. Ensure that the TWINT App is installed on your customer's phone.
2. Redirect your customer to the `_links.redirect.href` URL provided in the response.
The URL displays a QR code.
3. Your customer must scan the code using their TWINT app and confirm the payment on their device.
4. 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.
### Mobile
To request a payment from a mobile browser:
1. Ensure that the TWINT app is installed on your customer's phone.
2. Redirect your customer to the `_links.redirect.href` URL provided in the response.
The URL displays the various TWINT apps that your customer can choose from.
3. The chosen TWINT app opens on your customer's device for them to authorize the payment.
4. After authorizing the payment, they are redirected to either your success or failure URL.
---
## Manually capture the payment
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](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes).
---
## Get details about a payment
To retrieve details about the payment, call the [Get payment details](https://api-reference.checkout.com/tag/Payments/#operation/getPaymentsList) endpoint, setting the `payment_id` value from the payment response as the `{id}` path parameter:
**Production**
`GET` `https://{prefix}.api.checkout.com/payments/{id}`
**Sandbox**
`GET` `https://{prefix}.api.sandbox.checkout.com/payments/{id}`
See [Get payment details](https://www.checkout.com/docs/payments/manage-payments/get-payment-details) for more information.
---
## Refund a payment
TWINT supports both partial and full refunds.
You can refund the payment in the [Dashboard](https://dashboard.checkout.com) or by calling the [Refund a payment](https://api-reference.checkout.com/tag/Payments/#operation/refundAPayment) endpoint, setting the `payment_id` value from the payment response as the `{id}` path parameter:
**Production**
`POST` `https://{prefix}.api.checkout.com/payments/{id}/refunds`
**Sandbox**
`POST` `https://{prefix}.api.sandbox.checkout.com/payments/{id}/refunds`
TWINT recommends that you also provide the original payment's reference ID:
### Request example
```json
{
"amount": 20,
"reference": "ORD-5023-4E89"
}
```
### Response example
```json
{
"action_id": "act_c4x2vjvnx4uelb4io72fa4e57a",
"_links": {
"payment": {
"href": "https://{prefix}.api.checkout.com/payments/pay_fzzdurog3squjj2ityho7x3o64"
}
}
}
```
---
## Void a payment
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](https://www.checkout.com/docs/payments/manage-payments/void-a-payment) for more information.
---
## Test TWINT
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.
### Install the TWINT test app
1. On your test device, download the TWINT Configurator app:
* iOS – [TWINT Configurator for iOS](https://dashboard.appelium.com/twint/app-distributions/configurator)
* Android – [TWINT Configurator for Android](https://dashboard.appelium.com/twint/app-distributions/configurator-android)
2. When the download page opens, select _Install_. On Android, if prompted, select _Download anyway_ and then install the app from your downloads.
3. 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_.
4. Open the TWINT Configurator app, select _Environment_, and then select _PAT_ or _INT_, depending on your test environment.
5. Select _Wallet_, select the latest version, and then select the latest build.
6. 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.
### Register the TWINT test app
1. Open the TWINT test app and select _Continue with prepaid app_.
2. Enter your Swiss mobile phone number.
3. Enter the five-digit code you receive by text message.
4. If this is your first installation, select _Onboarding_. Otherwise, select _Log in_.
5. Complete the registration steps in the app. For step 1 of 7, you can photograph any item as identification.
### Add test credit
1. Open the TWINT test app and select _Credit code_.
2. Enter your voucher code, or scan the voucher QR code.
A green screen with _Credit successful_ confirms the credit is in your account.
### Test a payment
1. [Request a payment](#Request_a_payment) in your sandbox environment.
2. [Redirect your customer](#Redirect_the_customer) to the `_links.redirect.href` URL, and then scan the QR code or select the TWINT test app.
3. Confirm the payment in the TWINT test app.
4. Check that you're redirected to your success URL and that you receive a Payment captured webhook.