Payment-method icon

TWINT for API only

Add TWINT to your API-only integration.

You can add TWINT to your existing integration. The following instructions show only what you must add to your integration specifically for TWINT.

If an instruction on this page corresponds with a step in the main integration guide, it includes a link to that corresponding step of the main integration guide.

Requirements

Requirement Description
Integration type Make sure that you have an existing API-only integration.
Redirect handling Make sure that your existing integration is set up to handle the redirect.
action.type: redirect.
Setup steps Before you begin, add TWINT in your Customer Area.

How it works

  1. The shopper selects TWINT as the payment method.
  2. The shopper enters their details in the payment form that you build.
  3. The shopper is redirected to a TWINT hosted payment page
  4. The shopper authorizes the payment in the TWINT app.

Build your payment form

Include TWINT in the list of available payment methods. You do not need to collect any information from the shopper in your payment form.

You can download the logo for TWINT to use in your form.

Get TWINT as an available payment method

When you make the /paymentMethods to get available payment methods, specify the following so that TWINT is included in the response.

Parameter Values
countryCode CH
amount.currency CHF

Add additional parameters to your /payments request

You do not need to add any additional parameters when you make a payment.

Capture the payment

By default, TWINT payments are captured automatically. This means that the Capture Delay setting in your Customer Area is set to Immediate or 1–7 days.

In case Capture Delay is set to Manual, then you need to manually capture the payment. The authorization for TWINT payments expires after 7 days, so make sure you capture the payment before then.

Partial capture

TWINT supports partial capture, but not multiple partial captures. To partially capture a TWINT payment, specify in your  /payments/{paymentPspReference}/captures request:

  • modificationAmount: The amount that the shopper should pay.

The following example shows how to make a partial capture request:

Any unclaimed amount that is left over after partially capturing a payment is automatically cancelled.

Recurring payments

To make recurring payments for TWINT, you need to:

  1. Create a shopper token.
  2. Use the token to make future payments for the shopper.

Create a token

To create a token, include in your /payments request:

  • storePaymentMethod: true
  • shopperReference: Your unique identifier for the shopper (minimum length three characters).

When the payment details have been stored, you receive a recurring.token.created webhook containing:

  • type: recurring.token.created
  • shopperReference: your unique identifier for the shopper.
  • eventId: the pspReference of the initial payment.
  • storedPaymentMethodId: the token that you need to make recurring payments for this shopper.

Make sure that your server is able to receive the Recurring tokens life cycle events webhook. You can set up this webhook in your Customer Area.

Make a payment with a token

To make a payment with the token, include in your /payments request:

  • paymentMethod.storedPaymentMethodId: The storedPaymentMethodId from the recurring.token.created webhook.

    You can also get this value using the /listRecurringDetails endpoint.

  • shopperReference: The unique shopper identifier that you specified when creating the token (minimum length three characters).

  • shopperInteraction: ContAuth.

  • recurringProcessingModel: Subscription or UnscheduledCardOnFile.

For more information about the shopperInteraction and recurringProcessingModel fields, refer to Tokenization.

Test and go live

Check the status of TWINT test payments in your Customer Area > Transactions > Payments.

Before you can accept live TWINT payments, you need to submit a request for TWINT in your live Customer Area.

See also