Setting up installments for a bank to handle the payment plan

Background
Before starting this tutorial, make sure you understand the following topics from the Quick start section:

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.

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 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 payment plan, follow these steps:

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

    You could instead configure 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 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.
      • 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.

  3. 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.

  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 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 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. 

    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
  	}
}'

    📘

    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.


  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. {
  "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

Updated 9 days ago