Running subscription transactions with decline recovery

You can use Nexio's decline recovery feature when running card transactions with the API or card transactions run through the subscription service.

📘

Notes

• 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.)
• If a merchant is using both account updater and decline recovery, and we receive a decline that we can potentially resolve using Account updater, the Nexio system requests the update for the card, attempts the transaction in 7 days, and then resumes the decline recovery logic.

You may enable decline recovery on transactions run through the Nexio subscription service (subscriptions and pay plans).

1. Contact Integrations Support to enable decline recovery on your merchant account.

2. In order to be notified when a previously declined transaction is successfully processed, you must configure webhooks for the merchantId that is configured for decline recovery. If you've already configured these webhooks, skip this step.

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

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

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

   Include the retryOnSoftDecline parameter (and set it to true) in the body of your request. You must also include the orderNumber parameter.

   Example Request

   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",
           "orderNumber": "210058A"
         }
       },
       "tokenex": {
         "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
       },
       "processingOptions": {
         "retryOnSoftDecline": true
       }
     },
     "schedule": {
       "interval": "week",
       "intervalCount": 2
     }
   }'
   

   If the initial transaction is declined, the subscription is not created. It must be re-created with corrected information (such as a new card token or corrected billing information). 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 the webhooks to check for any declined transactions, Nexio sends a webhook (see step 2) for the TRANSACTION event type with a transactionStatus of 30 (meaning "declined"), Then, another webhook with the DECLINE_RECOVERY event type, as in the following example:

   Example Webhook Response

    {
        "eventType": "DECLINE_RECOVERY",
        "retryId": 43118,
        "orderNumber": "45928c5ae6105e6a02ba"
    }
   

   Use the retryId from the webhook response to get more information about the status of the declined transaction. Send a GET request to the View a decline recovery record endpoint using the retryId as the path parameter, as in the following example:

   Example RequestExample 200 Response

   curl --request GET \
    --url https://api.nexiopaysandbox.com/recovery/v3/retry/43118 \
    --header 'Accept: application/json' \
    --header 'Authorization: Basic [Base64_encoded_login]'
   

   {
       "id": 43118,
       "cardToken": "7c523ae8-d8b6-4522-a089-b97e123b5474",
       "retryDate": "2022-08-10T17:00:00.000Z",
       "transactionDate": "2022-08-09T15:27:16.000Z",
       "originalAmount": 18.18,
       "originalDeclinePaymentId": "eyJuYW1lIjoiYXV0aG9yaXplIiwibWVyY2hhbnRJZCI6IjEwMDI2MCIsInJlZk51bWJlciI6IjQwMDk5Nzk2MTg5IiwicmFuZG9tIjowLCJjdXJyZW5jeSI6InVzZCJ9",
       "retryEngineType": 10,
       "retryProviderRefNumber": "06186DY5AC0000760827XNJ8CADZW",
       "orderNumber": "45928c5ae6105e6a02ba",
       "recoveryStatus": 30,
       "retryCount": 0,
       "merchantId": "100260",
       "originalPaymentRequest": "{\"processingOptions\":{\"updateDynamoCard\":true,\"retryOnSoftDecline\":true},\"data\":{\"amount\":18.18,\"currency\":\"USD\",\"customer\":{\"billToPostal\":\"46282\",\"orderNumber\":\"45928c5ae6105e6a02ba\"}},\"tokenex\":{\"lastFour\":\"4242\",\"requestToken\":\"7c523ae8-d8b6-4522-a089-b97e123b5474\",\"firstSix\":\"424242\",\"token\":\"7c523ae8-d8b6-4522-a089-b97e123b5474\"},\"isProcessedFromServer\":true,\"clientIp\":\"10.0.0.1\"}",
       "retryMetadata": "{\"transaction\":{\"response\":{\"avsCode\":null,\"avsMessage\":null,\"cvvCode\":null,\"cvvMessage\":null,\"errorCode\":null,\"errorDetail\":\"This transaction has been declined.\"},\"paymentMethod\":{\"paymentMethodId\":\"QB6G7KLKATGEXIVAAGBIGN6GLY\",\"creditCardNumber\":\"424242******4242\",\"expiryMonth\":\"09\",\"expiryYear\":\"2023\",\"cvv\":\"\",\"firstName\":\"Checkout\",\"lastName\":\"Test\",\"fullName\":\"Checkout Test\",\"customerId\":\"customer123\",\"address1\":\"123 Test St\",\"address2\":\"Suite 123\",\"postalCode\":\"46282\",\"city\":\"Testerville\",\"state\":\"UT\",\"country\":\"US\",\"email\":\"[email protected]\",\"phoneNumber\":\"8015551234\",\"paymentMethodType\":\"CreditCard\",\"fingerprint\":null,\"lastFourDigits\":\"4242\",\"firstSixDigits\":\"424242\",\"cardType\":\"VISA\",\"dateCreated\":\"2022-08-09T15:27:26.814Z\",\"storageState\":\"Cached\"},\"transactionId\":\"06186DY5AC0000760827XNJ8CADZW\",\"transactionDate\":\"2022-08-09T15:27:26.547Z\",\"transactionStatus\":2,\"message\":\"Bank decline.\",\"responseCode\":\"20022\",\"transactionType\":\"Charge\",\"merchantTransactionId\":\"e95b6afb-4e3b-4f4b-8515-3aafe191a7cf\",\"customerId\":\"customer123\",\"currencyCode\":\"USD\",\"amount\":1818,\"gatewayToken\":\"OD435S4OAA6U3OWDAF3ZGDLIUY\",\"gatewayType\":\"authorize_net\",\"gatewayTransactionId\":null,\"merchantAccountReferenceId\":\"100260-40\",\"assignedGatewayToken\":\"OD435S4OAA6U3OWDAF3ZGDLIUY\",\"orderId\":\"45928c5ae6105e6a02ba\",\"retryDate\":\"2022-08-10T17:00:00\",\"retryCount\":0,\"dateFirstAttempt\":\"2022-08-09T15:27:26.547Z\",\"description\":null,\"productSku\":null,\"subscriptionId\":null,\"references\":{\"previousTransaction\":{\"gatewayMessage\":\"This transaction has been declined.\",\"transactionStatus\":2}},\"customerIp\":\"10.0.0.1\",\"shippingAddress\":{\"address1\":\"123 Ship St\",\"address2\":\"Warehouse 456\",\"postalCode\":\"67890\",\"city\":\"Shipperville\",\"state\":\"OR\",\"country\":\"US\"},\"referenceData\":\"CAABAEWGQaobetoIcPm+y44APU26wwF3kw1opn7WSGKb/uYAAAABgoM3xVM=\",\"disableCustomerRecovery\":false,\"customVariable1\":null,\"customVariable2\":null,\"customVariable3\":null,\"customVariable4\":null,\"customVariable5\":null}}",
       "userName": "[email protected]",
       "isEnabledForRecovery": true,
       "createdAt": "2022-08-09T15:27:27.000Z",
       "updatedAt": "2022-08-09T15:27:27.000Z",
       "retryProviderBody": "{\"transaction\":{\"merchantTransactionId\":\"e95b6afb-4e3b-4f4b-8515-3aafe191a7cf\",\"orderId\":\"45928c5ae6105e6a02ba\",\"customerId\":\"customer123\",\"currencyCode\":\"USD\",\"amount\":1818,\"paymentMethod\":{\"creditCardNumber\":\"{{{7c523ae8-d8b6-4522-a089-b97e123b5474}}}\",\"expiryMonth\":\"09\",\"expiryYear\":\"2023\",\"firstName\":\"Checkout\",\"lastName\":\"Test\",\"fullName\":\"Checkout Test\",\"address1\":\"123 Test St\",\"address2\":\"Suite 123\",\"postalCode\":\"46282\",\"city\":\"Testerville\",\"state\":\"UT\",\"country\":\"US\",\"email\":\"[email protected]\",\"phoneNumber\":\"8015551234\"},\"customerIp\":\"10.0.0.1\",\"shippingAddress\":{\"address1\":\"123 Ship St\",\"address2\":\"Warehouse 456\",\"postalCode\":\"67890\",\"city\":\"Shipperville\",\"state\":\"OR\",\"country\":\"US\"},\"references\":{\"previousTransaction\":{\"transactionStatus\":2,\"gatewayMessage\":\"This transaction has been declined.\"}},\"gateway\":{\"name\":\"authorize_net\",\"merchantAccountReferenceId\":\"100260-40\",\"gatewayType\":\"authorize_net\",\"currencyCode\":\"USD\"},\"retryCount\":0,\"dateFirstAttempt\":\"2022-08-09T15:27:16.203Z\"}}",
       "declineMessage": "This transaction has been declined."
   }