Creating a subscription

Nexio's subscription service allows you to run recurring transactions.
These can be in the form of basic subscriptions or pay plans.

Subscriptions set transactions to run for a specified amount on a predefined schedule.

To create a subscription, follow these steps:

1. Determine your Settings

   Determine whether to include an initial billing period and the proper subscription settings.
   (These will generally be pre-determined by the shopper's selections on your checkout page.)

2. Send a Request to Nexio

   Send a POST request to the Create a subscription endpoint. Include the billing amounts and subscription settings as determined in step 1.

   The example below will create a recurring subscription that will run a transaction for 19.99 USD every other week.

   Basic Subscription

   Shell

   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": 19.99,
         "currency": "USD",
         "customer": {
           "customerRef": "RP006"
         }
       },
       "tokenex": {
         "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
       }
     },
     "schedule": {
       "interval": "week",
       "intervalCount": 2
     }
   }'
   

   
   

   The example below will create a recurring subscription that will run a transaction once a month. The transaction amount will be 15 USD until October 5, 2021. After that, the transaction amount will be 25 USD.

   Subscription with Initial Billing Period

   Shell

   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"
         }
       },
       "tokenex": {
         "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
       }
     },
     "schedule": {
       "interval": "month",
       "intervalCount": 1,
       "dateInitialBillingEnd": "2021-10-05",
       "initialBillingAmount": 15
     }
   }'
   

   📘

   Note

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

3. Configure Webhooks (Optional)

   If desired, you may configure legacy webhooks to be sent every time a transaction is run through the
   subscription service.

   See the Legacy webhooks and event types tutorial in the Developer Tools section for step-by-step instructions on how to configure and receive webhooks.

   📘

   Note

   You will continue to receive webhooks for any previously configured transaction events.

   Example Request

   Shell

   curl -X POST https://api.nexiopaysandbox.com/webhook/v3/config \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Basic [Base64_encoded_login]'
     -d '{
     "merchantId": "100039",
     "webhooks": {
       "SUBSCRIPTION_DETAILS": {
         "url": "https://your-ecommerce-website.example.com"
       }
     }
   }'
   

1. Example Request

   Shell

   curl -X POST https://api.nexiopaysandbox.com/webhook/v3/config \
     -H 'Content-Type: application/json' \
     -H 'Accept: application/json' \
     -H 'Authorization: Basic [Base64_encoded_login]'
     -d '{
     "merchantId": "100039",
     "webhooks": {
       "SUBSCRIPTION_DETAILS": {
         "url": "https://your-ecommerce-website.example.com"
       }
     }
   }'