Creating a Nexio-scheduled card payment plan

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.

To create this type of payment plan, follow these steps:

If desired for tracking payments and errors, 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:
- The currency to use.
- The customer reference number.
- Which saved card token to use.
- 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.
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 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.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.
```
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"
      }
    },
    "tokenex": {
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
    }
  },
  "schedule": {
    "interval": "month",
    "intervalCount": 1,
    "balance": 500,
    "duration": 10
  }
}'
```
The following example creates a recurring payment plan 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 and continue until the total balance is paid off.
```
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,
    "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.

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

{
    "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