Requesting and handling recommendations

Alongside your payment fraud integration, there are two extra things to consider for transaction optimisation:

1. Requesting recommendations
   Make sure you send us important transaction and payment method details. We will return a recommendation to authenticate or authorise with or without an exemption or 3DS challenge preference where applicable.

2. Update us with authentication and authorisation attempts
   Make sure you update us at the end of the transaction about these attempts.

Requesting recommendations

A transaction optimisation recommendation can be requested by sending a request to the transaction endpoint.

The checkpoint=pspBeforeAuth query parameter at the end of your request URL is used for both payment fraud and transaction optimisation recommendations, but you will need to include &transactionOptimisation=true to ensure you also receive the latter.

For example, /psp/transaction?checkpoint=pspBeforeAuth&transactionOptimisation=true.

This recommendation request must be sent before performing authentication or authorisation.

There are important fields that must be included in the request:

We only provide transaction optimisation routing recommendations if the paymentMethod.methodType is set to card and the payment is not using an e-wallet. This is because other transaction types may be out of PSD2 scope, have Strong Customer Authentication built in already (e.g. Apple Pay), or do not support 3D Secure. Our recommendations are based around 3DS used as the mechanism to support SCA.

We will return a recommendation to either perform authentication through 3D Secure, or proceed directly to authorisation. A Strong Customer Authentication (SCA) exemption and 3DS challenge preference will also be returned if applicable.

Our recommendations will be driven by different sources:

• Machine Learning: This will drive the majority of our recommendations for optimisable traffic.
• Rules: You can request that Ravelin configure rules to be applied to optimisable traffic. However, we strongly recommend that recommendations be driven by our ML for optimisation purposes.
• Compliance Logic: This will help identify traffic which cannot be optimised, as well as help keep you compliant with PSD2 SCA.

The response will be appended to the payment fraud recommendation, with optimised recommendations being provided only to transactions we believe are low risk.

The recommendation will be in the data.transactionOptimisation field. It is important that you handle the following fields in your integration:

• data.transactionOptimisation.action
• data.transactionOptimisation.exemption
• data.transactionOptimisation.threeDSChallengePreference

More specific guidance on how to handle different recommendations is given in the next section.

Handling Recommendations

The table below explains what our recommendations may be and how to handle them.

It is important that we are aware of any restrictions that your payment partners may have when accepting routing and exemption recommendations. Please let us know if any of the following applies so that we can provide you with the best possible recommendations:

• If you or any of your acquirers have breached their Reference Fraud Rates.
• If you work with a payment partner that has any restricted routing. For instance, if your payment partner can only accept authenticate routing recommendations, we will ensure that our ML doesn’t return authorise routing recommendations, and we will return AUTHENTICATE with NO_PREFERENCE when the transaction is One-Leg-Out.

Example Recommendation Responses

Several example recommendation responses are shown below.

Recommendation: Send to 3D Secure for authentication with challenge as mandate

{
  "status": 200,
  "timestamp": 1738162660,
  "data": {
    "action": "ALLOW",
    "score": 18,
    "scoreId": "7fffffff985f3ab20133f3854-a0837cc1-0d5a-4436-902e-a9afcfd9e3a8",
    "transactionId": "b835c733-a50c-4048-a002-9c64d9b216c6",
    "transactionOptimisation": {
      "action": "AUTHENTICATE",
      "actionSource": "COMPLIANCE",
      "threeDSChallengePreference": "CHALLENGE_REQUESTED_AS_MANDATE",
      "compliance": {
        "type": "PSD2",
        "optimisable": false,
        "description": "must authenticate transactions with value 500 EUR or greater"
      }
    }
  }
}

Recommendation: Send to 3D Secure for authentication with TRA (low risk) exemption and no challenge requested

{
  "status": 200,
  "timestamp": 1738162660,
  "data": {
    "action": "ALLOW",
    "score": 18,
    "scoreId": "7fffffff9a06784b00a383df2-203ceb5e-b797-44ba-8afd-e59570ecec17",
    "transactionId": "b835c733-a50c-4048-a002-9c64d9b216c6",
    "rules": {},
    "transactionOptimisation": {
      "action": "AUTHENTICATE",
      "actionSource": "ML",
      "exemption": "TRANSACTION_RISK_ANALYSIS",
      "threeDSChallengePreference": "NO_CHALLENGE_REQUESTED",
      "compliance": {
        "type": "PSD2",
        "optimisable": true,
        "excludedRecommendations": [
          {
            "recommendation": {
              "route": "AUTHENTICATE",
              "exemption": "LOW_VALUE"
            },
            "description": "only available for transactions with value less than 30 EUR"
          },
          {
            "recommendation": {
              "route": "AUTHORISE",
              "exemption": "LOW_VALUE"
            },
            "description": "only available for transactions with value less than 30 EUR"
          }
        ]
      }
    }
  }
}

Recommendation: Proceed to authorisation with low value exemption

{
  "status": 200,
  "timestamp": 1738162660,
  "data": {
    "action": "ALLOW",
    "score": 18,
    "scoreId": "7fffffff9a065fe20028e9f66-5b61cf00-cc5c-4689-a772-d62a4ab06ad3",
    "transactionId": "b835c733-a50c-4048-a002-9c64d9b216c6",
    "transactionOptimisation": {
      "action": "AUTHORISE",
      "actionSource": "ML",
      "exemption": "LOW_VALUE",
      "compliance": {
        "type": "PSD2",
        "optimisable": true
      }
    }
  }
}

Example where transaction optimisation is not supported

{
  "status": 200,
  "timestamp": 1710859712297,
  "data": {
    "action": "REVIEW",
    "transactionId": "95482fce-8a04-4b5b-951b-123c29e70a83",
    "scoreId": "7fffffff9a06652102a2ab68f-b4ef16ef-5b4c-47b7-993e-570f573c864a",
    "score": 54
  },
  "message": "no transaction optimisation recommendation due to payment fraud action type"
}

Authentication and authorisation attempt updates

After you have attempted authentication and/or authorisation, you need to send us a request to our transaction endpoint with the outcome.

There are important fields that must be included in the request around the authentication:

There are important fields that must be included in the request around the authorisation:

Handling soft declines

If you receive a soft decline code after the initial authorisation attempt, you can include this in a single update after the authorisation.

If we recommend going straight to authorisation and the issuer responds with a soft decline, some payment service providers automatically trigger Strong Customer Authentication. You can still update us about this in a single authentication and authorisation update, and use transaction.softDeclineCode field to indicate there was a soft decline. This will be used to improve our recommendations in the future.

If there are no mechanisms in place to automatically respond to soft declines today, we strongly recommend you introduce logic to send a transaction to 3DS authentication once a soft decline is received, setting the 3DS Requestor Challenge Indicator value to 04 (challenge requested - mandate). This will help to reduce latency in the overall transaction flow.

Managing payment fraud and transaction optimisation recommendations

We provide transaction optimisation recommendations on what is considered low risk payment fraud traffic. We will therefore only provide optimised routing recommendations when we return an Allow for payment fraud.

We recommend the following actions for our recommendations in markets where authentication mandates exist:

Next steps

Test your transaction optimisation integration

Learn how to correctly handle transaction optimisation errors

Feedback

Was this page helpful?

Thanks for the feedback. If you'd like to provide more detail, please email support@ravelin.com.