# TWINT for Payment Setup API

To accept TWINT payments, you must:

1. Create a payment setup.
2. Confirm the payment.
3. Redirect the customer to TWINT.

---

## Create a payment setup

Call the [Create a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/createAPaymentSetup) 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/setups`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments/setups`

### Request example

```json
{
  "amount": 6540,
  "currency": "CHF",
  "reference": "ORD-5023-4E89",
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

In the request body, provide the following:

| Field | Description |
| --- | --- |
| `amount`<br>`number` | The payment amount, in the [minor currency unit](https://www.checkout.com/docs/payments/accept-payments/format-the-amount-value). <br><br>Minimum: 1 <br><br>**Required** |
| `currency`<br>`string` | Three-letter ISO 4217 [currency code](https://www.checkout.com/docs/developer-resources/codes/currency-codes.md). <br><br>Supported value: `CHF` <br><br>**Required** |
| `reference`<br>`string` | A unique reference for the payment. <br><br>Max length: 80 <br><br>**Required** |
| `settings.failure_url`<br>`string` | The URL to redirect the customer to if the payment fails. <br><br>Format: URI <br><br>Max length: 1024 <br><br>**Required** |
| `settings.success_url`<br>`string` | The URL to redirect the customer to if the payment is successful. <br><br>Format: URI <br><br>Max length: 1024 <br><br>**Required** |
| `description`<br>`string` | A description of the payment. <br><br>Max length: 100 |

### Response example

```json
{
  "id": "set_rcmepwrchqab2wsergcafvijfy",
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "amount": 6540,
  "currency": "CHF",
  "payment_type": "Regular",
  "reference": "ORD-5023-4E89",
  "description": "TWINT payment",
  "payment_methods": {
    "twint": {
      "status": "ready",
      "flags": []
    }
  },
  "available_payment_methods": [
    "twint"
  ],
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

The response returns a `payment_methods` object, which contains the payment methods enabled on your account.

When all required fields are present, the `payment_methods.twint` object shows a `ready` [status](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-using-the-payment-setup-api.md#Payment_method_status).

---

## Confirm the payment

Confirm the payment by calling the [Confirm a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/confirmAPaymentSetup) endpoint and provide:

- The payment setup `id` as the `{id}` path parameter.
- `twint` as the `{payment_method_name}` path parameter.

### Request example

**Production**

`POST` `https://{prefix}.api.checkout.com/payments/setups/{id}/confirm/twint`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments/setups/{id}/confirm/twint`

### Response example

```json
{
  "id": "pay_zsoov3umgscetdq66zkrxfijpu",
  "status": "Pending",
  "reference": "ORD-5023-4E89",
  "payment_type": "Regular",
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/payments/pay_zsoov3umgscetdq66zkrxfijpu"
    },
    "redirect": {
      "href": "https://pay.twint.ch/static-page/?orderUUID=712f8d2d-3e54-4ed9-bd0e-52a4b7941e79&type=PAYMENT"
    }
  }
}
```

---

## Redirect the customer

Redirect the customer to the `redirect.href` URL from the response. The customer completes the payment on the TWINT page and is then redirected back to your `settings.success_url` or `settings.failure_url`.

The redirection step varies depending on whether you redirect the customer from a desktop or 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 scans the code using their TWINT app and confirms the payment on their device.
4. After confirming the payment, they are redirected to either your success or failure URL.

> **Information**
>
> The QR code becomes invalid after five minutes. The payment expires if the customer does not confirm the payment within this time.

### Mobile

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 available TWINT apps.
3. The chosen TWINT app opens on the customer's device for them to authorize the payment.
4. After authorizing the payment, they are redirected to either your success or failure URL.