Transaction Optimisation Integration

Requesting and handling recommendations

On this page:

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:

Important Fields
paymentMethod.expiryMonth
paymentMethod.expiryYear
paymentMethod.iin
paymentMethod.instrumentId
paymentMethod.lastFour
paymentMethod.methodType
timestamp
transaction.acquirerBin
transaction.acquirerCountryCode
transaction.acquirerId
transaction.amount
transaction.currency
transaction.gateway
transaction.mcc
transaction.mid
transaction.transactionId

We only provide transaction optimisation routing recommendations if the paymentMethod.methodType is set to card. 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": 0.765,
    "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": 0.765,
    "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": 0.765,
    "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": 0.765,
    "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:

Important Fields
threeds.challengeCancel
threeds.challenged
threeds.deviceChannel
threeds.eci
threeds.errorCode
threeds.errorComponent
threeds.errorMessageType
threeds.liabilityShifted
threeds.requestorChallengeInd
threeds.transStatus
threeds.transStatusReason
threeds.version
threeds.whiteListStatus
threeds.whiteListStatusSource

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

Important Fields
transaction.declineCode
transaction.softDeclineCode
transaction.success
transaction.transactionId

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:

Payment Fraud Action Recommended route
ALLOW This transaction carries a low payment fraud risk and is optimisable. Follow the transaction optimisation recommendation provided (authenticate or authorise).
REVIEW This transaction carries a medium payment fraud risk. Send to authentication with a 3DS Requestor Challenge Indicator value of 01 (no preference).

Using this value will help to avoid friction and gain liability shift where possible.
PREVENT This transaction carries a high payment fraud risk. Stop processing.

Next steps

Test your transaction optimisation integration

Learn how to correctly handle transaction optimisation errors

Feedback