Subscriptions

Create a subscription

🛑 Important

Nexio does not currently recommend using the Subscription service for a 3DS flow. For other options, see Getting started with subscriptions in Guides.

Creates a recurring payment as a subscription or payment plan. For guides to using this endpoint, see the Recurring billing overview topic.

A successful request to this endpoint processes an initial transaction using a saved card token and schedules recurring transactions. All transactions are processed with the values provided in the payment object or the data saved in the card token. The scheduled transaction runs according to the values provided in the schedule object.

Also, in order to have a customer skip a month for an existing subscription or payment plan, you need to delete the current one and then recreate it to start with an initialBillingAmount of 0 and have the dateInitialBillingEnd happen a month before the next scheduled payment.

📘 Note

If the initial transaction is declined, the subscription or payment plan will not be created. It must be re-created with a new card token.

After the subscription or payment plan 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 or payment plan remains active, and the system tries again at the next scheduled payment date. In this instance, the merchant would need to contact the customer about the missed payment or transaction. Also, if you have webhooks configured, you will receive a webhook for each of the failures. For additional information about this, see the Creating a Nexio-scheduled card subscription or Creating a Nexio-scheduled card payment plan tutorial.

However, with Decline recovery and when the subscription or payment plan 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.

🛑 Important

When needing to use a 3DS flow to create a subscription, you must first run a customer-facing transaction where the customer proceeds through the 3DS flow (see the Using 3DS to run transactions tutorial). Make sure you use a paymentType of initialScheduled and also save the card token as part of the process.

Then, use this endpoint to create the subscription with that saved card token and a paymentType of scheduled.

⚠️ Try It

To use the Try It feature for this endpoint, you can use the credentials for your Sandbox API user.<br/><br/>You can also use the following test account. Copy the value and paste it into the appropriate space in the Try It section to the right. username: docs@nexiopay.com password: JZdzoXpdDeH6VA<br/><br/>Include at least a saved card token in the tokenex.token parameter, the amount and currency for the transaction, the payment type, and a customer reference number. You can also include the appropriate subscription parameters.

Request parameters

payment
payment.tokenex
payment.tokenex.token
payment.tokenex.firstSix
payment.tokenex.lastFour
payment.isAuthOnly
payment.shouldUpdateCard
payment.processingOptions
payment.processingOptions.saveCardToken
payment.processingOptions.retryOnSoftDecline
payment.processingOptions.checkFraud
payment.processingOptions.shouldUseFingerprint
payment.processingOptions.check3ds
payment.processingOptions.verboseResponse
payment.processingOptions.paymentType
payment.processingOptions.paymentOptionTag
payment.processingOptions.merchantId
payment.processingOptions.customerRedirectUrl
payment.data
payment.data.amount
payment.data.currency
payment.data.settlementCurrency
payment.data.customer
payment.data.customer.customerRef
payment.data.customer.invoice
payment.data.customer.orderNumber
payment.data.customer.orderDate
payment.data.customer.birthDate
payment.data.customer.nationalIdentificationNumber
payment.data.customer.companyName
payment.data.customer.firstName
payment.data.customer.lastName
payment.data.customer.email
payment.data.customer.phone
payment.data.customer.billToAddressOne
payment.data.customer.billToAddressTwo
payment.data.customer.billToCity
payment.data.customer.billToState
payment.data.customer.billToPostal
payment.data.customer.billToCountry
payment.data.customer.billToPhone
payment.data.customer.shipToAddressOne
payment.data.customer.shipToAddressTwo
payment.data.customer.shipToCity
payment.data.customer.shipToState
payment.data.customer.shipToPostal
payment.data.customer.shipToCountry
payment.data.customer.shipToPhone
payment.data.customer.createdAtDate
schedule
schedule.interval
schedule.intervalCount
schedule.balance
schedule.duration
schedule.dateInitialBillingEnd
schedule.intialBillingAmount
schedule.dateCancelAfter

Response parameters

