Running API card transactions with decline recovery
Background |
---|
Before starting this tutorial, make sure you understand the following topics from the Quick start section:
|
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 totrue
) in the body of your request. You must also include theorderNumber
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 theretryId
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." }
Updated 6 months ago