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
, andpayment.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
Updated about 2 months ago