Running API card 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 directly through the Nexio API.

  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 Developer Tools for instructions on how to configure and receive webhooks.
    You may also wish to configure webhooks for other transaction events at this time.

    (Skip this step if you have already configured webhooks for all desired events on your account.)

  3. Post Card Information to Nexio

    Post payment details along with a previously saved card token to the Run card transaction endpoint. Include the object "processingOptions": { "retryOnSoftDecline": true } in the body of your request.

    If desired, you may also choose to run an auth only transaction.

    Example Request
    curl -X POST \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Basic [Base64_encoded_login]'
      -d '{
      "data": {},
      "tokenex": {
        "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
      "processingOptions": {
        "retryOnSoftDecline": true

    Now, any successful transactions will be run as usual. Soft declines will be scheduled to be rerun at a later time.

  4. Await Success Confirmation

    Each time a transaction is retried Nexio will send a webhook (see step 2) with one of the following legacy 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?