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:

  1. If desired, 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:

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


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