customerRef
active
accountId
id
payment
payment.tokenex
payment.tokenex.token
payment.tokenex.firstSix
payment.tokenex.lastFour
payment.shouldUpdateCard
payment.isAuthOnly
payment.processingOptions
payment.processingOptions.saveCardToken
payment.processingOptions.retryOnSoftDecline
payment.processingOptions.checkFraud
payment.processingOptions.shouldUseFingerprint
payment.processingOptions.check3ds
payment.processingOptions.verboseResponse
payment.processingOptions.paymentType
payment.processingOptions.paymentOptionTag
payment.processingOptions.merchantId
payment.processingOptions.customerRedirectUrl
payment.data
payment.data.amount
payment.data.currency
payment.data.settlementCurrency
payment.data.customer
payment.data.customer.customerRef
payment.data.customer.invoice
payment.data.customer.orderNumber
payment.data.customer.orderDate
payment.data.customer.birthDate
payment.data.customer.nationalIdentificationNumber
payment.data.customer.companyName
payment.data.customer.firstName
payment.data.customer.lastName
payment.data.customer.email
payment.data.customer.phone
payment.data.customer.billToAddressOne
payment.data.customer.billToAddressTwo
payment.data.customer.billToCity
payment.data.customer.billToState
payment.data.customer.billToPostal
payment.data.customer.billToCountry
payment.data.customer.billToPhone
payment.data.customer.shipToAddressOne
payment.data.customer.shipToAddressTwo
payment.data.customer.shipToCity
payment.data.customer.shipToState
payment.data.customer.shipToPostal
payment.data.customer.shipToCountry
payment.data.customer.shipToPhone
payment.data.customer.createdAtDate
schedule
schedule.interval
schedule.intervalCount
schedule.initialBalance
schedule.balance
schedule.duration
schedule.dateInitialBillingEnd
schedule.intialBillingAmount
schedule.dateCancelAfter
schedule.scheduleType
userName
dateCreated
dateLastModified
dateLastRun
dateNextRun
paymentResult
paymentResult.amount
paymentResult.authCode
paymentResult.transactionStatus
paymentResult.transactionDate
paymentResult.transactionType
paymentResult.merchantId
paymentResult.currency
paymentResult.id
paymentResult.asyncTraceId
paymentResult.redirectUrl
paymentResult.message
paymentResult.status
paymentResult.gatewayResponse
paymentResult.gatewayResponse.gatewayName
paymentResult.gatewayResponse.refNumber
paymentResult.data
paymentResult.data.amount
paymentResult.data.currency
paymentResult.data.settlementCurrency
paymentResult.data.customer
paymentResult.data.customer.customerRef
paymentResult.data.customer.orderNumber
paymentResult.data.customer.orderDate
paymentResult.data.customer.invoice
paymentResult.data.customer.birthDate
paymentResult.data.customer.nationalIdentificationNumber
paymentResult.data.customer.companyName
paymentResult.data.customer.firstName
paymentResult.data.customer.lastName
paymentResult.data.customer.email
paymentResult.data.customer.phone
paymentResult.data.customer.billToAddressOne
paymentResult.data.customer.billToAddressTwo
paymentResult.data.customer.billToCity
paymentResult.data.customer.billToState
paymentResult.data.customer.billToPostal
paymentResult.data.customer.billToCountry
paymentResult.data.customer.billToPhone
paymentResult.data.customer.shipToAddressOne
paymentResult.data.customer.shipToAddressTwo
paymentResult.data.customer.shipToCity
paymentResult.data.customer.shipToState
paymentResult.data.customer.shipToPostal
paymentResult.data.customer.shipToCountry
paymentResult.data.customer.shipToPhone
paymentResult.data.customer.createdAt
paymentResult.card
paymentResult.card.cardHolder
paymentResult.card.cardNumber
paymentResult.card.expirationMonth
paymentResult.card.expirationYear
paymentResult.token
paymentResult.token.firstSix
paymentResult.token.lastFour
paymentResult.token.token
paymentResult.kountResponse
paymentResult.kountResponse.status
paymentResult.kountResponse.rules
lastPaymentStatus
lastSuccessfulPaymentDate
exp

</div>

post/subscription/v3

Request body

Response

Success

customerRefstring

Customer identifier. This value cannot later be changed for an existing subscription or payment plan.

activeboolean

Indicates whether the subscription or payment plan is currently active. When false, this indicates that the system will not attempt another transaction.

accountIdstring

The Nexio account number of the user who created the subscription or payment plan. You can also get this value from the response for the Who am I endpoint.

idstring

The unique subscription identifier. You may want to save this value to your system for future tracking and management purposes.

userNamestring

The username of the account through which the subscription was created.

dateCreatedstring

The date and time the subscription or payment plan was created, formatted as an ISO-8601 date expressed in UTC.

dateLastModifiedstring

The date and time the subscription or payment plan was last modified, formatted as an ISO-8601 date expressed in UTC.

dateLastRunstring

The date and time a payment in this subscription or payment plan was last run, formatted as an ISO-8601 date expressed in UTC.

dateNextRunstring

The date a payment in this subscription is next scheduled to run, formatted as YYYY-MM-DD.

lastPaymentStatusstring

Will be either success or failure to indicate whether the last attempted transaction for the subscription or payment plan was successful.

lastSuccessfulPaymentDatestring

The date and time a payment in this subscription or payment plan was last successfully run, formatted as an ISO-8601 date expressed in UTC.

expinteger

This parameter is for Nexio internal use only. It is only returned in requests made in the Sandbox environment.

randomRandomNnnn — unresolved $ref

Create a subscription

Request parameters

Response parameters

Request body

Response

Changes