How it works

sequenceDiagram
    participant Customer
    participant PG as Card form
    participant Gateway as Payment Gateway
    participant Acquirer
    participant Backend as Merchant Backend

    Note over PG,Gateway: Only when instalments are enabled on your terminal
    PG->>Gateway: Loads the session
    Gateway-->>PG: Instalment options for your terminal
    Customer->>PG: Enters the card number
    PG->>PG: Enables the selector if the card is eligible
    Customer->>PG: Picks a number of instalments and pays
    PG->>Gateway: Payment with the chosen number
    Gateway->>Acquirer: Authorization with the number of instalments
    Acquirer-->>Gateway: Approved or declined
    Gateway->>Backend: Webhook with number_of_instalments

You don't write any code for the selector: it is part of the card form.

1. Your backend creates the session as usual: an Embedded Fields session or a Hosted Payment Page. You don't add anything for instalments.
2. The card form loads the session. If instalments are enabled on your terminal, the form shows the instalment selector under the card number.
3. The selector stays disabled until the cardholder enters a card that can be paid in instalments.
4. The cardholder picks a number of instalments, or leaves it at No instalments, and pays.
5. Finrelay sends the chosen number to the acquirer with the authorization, and reports it in every webhook for the transaction.

Availability

• Enabled per terminal. Ask your account manager to enable instalments on the terminal. A terminal without instalments doesn't show the selector.
• Eligible cards only. Instalments depend on your acquirer and on the card. The selector becomes selectable only for card numbers that are set up for instalments with your acquirer; for other cards it stays disabled and the payment is taken in full.
• Acquirer support. Instalments are available on selected acquirers. Your account manager can tell you whether yours supports them.
• Card form only. The cardholder chooses the number in the card form of Embedded Fields or the Hosted Payment Page. Server-to-server requests to POST /api/transactions/authorize can't request instalments yet.

Don't set options.number_of_instalments

Setting options.number_of_instalments on a session or on a Direct API request doesn't request instalments from the acquirer. Leave it out and let the cardholder choose in the card form.

What the cardholder sees

The selector sits under the card number field.

State	What the selector shows
Form loaded, no card number yet	No instalments, disabled
Card that can't be paid in instalments	No instalments, disabled
Card that can be paid in instalments	Selectable: No instalments, then the numbers available on your terminal (currently 1 to 6)
Card number changed to an ineligible card	The choice is cleared and the selector is disabled again

No instalments is the default. If the cardholder keeps it, the payment is taken in full and no number is sent.

In Embedded Fields, the selector also appears when the cardholder pays with a saved card, using that card's eligibility.

The selector follows the language of the form:

Language	Label	Default option
English (en-US)	Instalments	No instalments
Bosnian (bs-BA)	Rate	Bez rata
Romanian (ro-RO)	Rate	Fără rate
Swedish (sv-SE)	Delbetalning	Ingen delbetalning

On the Hosted Payment Page, the English label is spelled Installments, with No Installments as the default option.

Read the chosen number of instalments

Every transaction webhook carries payload.number_of_instalments. See Transaction Processed Webhook.

Field	Type	Description
payload.number_of_instalments	integer or null	The number of instalments the cardholder chose. null when the payment was taken in full. The key is always present.

{
  "event": "transaction-svc:transaction:purchase:approved",
  "payload": {
    "id": "KlLQpgjqCmsmogHfNjuS",
    "reference": "ORDER-123456",
    "currency": "EUR",
    "amount": 60000,
    "transaction_type": "PURCHASE",
    "status": "APPROVED",
    "payment_method_type": "card",
    "payment_method_brand": "VISA",
    "number_of_instalments": 6
  }
}

The example shows only some of the payload's fields. amount is the full amount of the purchase; how it is split into instalments is between the cardholder and their bank.

Record the number with the order from the webhook. Don't rely on what the browser reports after the payment.