Creating a Nexio-scheduled card subscription

Nexio's subscription service allows you to run recurring transactions as subscriptions that run for a specified amount on a predefined schedule. For general information about subscriptions, see Getting started with subscriptions.

To create a subscription, follow these steps:

If desired, 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:
- Amount to charge for the scheduled transactions.
- The currency to use.
- The customer reference number.
- Which saved card token to use.
Other parameters that you may want to include:
- The schedule to use for transactions (for example, every month or every six weeks).
- A trial period at a lower price - with the length of time and the amount for that.
- Whether to end the subscription after a certain date and what that date is.
- Whether to end the subscription after a certain number of transactions.
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.

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

Including values for payment.tokenex.token, payment.data.amount, payment.data.currency, and payment.data.customer.customerRef. You can also include any other supported parameters.

The following example creates a recurring subscription that runs a transaction for 19.99 USD 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": {
      "amount": 19.99,
      "currency": "USD",
      "customer": {
        "customerRef": "RP006"
      }
    },
    "tokenex": {
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
    }
  },
  "schedule": {
    "interval": "week",
    "intervalCount": 2
  }
}'

The following example creates a recurring subscription that runs a transaction once a month. The transaction amount will be 15 USD until October 5, 2023. After that, the transaction amount will be 25 USD.

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": "2023-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.

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

{
    "customerRef": "987654321",
    "active": true,
    "accountId": "856g721d-4b32-4eb5-98e7-20ab268dd6c3",
    "id": "bd55c261-8abc-400b-a2fb-47122ce8636e",
    "payment": {
        "tokenex": {
            "token": "8b234b2e-b409-43d4-bdf3-db1d7398d767",
            "firstSix": "411111",
            "lastFour": "1111"
        },
        "data": {
            "currency": "USD",
            "settlementCurrency": "USD",
            "amount": 19.99,
            "customer": {
                "customerRef": "987654321"
            }
        }
    },
    "schedule": {
        "interval": "week",
        "intervalCount": 2,
        "initialBillingAmount": null,
        "balance": null,
        "initialBalance": null,
        "scheduleType": 10
    },
    "userName": "[user_name]",
    "dateCreated": "2023-06-30T22:04:01.756Z",
    "dateLastModified": "2023-06-30T22:04:11.904Z",
    "dateLastRun": "2023-06-30T22:04:01.753Z",
    "dateNextRun": "2023-07-14",
    "paymentResult": {
        "id": "eyJuYW1lIjoWJlciI6IjMxCJtZXJjaGFudElkIjoiMoiVVNEIn0=eyJuYW1lIjoib3BlbnBheSIsIm1lcmN",
        "merchantId": "000999",
        "transactionDate": "2023-06-30T22:04:11.812Z",
        "transactionStatus": "authorized",
        "amount": 19.99,
        "transactionType": "sale",
        "currency": "USD",
        "gatewayResponse": {
            ...
        },
        "data": {
            "amount": 19.99,
            "currency": "USD",
            "settlementCurrency": "USD",
            "customer": {
                "customerRef": "987654321"
            }
        },
        "card": {
            "cardNumber": "411111******1111",
            "expirationYear": "28",
            "expirationMonth": "12",
            "cardHolder": "John H Doe"
        },
        "kountResponse": {
            "status": "success",
            "rules": "[response]"
        },
        "token": {
            "firstSix": "411111",
            "lastFour": "1111",
            "token": "8b234b2e-b409-43d4-bdf3-db1d7398d767"
        }
    },
    "lastPaymentStatus": "success",
    "lastSuccessfulPaymentDate": "2023-06-30T22:04:11.812Z"
}

See also