---
updatedAt: 2025-09-17T23:26:28.000Z
agentTools:
  projectIndex: https://docs.nexiopay.com/llms.txt
---

# Setting up installments for a bank to handle the payment plan

<Table align={["left"]}>
  <thead>
    <tr>
      <th style={{ textAlign: "left" }}>
        Background
      </th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style={{ textAlign: "left" }}>
        Before starting this tutorial, make sure you understand the following topics from the [Quick start](https://docs.nexiopay.com/docs/quick-start) section:
        <ul style={{ marginTop: "-5px", marginBottom: "-5px" }}>
          <li>[Sandbox environments](https://docs.nexiopay.com/docs/sandbox-environments) (especially about testing).</li>
          <li>[Authentication](https://docs.nexiopay.com/docs/authentication) (about authenticating using your API user and when you need a login versus a one-time-use token).</li>
        </ul>
      </td>
    </tr>
  </tbody>
</Table>

Payment plans can have transactions that are run by the bank when the customer pays with a card. The bank fully funds the merchant up front and handles billing the customer. For general information about payment plans, see [Getting started with pay plans](https://docs.nexiopay.com/docs/getting-started-with-pay-plans).

This option is for cases where you want to support a card payment for the duration of the plan, have the bank handle the schedule, and receive all the funds up front.

Nexio's [Payment service](https://docs.nexiopay.com/reference/runcardtransaction) allows you to configure card transactions to run according to an installment period, depending on the connection or gateway.

Nexio supports installments for the following gateways, with the indicated values:

* [Cybersource](https://docs.nexiopay.com/docs/cybersource-integration-guide) - `period` can be 1-100, depending on the processor being used. Accepted values may depend on the currency, country, and processor used for the transaction. Contact [Integrations Support](https://docs.nexiopay.com/page/contact-us) for more information about possible options for your situation.
* [Openpay](https://docs.nexiopay.com/docs/openpay-integration-guide) - `period` can be 3, 6, 9, 12, or 18. By default, the amount must be 300 and the currency must be MXN. The minimum amount can be changed by Openpay.

To create this type of payment plan, follow these steps:

1. If desired for tracking payments and errors, you can optionally [register a webhook](https://docs.nexiopay.com/docs/registering-webhooks) for TRANSACTIONS.

   You could instead [configure legacy webhooks](https://docs.nexiopay.com/docs/configuring-legacy-webhooks).

2. Determine which values you need to collect from the customer or retrieve from your system. The following parameters are required:

   * Either a saved card token or full card information (the full card number and expiration date).
   * The total amount.
   * The currency.
   * The payment type - The type of transaction being processed using stored payment credentials. Use this parameter to properly flag initial and subsequent transactions. For more information about this parameter and when to use each option, see the [paymentType](https://docs.nexiopay.com/docs/constant-transaction-values#payment-type-paymenttype) documentation and reference table.
   * The installment period. The valid values depend on the gateway or connection.
     * Cybersource - `period` can be 1-100. Accepted values may depend on the currency used for the transaction. Contact Cybersource for more information.
     * Openpay - `period` can be 3, 6, 9, 12, or 18. By default, the amount must be 300 and the currency must be MXN. The minimum amount can be changed by Openpay.

3. Complete all the steps in [Creating a save card page with the iframe](https://docs.nexiopay.com/docs/creating-a-save-card-page-with-the-iframe) or [Creating a save card page with your own form](https://docs.nexiopay.com/docs/creating-a-save-card-page-with-your-own-form).

   You may want to include customer information in the request to [Create one-time-use token](https://docs.nexiopay.com/reference/createonetimeusetoken) or to [Save the card token](https://docs.nexiopay.com/reference/savecardtoken) to use in running the transaction with the specified saved card token.

   If using an iframe for running the card transaction, you must also include the `installment.period` parameter as part of the request for the one-time-use token. For using your own form to run the transaction, you can include it there, or in the [Run card transaction](https://docs.nexiopay.com/reference/runcardtransaction) request.

4. As part of a checkout page for a payment plan item (for more information about doing this, see either [Creating a card checkout page with your own form](https://docs.nexiopay.com/docs/creating-a-card-checkout-page-with-your-own-form) or [Creating a card checkout page with the iframe](https://docs.nexiopay.com/docs/creating-a-card-checkout-page-with-the-iframe)), when the customer submits payment, make sure to include all required parameters.

   The following example creates a recurring payment plan with a saved card token that runs 12 transactions (once a month) to pay off $600. The payment amount per transaction is determined by dividing the amount by the installment period (thus, $50 in this example). The gateway/connection handles the schedule of billing the customer.

   ```shell Payment plan running monthly
   curl -X POST https://api.nexiopaysandbox.com/subscription/v3 \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Basic [Base64_encoded_login]' \
     -d '{
     	"data": {
       	"amount": 600,
         "currency": "USD"
     	},
     	"processingOptions": {
         "paymentType": "initialScheduled"
       },
       "tokenex": {
       	"token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
     	},
     	"installment": {
       	"period": 12
     	}
   }'
   ```

   <br />

   > 📘 Note
   >
   > If the initial transaction is declined, the payment plan will not be created. It must be re-created with a new card token or payment method.

   <br />

5. From the response, save the `id` so you can track, manage, and update the payment plan as needed. When sending the full card information, save the `recurringData.recurringId` for managing future transactions.

   1. ```json Sample response
      {
        "id": "[payment_id]",
        "merchantId": "301525",
        "transactionDate": "2023-07-31T22:24:56.641Z",
        "authCode": "[auth_code]",
        "transactionStatus": "authorized",
        "amount": 50,
        "transactionType": "sale",
        "currency": "USD",
        "gatewayResponse": {
          ...
        },
        "data": {
          "amount": 50,
          "currency": "USD",
          "settlementCurrency": "USD",
          "customer": {
            "email": "jdoe@example.com",
            "billToAddressOne": "2147 West Silverlake Drive",
            "billToCity": "Scranton",
            "billToState": "PA",
            "billToPostal": "18503",
            "billToCountry": "US"
          }
        },
        "card": {
          "cardNumber": "411111******1111",
          "expirationYear": "28",
          "expirationMonth": "12",
          "cardHolder": "John H Doe"
        },
        "installment": {
          "period": 12
        },
        "kountResponse": {
          "status": "success",
          "rules": "[response]"
        },
        "token": {
          "firstSix": "411111",
          "lastFour": "1111",
          "token": "146ae124-1022-4dad-937e-feb339f35382"
        }
      }
      ```

# See also

* [Recurring billing overview](doc:recurring-billing-overview)
* [Getting started with pay plans](doc:getting-started-with-pay-plans)
* [Getting started with subscriptions](doc:getting-started-with-subscriptions)