TWINT supports recurring payments, and we streamline this process for you with our payment agreements API.

Create the payment agreement

To create a TWINT payment agreement, provide the following information when calling our /v1/payment-agreements API:

Data Field	Required	Description
paymentMethod	M	`TWINT`
consumer.name	M	Full name of the consumer.
consumer.country	M	The country from which the consumer is shopping.
authenticationSettings.type	M	Supply settings for the support authentication flows:`REDIRECT`

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

POST /v1/payment-agreements

{
  "paymentMethod": "TWINT",
  "consumer": {
    "name": "John Smith",
    "country": "CH"
  },
  "authenticationSettings": [
    {
      "type": "REDIRECT",
      "settings": {
        "returnUrl": "https://www.webshop.com/order-results-page"
      }
    }
  ]
}

{
  "paymentMethod": "TWINT",
  "consumer": {
    "name": "John Smith",
    "country": "CH"
  },
  "authenticationSettings": [
    {
      "type": "REDIRECT",
      "settings": {
        "returnUrl": "https://www.webshop.com/order-results-page"
      }
    }
  ],
  "initialPaymentCharge": {
    "amount": {
      "value": 1000,
      "currency": "CHF"
    }
  }
}

Response

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

{
  "id": "agr_gFCDp991mUCjWVypLEvfZ",
  "status": "AUTHENTICATION_PENDING",
  "paymentMethod": "TWINT",
  "startDate": "2025-04-10T13:31:39.222Z",
  "instrumentId": "instr_hLOqf7bZvyo98kqT4Spio",
  "consumer": {
    "name": "John Smith",
    "country": "CH"
  },
  "authenticationMethods": [
    {
      "details": {
        "requestUrl": "https://redirection-target.ppro.com",
        "requestMethod": "GET"
      },
      "type": "REDIRECT"
    }
  ],
  "history": [
    {
      "id": "ahist_8WvsAUIuUR9lYCajdkPsv",
      "status": "AUTHENTICATION_PENDING",
      "createdAt": "2025-04-10T13:31:39.222Z"
    }
  ],
  "initialPaymentChargeId": "charge_QQu5vY0HQYKIvsa7OO6Hx",
  "createdAt": "2025-04-10T13:31:39.222Z",
  "updatedAt": "2025-04-10T13:31:39.222Z"
}

{
  "id": "agr_gFCDp991mUCjWVypLEvfZ",
  "status": "AUTHENTICATION_PENDING",
  "paymentMethod": "TWINT",
  "instrumentId": "instr_hLOqf7bZvyo98kqT4Spio",
  "consumer": {
    "name": "John Smith",
    "country": "CH"
  },
  "authenticationMethods": [
    {
      "details": {
        "requestUrl": "https://redirection-target.ppro.com",
        "requestMethod": "GET"
      },
      "type": "REDIRECT"
    }
  ],
  "history": [
    {
      "id": "ahist_8WvsAUIuUR9lYCajdkPsv",
      "status": "AUTHENTICATION_PENDING",
      "createdAt": "2025-04-10T13:31:39.222Z"
    }
  ],
  "initialPaymentChargeId": "charge_QQu5vY0HQYKIvsa7OO6Hx",
  "createdAt": "2025-04-10T13:31:39.222Z",
  "updatedAt": "2025-04-10T13:31:39.222Z"
}

Pick the desired authentication method

REDIRECT

Redirect your consumer to the returned $.authenticationMethods[?(@.type == "REDIRECT")].details.requestUrl.
For example, with the value of https://redirection-target.ppro.com/ using the returned $.authenticationMethods[?(@.type == "REDIRECT")].details.requestMethod HTTP method.
The consumer will finalize the agreement and/or the payment process on the redirected page.

Handling the result

REDIRECT

Once the consumer has confirmed the agreement and/or payment, they are redirected to the returnUrl provided in the payment agreement creation request.
After the consumer is redirected back to your site, check the agreement and/or payment status and use the Status that you received to display the outcome to the consumer.
GET /v1/payment-agreements/{agreement-id}
GET /v1/payment-charges/{paymentChargeId}
Webhooks are also sent to inform you of the agreement and/or payment outcome. If the shopper closes the browser and doesn't return to your website, you can rely on webhooks to receive the result.
Store the Payment Agreement ID for subsequent payments.

Create a recurring payment

To initiate a subsequent recurring payment, send a request against an active agreement /v1/payment-agreements/{agreement-id}/payment-charges

Request

POST /v1/payment-agreements/{agreement-id}/payment-charges

{
  "amount": {
    "value": 1000,
    "currency": "CHF"
  }
}

Response

{
    "id": "charge_WLnk5R2RKwzAinkEoAMm0",
    "paymentMethod": "TWINT",
    "currency": "CHF",
    "country": "CH",
    "instrumentId": "instr_86xMmxSjrVafelQgtAXxr",
    "status": "CAPTURED",
    "consumer": {
        "name": "John Smith",
        "country": "CH"
    },
    "authorizations": [
        {
            "id": "authz_nx4VgDiibOTPoYgXxQbrL",
            "amount": 1000,
            "status": "AUTHORIZED",
            "createdAt": "2025-04-10T16:28:40.150Z",
            "updatedAt": "2025-04-10T16:28:40.150Z"
        }
    ],
    "captures": [
        {
            "id": "capture_aJh1kGwLdwK8S3aFCeWFV",
            "amount": 1000,
            "status": "CAPTURED",
            "createdAt": "2025-04-10T16:28:40.150Z",
            "updatedAt": "2025-04-10T16:28:40.150Z"
        }
    ],
    "refunds": [],
    "voids": [],
    "createdAt": "2025-04-10T16:28:38.716Z",
    "updatedAt": "2025-04-10T16:28:40.150Z"
}