marcopolo Online payment
Sign up

Introduction

When processing online transactions for card payment methods, a 3-D Secure authentication check via SCA is generally mandatory. However, the SCA guideline also grants the possibility to implement the authentication step as a background process (via the so-called frictionless flow), making it imperceptible for your customers.

However, there is always a chance that your customer's bank insists your customers authenticate themselves actively (via the so-called challenge flow), declining the transaction.

Our Soft Decline mechanism is a great way to recover these declined transactions. It allows you to resend the transaction once more to our platform after a first rejection due to a frictionless authentication attempt. Resubmitting the transaction while enforcing the challenge flow in the second request will raise the chance that your transaction is accepted after all.

Soft Decline is available for the following payment methods: 
MasterCard
Visa
via all integration modes

Understand Soft Decline payment flow

This is a high-level payment flow covering only the mandatory steps for this feature. Regardless of the mode you choose, the flow follows some basic steps as described below. Learn in our dedicated guides about the individual differences.

Our Soft Decline feature is available for or all our integration modes and blends in seamlessly in the payment flow.

  1. You send a standard CreateHostedCheckout/CreatePayment request to our platform, including at least the mandatory 3-D Secure properties while indicating that you want to enforce the frictionless flow. Depending on your integration mode, differences apply. Check out the "Integrate Soft Decline" chapter to find examples for each mode.
  2. Our platform sends the request to your customer’s issuer. Depending on the issuer’s response, two scenarios are possible:
    a): The issuer accepts the transactions with the frictionless flow. We submit the actual financial transaction to the acquirer to process it. We receive the transaction result, ending the flow.
    b): The issuer insists on challenge flow. The flow continues at 3).
  3. Our platform returns a response to you. It includes statusOutput.statusCode=2 and statusOutput.errors.code=40001139, informing you that the issuer insists on the challenge flow.
  4. Our platform automatically redirects your customers to their issuer for 3-D Secure authentication.
  5. Our system receives the 3-D authentication result from the issuer.
  6. We process the transaction and receive the result from the acquirer.
  7. We redirect your customer to your returnUrl.
  8. You request the transaction result from our platform via GetPaymentDetails/GetHostedCheckout or receive the result via webhooks.

Integrate Soft Decline

Add the following property to a standard CreateHostedCheckout/CreatePayment request (including mandatory 3-D Secure properties):

Properties Remarks

cardPaymentMethodSpecificInput.threeDSecure
     skipAuthentication

skipAuthentication: Set to "true" to indicate that you wish to use the Soft Decline feature

Depending on the integration mode, differences apply. Find an example for all in the "Integration" tab for the respective payment:

American Express
MasterCard
Visa

Find detailed information about this object and its properties in our CreatePaymentAPI/CreateHostedCheckoutAPI.

Test Soft Decline

Add the following properties to a standard CreateHostedCheckout/CreatePayment request (including mandatory 3-D Secure properties).

Make sure to:

  • Set the exact order.amountOfmoney.amount=1602 together with skipAuthentication/exemptionRequest as described above.
  • Use card number 4874970686672022 or any other Visa card number from our test cases triggering a challenge flow.
  • Choose a currency for order.amountOfmoney.currencyCode  that uses only two decimals. 
CreateHostedCheckout CreatePayment
{
   "cardPaymentMethodSpecificInput":{
      "threeDSecure":{
         "skipAuthentication":true,
         "exemptionRequest":"low-value"
      }
   },
   "order":{
      "amountOfMoney":{
         "amount":1602,
         "currencyCode":"EUR"
      }
   }
}
{
   "cardPaymentMethodSpecificInput":{
      "card":{
         "cardholderName":"Wile E. Coyote",
         "cardNumber":"4874970686672022",
         "cvv":"123",
         "expiryDate":"0529"
      },
      "paymentProductId":1,
      "returnUrl":"https://yourReturnUrl.com",
      "threeDSecure":{
         "skipAuthentication":true,
         "exemptionRequest":"low-value"
      }
   },
   "order":{
      "amountOfMoney":{
         "amount":1602,
         "currencyCode":"EUR"
      },
      "customer":{
         "device":{
            "acceptHeader":"texthtml,application/xhtml+xml,application/xml;q=0.9,/;q=0.8",
            "browserData":{
               "colorDepth":24,
               "javaEnabled":false,
               "screenHeight":"1200",
               "screenWidth":"1920"
            },
            "ipAddress":"123.123.123.123",
            "locale":"en_GB",
            "userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_4) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/12.1 Safari/605.1.15",
            "timezoneOffsetUtcMinutes":"420"
         },
         "locale":"en_GB"
      }
   }
}

Was this page helpful?

Do you have any comments?

Thank you for your response.