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.

📘

Note

After the subscription is created, if a subsequent transaction gets declined or has an error, the system retries the transaction up to three times, one minute apart. On the third failure, the system stops trying for that installment, the subscription remains active, and the system tries again at the next scheduled payment date. In this instance, the merchant needs to contact the customer about the missed payment. Also, if you have webhooks configured, you will receive a webhook for each of the failures.

However, with Decline recovery and when the subscription was created with the retryOnSoftDecline parameter, instead of doing the three retries at a minute apart, the system retries according to the recommendation received from the Decline recovery system.

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.
   • The payment type - The type of transaction being processed using stored payment credentials. Use this parameter to properly flag initial and subsequent transactions. For more information about this parameter and when to use each option, see the paymentType documentation and reference table.

   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.processingOptions.paymentType, 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.

   Subscription running 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"
         }
       },
       "processingOptions": {
         "paymentType": "initialScheduled"
       },
       "tokenex": {
         "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
       }
     },
     "schedule": {
       "interval": "week",
       "intervalCount": 2
     }
   }'
   

   
   
   Subscription with initial billing period

   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"
         }
       },
       "processingOptions": {
         "paymentType": "initialScheduled"
       },
       "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.

   Sample response

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

• Recurring billing overview
• Getting started with subscriptions
• Getting started with pay plans