> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anglpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Issuer installments

> Ask the card issuer to split a single card payment into installments, such as interest-free installments in Mexico (MSI).

With issuer installments, you take a single card payment and the card issuer splits it into installments for the
buyer. The buyer repays the issuer over time. An example is interest-free installments in Mexico, known as meses sin
intereses (MSI).

> [!NOTE]
>
> This isn't the same as an installment series that you charge yourself, where each installment is a separate
> merchant-initiated transaction. For that, see the [installments](https://docs.anglpay.com/guides/features/recurring-payments/scenarios.md#installments)
> recurring payment scenario.

## Request installments

Set `installment_count` to the number of installments when you [create a transaction](https://docs.anglpay.com/reference/transactions/new-transaction.md).
The value can be from 1 to 100 and has no default.

```http theme={"system"}
POST /transactions
```

```json theme={"system"}
{
  "amount": 120000,
  "currency": "MXN",
  "country": "MX",
  "intent": "capture",
  "installment_count": 6,
  "payment_method": {
    "method": "checkout-session",
    "id": "[checkout-session-id]"
  }
}
```

Gr4vy treats any value as a request for installments, including `1`. It doesn't check the country, currency, or amount
against the plans your payment service offers. Gr4vy stores `installment_count` on the transaction and returns it in the
transaction response. The response doesn't include plan details or the number of installments the issuer approved.

Installments work with Apple Pay and Google Pay on the supporting connectors, and 3-D Secure runs as usual.

### Payment source

The payment is a customer-initiated payment, so set `payment_source` to `ecommerce` or `card_on_file`. Don't set it to
`installment` or `recurring`, which mark a series of payments that you charge yourself. Don't combine the two kinds of
installments. On some connectors, such as [Unlimit](https://docs.anglpay.com/connections/payments/unlimit-card.md#installments), a payment with
`payment_source` set to `installment` or `recurring` is sent without the plan. The buyer is then charged the full
amount at once.

### Stored cards

You can request installments on a card the buyer stored earlier. Send the stored payment method's ID with
`installment_count`, as a customer-initiated payment with `merchant_initiated` set to `false`.

## Routing

Gr4vy only sends a transaction with `installment_count` to connections that support installments. This applies to
Flow rules, the default connection, retries, and a transaction that sets `payment_service_id`. It also applies to every
payment method, not only cards.

If no active connection supports installments, the request fails with a `400` response and the message
`There is no active payment service for this transaction.` No transaction is created. See
[no active payment service](https://docs.anglpay.com/guides/api/errors.md#no-active-payment-service).

## Eligibility

Gr4vy doesn't check whether a card is eligible for the plan you request. It doesn't check the number of installments,
the issuer, or whether the card is a credit or debit card. Gr4vy also has no API to look up the plans available for a
card.

The issuer and your payment service decide at payment time. Depending on the payment service, a plan that isn't
eligible comes back as a declined transaction or as a failed one. See [connector behavior](#connector-behavior). Agree
the plans you offer, and which cards qualify, with your payment service.

### Choose which plans to offer

To decide which plans to show a buyer, keep your own table of the plans your payment service offers, for example by
issuer and number of installments. [Get card details](https://docs.anglpay.com/reference/card-details/get-card-details.md) returns the card's
`card_type` (such as `credit` or `debit`), `scheme`, and `country` for a BIN or a stored `payment_method_id`. Use it to
rule out cards before you show a plan. It doesn't return the issuing bank.

## Embed, mobile SDKs, and payment links

Embed, the mobile SDKs, and the payment link page don't show the buyer a plan picker. You choose the number of
installments yourself and set it in code:

* **Embed** - Set the [`installmentCount`](https://docs.anglpay.com/guides/payments/embed/options) option.
* **Mobile SDKs** - Set the `installmentCount` option for [iOS](https://docs.anglpay.com/guides/payments/ios/options.md),
  [Android](https://docs.anglpay.com/guides/payments/android/options.md), or [React Native](https://docs.anglpay.com/guides/payments/react-native/options.md).
* **Payment links** - Set `installment_count` when you
  [create the payment link](https://docs.anglpay.com/guides/features/payment-links/overview.md).

Embed, and the payment link page that uses it, send the number of installments with whichever payment method the buyer
picks. If the buyer picks a payment method that no installments connection supports, such as a wallet or bank payment,
the transaction can't be created. Only set `installmentCount`, or `installment_count` on a payment link, when every
payment option the buyer sees routes to a connection that supports installments.

When the buyer pays with a stored card, Embed sends `payment_source` as `card_on_file` and `is_subsequent_payment` as
`true`.

## Connector behavior

Each connector sends the number of installments to the payment service in its own format. Some also change how they
process the payment:

* **Fiserv** captures the payment straight away, even when `intent` is `authorize`. Set `intent` to `capture`. See
  [Fiserv installments](https://docs.anglpay.com/connections/payments/fiserv-card.md#installments) for capture, void, and refund.
* **Unlimit** only runs these payments as a one-step payment, so set `intent` to `capture`. See
  [Unlimit installments](https://docs.anglpay.com/connections/payments/unlimit-card.md#installments).
* **dLocal** fails the transaction when it doesn't accept the number of installments, rather than declining it. See
  [dLocal installments](https://docs.anglpay.com/connections/payments/dlocal-card.md#installments).

The following connectors support issuer installments. Each entry links to that connector's installments section.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.