Requesting Recommendations

There are two steps to integrate with transaction optimisation:

1. Request a recommendation
   Send us details of a transaction. We will return a recommendation to either perform authentication or authorisation.

2. Update us with authentication and authorisation attempts
   This could be after each attempt or at the end of the transaction.

Request Recommendations

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

Add the transactionOptimisation=true query parameter to the end of the request’s URL.

This must be used in addition to the score query parameter for specifying a Checkpoint.

For example: /v2/checkout?score=checkoutPreAuth&transactionOptimisation=true

This request must be sent before starting authentication or authorisation.

These are the important fields to send in the recommendation request:

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 or proceed directly to authorisation, and which SCA exemption to use if applicable. The recommendation will be in the data.transactionOptimisation field.

See the Checkout Endpoint Response API Reference for the format of the response.

Several example recommendation responses are shown below.

Recommendation: Send to 3D Secure for authentication with transaction risk analysis exemption

{
    "status": 200,
    "timestamp": 709513200,
    "data": {
        "customerId": "012345678",
        "action": "ALLOW",
        "score": 18,
        "source": "RAVELIN",
        "scoreId": "012345678-012345678-012345678",
        "transactionOptimisation": {
            "transactionId": "ea376fe5-cc16-4a6e-b553-88b1d559a56c",
            "action": "AUTHENTICATE",
            "actionSource": "CLIENT_RULE",
            "exemption": "TRANSACTION_RISK_ANALYSIS",
            "threeDSChallengePreference": "NO_CHALLENGE_REQUESTED"
        }
    }
}

Recommendation: Send to 3D Secure for authentication without an SCA exemption

{
    "status": 200,
    "timestamp": 709513200,
    "data": {
        "customerId": "012345678",
        "action": "ALLOW",
        "score": 28,
        "source": "RAVELIN",
        "scoreId": "012345678-012345678-012345678",
        "transactionOptimisation": {
            "transactionId": "ea376fe5-cc16-4a6e-b553-88b1d559a56c",
            "action": "AUTHENTICATE",
            "actionSource": "CLIENT_RULE",
            "threeDSChallengePreference": "CHALLENGE_REQUESTED"
        }
    }
}

Recommendation: Proceed to authorisation with low value exemption

{
    "status": 200,
    "timestamp": 709513200,
    "data": {
        "customerId": "012345678",
        "action": "ALLOW",
        "score": 18,
        "source": "RAVELIN",
        "scoreId": "012345678-012345678-012345678",
        "transactionOptimisation": {
            "transactionId": "ea376fe5-cc16-4a6e-b553-88b1d559a56c",
            "action": "AUTHORISE",
            "actionSource": "CLIENT_RULE",
            "exemption": "LOW_VALUE"
        }
    }
}

Authentication attempt updates

After you have attempted to authenticate a customer, send a request to our Checkout Endpoint to update us on the outcome.

Add the 3ds object to the transaction object in order to send us the details of the authentication attempt.

An example request is shown below:

POST https://api.ravelin.com/v2/checkout HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "timestamp": 1512828988826,
  "customerId": "abc-123-ZYZ",
  "order": {
    "orderId": "abcde12345-ZXY"
  },
  "paymentMethodId": "pm-abc123",
  "transaction": {
    "transactionId": "123-abc-XYZ",
    "amount": 10000,
    "currency": "GBP",
    "gateway": "example-gateway",
    "3ds": {
      "attempted": true,
      "challenged": true,
      "success": true,
      "startTime": 1479231064910,
      "endTime": 1479231064919,
      "timedOut": false,
      "version": "2.2.0",
      "liabilityShifted": true,
      "eci": "05",
      "transStatus": "Y",
      "messageType": "RReq"
    }
  }
}

Authorisation attempt updates

After you have attempted to authorise a transaction, send a request to our Checkout Endpoint to update us on the outcome.

The following fields should be set in the transaction, where available.

An example request is shown below:

POST https://api.ravelin.com/v2/checkout HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "timestamp": 1512828988826,
  "customerId": "abc-123-ZYZ",
  "order": {
    "orderId": "abcde12345-ZXY"
  },
  "paymentMethodId": "pm-abc123",
  "transaction": {
    "transactionId": "123-abc-XYZ",
    "type": "auth_capture",
    "amount": 10000,
    "currency": "GBP",
    "gateway": "example-gateway",
    "gatewayReference": "123-abc-XYZ",
    "success": true,
    "authCode": "1234",
    "cvvResultCode": "pass"
  }
}

Completed transaction updates

Instead of updating Ravelin after each stage of the transaction, you can update us after the transaction has finished processing.

Send a request to our Checkout Endpoint and provide all the details of any authentication and authorisation attempts.

The following fields should be set in the transaction, where available.

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.