Requesting and handling recommendations

There are two steps to integrate with transaction optimisation:

1. Request a recommendation
   Send us transaction details, and we will return a recommendation to authenticate or authorise, with or without an exemption and 3DS challenge preference.

2. Update us with authentication and authorisation attempts
   You can update us at the end of 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.

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

Example where we return an authorisation recommendation

{
  "status": 200,
  "timestamp": 1710852020908,
  "data": {
    "action": "ALLOW",
    "transactionId": "ea376fe5-cc16-4a6e-b553-88b1d559a56c",
    "scoreId": "7fffffff9a065fe20028e9f66-5b61cf00-cc5c-4689-a772-d62a4ab06ad3",
    "score": 76,
    "rules": {},
    "transactionOptimisation": {
      "ruleId": 29607796,
      "ruleVersion": 1,
      "action": "AUTHORISE",
      "actionSource": "CLIENT_RULE",
      "exemption": "LOW_VALUE",
      "rules": {
        "triggered": [
          {
            "ruleId": 29607796,
            "ruleVersion": 1,
            "state": "active",
            "action": "AUTHORISE",
            "exemption": "LOW_VALUE",
            "description": "Customer email address is equal to qa-force-txopt-authorise-lowvalue@ravelin.com"
          }
        ]
      }
    }
  }
}

Example where we return an authentication recommendation

{
  "status": 200,
  "timestamp": 1710852020908,
  "data": {
    "action": "ALLOW",
    "transactionId": "c69120fb-8048-4e54-a7ff-3b34da594747",
    "scoreId": "7fffffff9a06784b00a383df2-203ceb5e-b797-44ba-8afd-e59570ecec17",
    "score": 76,
    "rules": {},
    "transactionOptimisation": {
      "ruleId": 29607796,
      "ruleVersion": 1,
      "action": "AUTHENTICATE",
      "actionSource": "CLIENT_RULE",
      "exemption": "TRANSACTION_RISK_ANALYSIS",
      "threeDSChallengePreference": "NO_CHALLENGE_REQUESTED",
      "rules": {
        "triggered": [
          {
            "ruleId": 29607798,
            "ruleVersion": 1,
            "state": "active",
            "action": "AUTHENTICATE",
            "exemption": "TRANSACTION_RISK_ANALYSIS",
            "threeDSChallengePreference": "NO_CHALLENGE_REQUESTED",
            "description": "Customer email address is equal to qa-force-txopt-authenticate-tra@ravelin.com"
          }
        ]
      }
    }
  }
}

Examples where we return no recommendation

{
  "status": 200,
  "timestamp": 1710859712297,
  "data": {
    "action": "PREVENT",
    "transactionId": "ea376fe5-cc16-4a6e-b553-88b1d559a56c",
    "scoreId": "7fffffff9a065a3f031f52222-d98afde8-5711-4a34-965a-e656e834255c",
    "score": 76,
    "rules": {
      "passiveAction": "PREVENT",
      "triggered": [
        {
          "ruleId": 29609356,
          "ruleVersion": 1,
          "state": "active",
          "action": "PREVENT",
          "description": "Customer email address is equal to cust-prevent@ravelin.com"
        }
      ]
    }
  },
  "message": "no transaction optimisation recommendation due to payment fraud action type"
}

{
  "status": 200,
  "timestamp": 1710859712297,
  "data": {
    "action": "REVIEW",
    "transactionId": "95482fce-8a04-4b5b-951b-123c29e70a83",
    "scoreId": "7fffffff9a06652102a2ab68f-b4ef16ef-5b4c-47b7-993e-570f573c864a",
    "score": 76,
    "rules": {
      "passiveAction": "REVIEW",
      "triggered": [
        {
          "ruleId": 29609357,
          "ruleVersion": 1,
          "state": "active",
          "action": "REVIEW",
          "description": "Customer email address is equal to cust-review@ravelin.com"
        }
      ]
    }
  },
  "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:

You should include the transaction.stepId to tell us which transaction step your update refers to.

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.