Running API card transactions with decline recovery

Background
Before starting this tutorial, make sure you understand the following topics from the Quick start section: Sandbox environments (especially about testing). Authentication (about authenticating using your API user and when you need a login versus a one-time-use token).

You can use Nexio's decline recovery service 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 directly through the Nexio API.

Contact Integrations Support to enable Decline Recovery on your merchant account.
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.

Post payment details along with a previously saved card token to the Run card transaction endpoint. Include the retryOnSoftDecline parameter (and set it to true) in the body of your request. You must also include the orderNumber parameter.

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

curl -X POST https://api.nexiopaysandbox.com/pay/v3/process \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic [Base64_encoded_login]'
  -d '{
  "data": {
      "amount": 29.99,
      "customer": {
          "orderNumber": "210058A"
      }
  },
  "tokenex": {
      "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d"
  },
  "processingOptions": {
      "retryOnSoftDecline": true
  }
}'

  {
    "id": "eyJuYW1lIjoWJlciI6IjMxCJtZXJjaGFudElkIjoiMoiVVNEIn0=eyJuYW1lIjoib3BlbnBheSIsIm1lcmN",
    "merchantId": "100039",
    "authCode": "035410",
    "amount": 29.99,
    "currency": "EUR",
    "transactionDate": "2019-01-15T13:19:39.329Z",
    "transactionStatus": "settled",
    "transactionType": "sale",
    "shouldUpdateCard": true,
    "card": {
        "cardType": "visa",
        "cardHolder": "John H Doe",
        "cardNumber": "424242******4242",
        "expirationMonth": "12",
        "expirationYear": "28"
    },
    "token": {
        "firstSix": "479300",
        "lastFour": "3313",
        "token": "6ee140a0-05d1-4958-8325-b38a690dbb9d",
        "cardType": "visa"
    },
    "data": {
        "amount": 29.99,
        "currency": "EUR",
        "settlementCurrency": "CAD",
        "customer": {
          "customerRef": "RP006",
          "orderNumber": "210058A",
          "orderDate": "2021-08-26",
          "invoice": "IN0001",
          "firstName": "John",
          "lastName": "Doe",
          "birthDate": "1990-12-05",
          "billToAddressOne": "2147 West Silverlake Drive",
          "billToAddressTwo": "Apt 42",
          "billToCity": "Scranton",
          "billToState": "PA",
          "billToPostal": "18503",
          "billToCountry": "US",
          "billToPhone": "1555555555",
          "email": "[email protected]",
          "phone": "1555555555",
          "shipToAddressOne": "1725 Slough Avenue",
          "shipToAddressTwo": "Suite 200",
          "shipToCity": "Scranton",
          "shipToState": "PA",
          "shipToPostal": "18505",
          "shipToCountry": "US",
          "shipToPhone": "1555555555",
          "createdAt": "2020-04-28T18:50:04.866Z"
        },
        "cart": {
          "items": [
            {
              "item": "913261",
              "description": "Hammermill Premium 8.5 x 11 Color Copy Paper, 28 lbs. 500/Ream",
              "quantity": 8,
              "price": 16.49,
              "type": "sale"
            }
          ]
        },
        "customFields": {
          "exampleKey": "Example string",
          "exampleRefNumber": "094785"
        }
      },
      "kountResponse": {
        "status": "success",
        "rules": "{\"VERS\":\"0630\",\"MODE\":\"Q\",\"TRAN\":\"7V7D0V1BMKPX\",\"MERC\":\"717000\",\"SESS\":\"3bbb89edcd5742f18e2502ebb2bbb18b\",\"ORDR\":\"14233\",\"AUTO\":\"A\",\"SCOR\":\"29\",\"GEOX\":\"US\",\"BRND\":\"VISA\",\"REGN\":null,\"NETW\":\"N\",\"KAPT\":\"N\",\"CARDS\":\"1\",\"DEVICES\":\"1\",\"EMAILS\":\"1\",\"VELO\":\"0\",\"VMAX\":\"0\",\"SITE\":\"DEFAULT\",\"DEVICE_LAYERS\":\"....\",\"FINGERPRINT\":null,\"TIMEZONE\":null,\"LOCALTIME\":\" \",\"REGION\":null,\"COUNTRY\":null,\"PROXY\":null,\"JAVASCRIPT\":null,\"FLASH\":null,\"COOKIES\":null,\"HTTP_COUNTRY\":null,\"LANGUAGE\":null,\"MOBILE_DEVICE\":null,\"MOBILE_TYPE\":null,\"MOBILE_FORWARDER\":null,\"VOICE_DEVICE\":null,\"PC_REMOTE\":null,\"RULES_TRIGGERED\":0,\"COUNTERS_TRIGGERED\":0,\"REASON_CODE\":null,\"MASTERCARD\":\"\",\"DDFS\":null,\"DSR\":null,\"UAS\":null,\"BROWSER\":null,\"OS\":null,\"PIP_IPAD\":null,\"PIP_LAT\":null,\"PIP_LON\":null,\"PIP_COUNTRY\":null,\"PIP_REGION\":null,\"PIP_CITY\":null,\"PIP_ORG\":null,\"IP_IPAD\":null,\"IP_LAT\":null,\"IP_LON\":null,\"IP_COUNTRY\":null,\"IP_REGION\":null,\"IP_CITY\":null,\"IP_ORG\":null,\"WARNING_COUNT\":0}"
      },
      "installment": {
        "period": "10"
      },
      "gatewayResponse": {
        "gatewayName": "[usaepay]",
        "refNumber": "8E56222GD0701110"
      }

  }

  {
    "error": 435,
    "message": "This transaction has been declined.",
    "gatewayResponse": {
        "gatewayName": "authorize",
        "refNum": "40099811799",
       "status": "declined"
    },
    "merchantId": "100260"
  }

A successful transaction processes as normal. Soft declines are scheduled to be rerun at a later time. Hard declines are marked as unrecoverable.

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:

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

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."
}

📘Notes

📘
Notes