Transaction Optimisation Integration

Requesting Recommendations

On this page:

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 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:

Important Fields
order.orderId
order.creationTime
order.price
order.currency
order.country
transaction.transactionId
transaction.time
transaction.amount
transaction.currency
transaction.gateway
transaction.mcc
transaction.mid
transaction.acquirerId
transaction.acquirerBin
transaction.acquirerCountryCode
paymentMethod.methodType
paymentMethod.paymentMethodId
paymentMethod.instrumentId
paymentMethod.cardBin
paymentMethod.cardLastFour
paymentMethod.expiryMonth
paymentMethod.expiryYear
paymentMethod.successfulRegistration
paymentMethod.registrationTime
paymentMethod.lastVerified

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 a 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",
            "threeDS": {
                "messageVersion": "2.2.0",
                "threeDSRequestorChallengeInd":"05"
            }
        }
    }
}

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

{
    "status": 200,
    "timestamp": 709513200,
    "data": {
        "customerId": "012345678",
        "action": "REVIEW",
        "score": 68,
        "source": "RAVELIN",
        "scoreId": "012345678-012345678-012345678",
        "transactionOptimisation": {
            "transactionId": "ea376fe5-cc16-4a6e-b553-88b1d559a56c",
            "action": "AUTHENTICATE",
            "actionSource": "CLIENT_RULE",
            "threeDSChallengePreference": "CHALLENGE_REQUESTED",
            "threeDS": {
                "messageVersion": "2.1.0",
                "threeDSRequestorChallengeInd":"03"
            }
        }
    }
}

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.

Important Fields
transaction.3ds

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": "1.0.2",
      "liabilityShifted": true,
      "eci": "5",
      "transStatus": "Y",
      "messageType": "ARes"
    }
  }
}

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.

Important Fields
transaction.gatewayReference
transaction.success
transaction.authCode
transaction.declineCode
transaction.cvvResultCode

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.

Important Fields
transaction.3ds
transaction.gatewayReference
transaction.success
transaction.authCode
transaction.declineCode
transaction.cvvResultCode

Configuration

The transaction optimisation recommendation depends on the payment fraud action calculated for the transaction and can be configured using our rules engine.

We recommend the following mapping of the payment fraud action and the route of a transaction:

Payment Fraud Action Recommended route
ALLOW These are low risk transactions. Try to avoid authentication where a bank allows it, or else target frictionless authentication through exemptions and richer data sharing.
REVIEW These are risky transactions. Send to authentication and ask for a challenge.
PREVENT Drop the transaction

Next steps

Test your transaction optimisation integration

Learn how to correctly handle transaction optimisation errors

Feedback

© Ravelin Technology Ltd. All rights reserved