Running subscription transactions with decline recovery

You can use Nexio's Decline Recovery service when running card transactions with the API or card transactions run through the subscription service.



  • Decline Recovery does not immediately determine whether the payment will go through at a later date. It should not be used for payments for which the customer will be waiting for payment confirmation, such as through the payment iframe or your own form.
  • Decline Recovery will not attempt to retry transactions classified as hard declines. In general, hard declines require the issuer or cardholder to rectify outstanding issues. (See FlexPay's documentation for more information regarding hard and soft declines.)

You may enable Decline Recovery on transactions run through the Nexio Subscription Service (subscriptions and pay plans).

  1. Configure Your Account

    Contact Integrations Support to enable Decline Recovery on your merchant account.

  2. Configure Webhooks

    In order to be notified when a previously declined transaction is successfully processed, you must configure webhooks for TRANSACTION_AUTHORIZED, TRANSACTION_CAPTURED and TRANSACTION_SETTLED events.

    See the webhooks tutorial in the Developer Tools section for instructions on how to configure and receive webhooks.

    You may also wish to configure webhooks for other transaction events at this time.

  3. Create a Subscription or Pay Plan

    Follow steps 1-2 of the Creating a subscription or Creating a pay plan tutorial.

    Set the parameter payment.processingOptions.retryOnSoftDecline to true in the body of your request.

    Example Request
    curl -X POST \
      -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"
        "processingOptions": {
          "retryOnSoftDecline": true
      "schedule": {
        "interval": "week",
        "intervalCount": 2

    If the initial transaction is declined, the subscription will not be created. It must be re-created with corrected information (such as new card token, corrected billing information, etc.). Any future transactions that are declined will be rerun at a later date and time. (Up to 11 times within a 30 day period.)

    Note: Subscriptions run with Decline Recovery have a minimum interval of 29 days.

  4. Monitor Webhooks

    Each time a transaction is retried Nexio will send a webhook (see step 2) with one of the following event types:
    The webhook body will include the transaction status (data.transactionStatus), letting you know whether the transaction was successful.

Did this page help you?