Skip to main content
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).
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 recurring payment scenario.

Request installments

Set installment_count to the number of installments when you create a transaction. The value can be from 1 to 100 and has no default.
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, 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.

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. 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 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, 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, 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 for capture, void, and refund.
  • Unlimit only runs these payments as a one-step payment, so set intent to capture. See Unlimit installments.
  • dLocal fails the transaction when it doesn’t accept the number of installments, rather than declining it. See dLocal installments.
The following connectors support issuer installments. Each entry links to that connector’s installments section.