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