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 includeschedule.duration
, optional otherwise),payment.data.currency
,payment.data.customer.customerRef
,schedule.interval
,schedule.intervalCount
,schedule.balance
, andschedule.duration
(required if you don't includepayment.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
Updated about 2 months ago