Setting up installments for a bank to handle the subscription

Subscriptions can have transactions that are run by the bank when the customer pays with a card. The bank fully funds the merchant up front for the entire subscription amount and handles billing the customer. This seems like a short-term subscription from the customer point of view. For general information about subscriptions, see Getting started with subscriptions.

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

Nexio's Payment service 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 - 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 for more information about possible options for your situation.
KICC (via Switch) - period can be 2-12. The amount must be at least 50000 and the currency must be KRW.
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.
PayU Colombia/LATAM (via PaymentsOS) - period can be 1-36. The amount must be at least 300 and the currency must be COP.

To create this type of subscription, follow these steps:

If desired for tracking payments and errors, you can optionally register a webhook for TRANSACTIONS.

You could instead configure legacy webhooks.
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 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.
  - KICC (via Switch) - period can be 2-12. The amount must be at least 50000 and the currency must be KRW.
  - 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.
  - PayU Colombia/LATAM (via PaymentsOS) - period can be 1-36. The amount must be at least 300 and the currency must be COP.
Complete all the steps in Creating a save card page with the iframe or 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 or to Save the card token 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 request.
As part of a checkout page for a subscription item (for more information about doing this, see either Creating a card checkout page with your own form or 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 subscription with a saved card token that runs only 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.
```
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"
  	},
  	"tokenex": {
    	"token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  	},
  	"installment": {
    	"period": 12
  	}
}'
```
📘
Note
If the initial transaction is declined, the subscription will not be created. It must be re-created with a new card token or payment method.

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

{
  "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": "[email protected]",
      "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