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
Setinstallment_count to the number of installments when you create a transaction.
The value can be from 1 to 100 and has no default.
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 setpayment_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 withinstallment_count, as a customer-initiated payment with merchant_initiated set to false.
Routing
Gr4vy only sends a transaction withinstallment_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’scard_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
installmentCountoption. - Mobile SDKs - Set the
installmentCountoption for iOS, Android, or React Native. - Payment links - Set
installment_countwhen you create the payment link.
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
intentisauthorize. Setintenttocapture. See Fiserv installments for capture, void, and refund. - Unlimit only runs these payments as a one-step payment, so set
intenttocapture. See Unlimit installments. - dLocal fails the transaction when it doesn’t accept the number of installments, rather than declining it. See dLocal installments.