Nexio's subscription service allows you to run recurring transactions as a payment plan that run for a specified amount on a predefined schedule to pay down a balance. 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, use a saved card token, and have Nexio manage sending transaction requests automatically according to a schedule.

📘

Note

After the payment plan is created, if a subsequent transaction gets declined or has an error, the system retries the transaction up to three times, one minute apart. On the third failure, the system stops trying for that installment, the payment plan remains active, and the system tries again at the next scheduled payment date. In this instance, the merchant needs to contact the customer about the missed payment. Also, if you have webhooks configured, you will receive a webhook for each of the failures.

However, with Decline recovery and when the payment plan was created with the retryOnSoftDecline parameter, instead of doing the three retries at a minute apart, the system retries according to the recommendation received from the Decline recovery system.

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:

   • The currency to use.
   • The customer reference number.
   • Which saved card token to use.
   • 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 schedule to use for transactions (for example, every month or every six weeks).
   • The initial balance for the payment plan.
   • The amount to charge for each payment and/or the total number of payments.

   Other parameters that you may want to include:

   • A payment period at a lower payment amount - with the length of time and the amount for that.
   • Whether to end the payment plan after a certain date (regardless of the total being paid) and what that date is.

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.

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, send a POST request to the Create a subscription endpoint, using the appropriate Payment Plan body parameters in the request.

   Include values for payment.tokenex.token, payment.processingOptions.paymentType, payment.data.amount (required if you don't include schedule.duration, optional otherwise), payment.data.currency, payment.data.customer.customerRef, schedule.interval, schedule.intervalCount, schedule.balance, and schedule.duration (required if you don't include payment.data.amount, optional otherwise). You can also include any other supported parameters.

   The following example creates a recurring payment plan that will run 10 transactions (once a month) to pay off $500, thus paying $50 each time.

   Subscription running every other week

   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 '{
     "payment": {
       "data": {
         "currency": "USD",
         "customer": {
           "customerRef": "RP006"
         }
       },
       "processingOptions": {
         "paymentType": "initialScheduled"
       },
       "tokenex": {
         "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
       }
     },
     "schedule": {
       "interval": "month",
       "intervalCount": 1,
       "balance": 500,
       "duration": 10
     }
   }'
   

   
   
   Subscription with initial billing period

   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 '{
     "payment": {
       "data": {
         "amount": 25,
         "currency": "USD",
         "customer": {
           "customerRef": "RP006"
         }
       },
       "processingOptions": {
         "paymentType": "initialScheduled"
       },
       "tokenex": {
         "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
       }
     },
     "schedule": {
       "interval": "month",
       "intervalCount": 1,
       "dateInitialBillingEnd": "2023-10-05",
       "initialBillingAmount": 15,
       "balance": 500
     }
   }'
   

   
   

   📘

   Note

   If the initial transaction is declined, the subscription will not be created. It must be re-created with a new card token.

   
   

5. From the response, save the id so you can track, manage, and update the subscription as needed.

   Sample response

   {
       "customerRef": "RP006",
       "active": true,
       "accountId": "846d822e-4b32-4eb5-98e7-20ab268dd6c3",
       "id": "5d5766ec-b167-441d-abb5-7c42e59f84ce",
       "payment": {
           "data": {
               "currency": "USD",
               "customer": {
                   "customerRef": "RP006"
               },
               "amount": 50
           },
           "tokenex": {
               "token": "146ae124-1022-4dad-937e-feb339f35382"
           }
       },
       "schedule": {
           "interval": "month",
           "intervalCount": 1,
           "dateInitialBillingEnd": "2023-07-03",
           "initialBillingAmount": null,
           "duration": 10,
           "balance": 450,
           "initialBalance": 500,
           "scheduleType": 20
       },
       "userName": "[user_name]",
       "dateCreated": "2023-07-03T21:28:39.198Z",
       "dateLastModified": "2023-07-03T21:28:43.169Z",
       "dateLastRun": "2023-07-03T21:28:39.197Z",
       "dateNextRun": "2023-08-03",
       "paymentResult": {
           "id": "[payment_id]",
           "merchantId": "000099",
           "transactionDate": "2023-07-03T21:28:43.122Z",
           "authCode": "[auth_code]",
           "transactionStatus": "authorized",
           "amount": 50,
           "transactionType": "sale",
           "currency": "USD",
           "gatewayResponse": {
               ...
           },
           "data": {
               "amount": 50,
               "currency": "USD",
               "settlementCurrency": "USD",
               "customer": {
                   "customerRef": "RP006"
               }
           },
           "card": {
               "cardNumber": "411111******1111",
               "expirationYear": "28",
               "expirationMonth": "12",
               "cardHolder": "John H Doe"
           },
           "kountResponse": {
               "status": "success",
               "rules": "[response]"
           },
           "token": {
               "firstSix": "411111",
               "lastFour": "1111",
               "token": "146ae124-1022-4dad-937e-feb339f35382"
           }
       },
       "lastPaymentStatus": "success",
       "lastSuccessfulPaymentDate": "2023-07-03T21:28:43.122Z"
   }
   

See also

• Recurring billing overview
• Getting started with pay plans
• Getting started with subscriptions