Installment options

Offer installments through Checkout Link or Payment Link by adding installmentOptions to your payment request. Checkout displays the number of installments on the payment page and sends the installment configuration to the payment gateway for processing.

Availability depends on your merchant account, the selected payment method, and your processor. Confirm that your integration supports the intended installment arrangement before offering it to customers.

Configure installments

Include installmentOptions at the top level of the request, alongside fields such as storeId and transactionAmount.

ParameterJSON valueDescription
installmentOptionsObjectConfigures the installment arrangement. Include this object when requesting an installment payment.
installmentOptions.numberOfInstallments"5" — string in the exampleNumber of installments displayed on the payment page. Use a count supported by your account and processor, and the value type specified by your API version.
installmentOptions.allowCardHolderChooseInstallmentstrue or false — booleanIndicates whether the cardholder can choose the number of installments. Check the supported selection rules for your integration.

Update an existing integration

Use the top-level installmentOptions object for new requests and when updating your integration:

  • Move installment configuration from the legacy order.installmentOptions location to the request root.
  • Omit the deprecated allowInstallments flag. Configure installments through installmentOptions.

If your integration currently uses the legacy fields, check the compatibility policy for your API version before changing requests.

Create a Checkout session

Send your usual Checkout creation request with the top-level installment configuration. This example uses a card SALE transaction with five installments and cardholder choice enabled.

Replace YOUR_STORE_ID, the merchant transaction identifier, and the callback URLs with your own values. The amount, currency, installment count, and card authentication settings are illustrative; use values supported by your integration.

{
  "storeId": "YOUR_STORE_ID",
  "merchantTransactionId": "installment-order-1001",
  "transactionType": "SALE",
  "transactionAmount": {
    "total": 100.00,
    "currency": "GBP"
  },
  "paymentMethodDetails": {
    "cards": {
      "authenticationPreferences": {
        "challengeIndicator": "01"
      }
    }
  },
  "checkoutSettings": {
    "locale": "en_GB",
    "webHooksUrl": "https://merchant.example/payments/webhook",
    "redirectBackUrls": {
      "successUrl": "https://merchant.example/payments/success?merchantTransactionId=installment-order-1001",
      "failureUrl": "https://merchant.example/payments/failure?merchantTransactionId=installment-order-1001"
    }
  },
  "installmentOptions": {
    "numberOfInstallments": "5",
    "allowCardHolderChooseInstallments": true
  }
}

For Payment Link, include the same top-level installmentOptions object in your Payment Link creation request, together with the other fields required by that API.

Checkout creation response

A successful Checkout creation request returns a session identifier and a URL for the customer to open. The following response uses illustrative identifiers:

{
  "checkout": {
    "storeId": "YOUR_STORE_ID",
    "checkoutId": "EXAMPLE_CHECKOUT_ID",
    "redirectionUrl": "https://www.checkout-lane.com/#/?checkoutId=EXAMPLE_CHECKOUT_ID"
  }
}
Response fieldDescription
checkout.storeIdStore associated with the Checkout session.
checkout.checkoutIdIdentifier of the created Checkout session.
checkout.redirectionUrlURL to use when directing the customer to Checkout.

Redirect the customer to the actual checkout.redirectionUrl returned by the API. Use the returned URL rather than constructing one from the sample hostname or session identifier.

Creating a Checkout session does not confirm payment approval. Determine the final outcome after the customer completes the payment journey.

Customer payment experience

  1. The customer opens the Checkout Link or Payment Link.
  2. The payment page displays Number of Installments from the installment configuration.
  3. The customer completes the payment, including any required 3-D Secure authentication if required per local requirement.
  4. Checkout submits the installment data to the payment gateway for processing.
  5. Your integration receives the payment outcome through its configured return and notification flows.

The allowCardHolderChooseInstallments setting indicates whether the customer may choose the installment count. The available choices and how they interact with a supplied numberOfInstallments depend on the supported selection rules for your integration.

Click to Pay

For eligible Click to Pay transactions, Checkout also forwards installment data to the authorization platform. Confirm Click to Pay installment support for your merchant account and the intended link journey with your Fiserv representative.

Forwarding installment data does not establish payment approval. Complete the customer journey and check the final transaction status.

Confirm the payment outcome

Use your configured success and failure return URLs to bring the customer back to your application. Process payment notifications and, when needed, use transaction inquiry to check the final status before fulfilling the order.

Keep the Checkout session identifier and merchant transaction identifier so you can associate the payment outcome with the original request.

For installment details in Payment Link inquiry and webhook responses, follow the response specification for your API version. The Checkout creation response above describes session creation; refer to the relevant transaction inquiry and webhook documentation for their response fields.

Troubleshooting

SymptomWhat to check
The installment count is missing from the payment page.Confirm that installmentOptions is at the request root and includes numberOfInstallments. Check that your account and selected payment method support installments.
The request fails validation.Check the current API specification for field names, value types, accepted counts, and required fields. Use the top-level object and omit the deprecated allowInstallments flag in new requests.
The installment payment fails during processing.Confirm eligibility for the merchant account, card or payment method, processor, currency, and selected installment arrangement. Inspect the final transaction status and any returned error details.
Checkout was created, but the payment is not approved.Confirm that the customer completed the payment and any required authentication. Check the notification or transaction inquiry result; the creation response confirms only that the session exists.
Cardholder selection behaves differently from expected.Check allowCardHolderChooseInstallments and the selection rules supported by your integration, including how a supplied installment count is handled.
Click to Pay installment data is missing during processing.Confirm that the request includes installmentOptions, that the customer selected Click to Pay, and that this combination is supported for your account and link journey. Provide the transaction reference when contacting support.

When requesting support, include your store ID, merchant transaction identifier, Checkout session identifier, and the relevant error or transaction status.


Did this page help you?
Want a quick overview?