# 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" : "abc.com/1234",
  "failure_url" : "abc.com/2345",
  "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": "example_reference",
  "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. <br>
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. <br>
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 your on-boarding, or after going live by contacting 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:

**Live**

`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:

**Live**

`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.