Transaction Optimisation API

Overview

The Payments Services Directive 2 (PSD2) introduces new rules around Strong Customer Authentication (SCA) to make payments safer, more secure and protect consumers from fraud. This means most online payments in the EEA will require SCA. However the legislation also introduces SCA exemptions that aim to minimise friction when a transaction risk is low.

The goal with transaction optimisation is to understand how issuers are adapting to PSD2 and recommend the lowest friction route, whether the best course of action is to authenticate a customer using 3D Secure or whether you should proceed directly to authorisation, and which SCA Exemptions is best suited.

Authentication provides an extra level of security during checkout, however authenticating customers affects conversion - a large percentage of customers abandon checkout when asked to authenticate using 3DS. 3D Secure 2 (3DS2) introduces the option for frictionless authentication, support for SCA exemptions and sending more data elements on each transaction, which aims to improve the customer experience with a less disruptive authentication. Therefore it is preferable to only authenticate when you are concerned a customer is a fraudster, or when an issuer is going to enforce authentication anyway. The challenge is knowing whether an issuer is going to enforce authentication.

You could just attempt to avoid authentication by going directly to authorisation and use an SCA exemption, but if the issuer does enforce SCA you’ll get a soft decline and have to go back and authenticate the customer, and then perform a second authorisation. This may be undesirable because each attempt adds additional latency to the payment process.

Ravelin’s transaction optimisation will optimise your transaction routing for the best possible chance of success by avoiding unnecessary friction and maximising successful payment authorisations.


There are two steps to integrating with Ravelin’s transaction optimization:

  1. Request a transaction optimisation recommendation
    Send us details of a transaction and we will return a recommendation to start with either authentication or authorisation.

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

If you have any queries about integrating with transaction optimisation please don’t hesitate to ask us.

Flow

The flow diagram below shows all the possible routes a transaction could take during the payment flow, and the messages sent between you, Ravelin and your PSP.

Requests

The transaction optimisation uses the Core V2 API.

To identify a transaction to be handled by the transaction optimisation engine add the ?transactionOptimisation=true query parameter to the end of the request’s URL.

The transactionOptimisation=true must be used in conjunction with the score=true query parameter for requesting a payment fraud score. Link them with an ampersand: /v2/checkout?score=true&transactionOptimisation=true.

Transaction optimisation Recommendation

POST /v2/checkout?score=true&transactionOptimisation=true

The transaction optimisation recommendation can be requested by sending a transaction to the /v2/checkout.

This must be done before starting authentication or authorisation.

These are the fields relevant to an initial transaction optimisation recommendation request. These are a subset of the fields available on our Core V2 API /v2/checkout and /v2/pretransaction endpoints.

{
  "timestamp": 1512828988826,
  "customerId": "abc-123-ZYZ",
  "transaction": {
    "transactionId": "123-abc-XYZ",
    "time": 1480340580291,
    "amount": 1000,
    "currency": "GBP",
    "gateway": "braintree",
    "mcc": "0742",
    "mid": "mid-1",
    "acquirerId": "adyen",
    "acquirerBin": "123456",
    "acquirerCountryCode": "GBR"
  },
  "paymentMethod": {
    "methodType": "card",
    "paymentMethodId": "pm-abc123",
    "instrumentId": "fp_abc123",
    "cardBin": "535522",
    "cardLastFour": "0001",
    "expiryMonth": 7,
    "expiryYear": 2020,
    "successfulRegistration": true,
    "registrationTime": 1512828988826,
    "lastVerified": 1512828988826
  },
  "paymentMethodId": "pm-abc123"
}
Name Type Description Example
timestamp
required
integer

The time at which this data payload was valid. When sending events in realtime, this will usually be 'now'. This is used to merge data that arrives out-of-order.

A unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

1512828988826
customerId
required
string

The ID of the customer whose order is being submitted or updated. (See customers.)

"abc-123-ZYZ"
paymentMethodId
required
string

The ID of the primary payment method to be charged in completing the checkout process. Mutually exclusive with paymentMethod.

"pm-abc123"
transaction
required
object

A transaction is an attempt to charge a payment method to pay or be refunded for an order. You can think of it as the data included in your request from your application to a payment gateway. One order could have many transactions associated with it: e.g. pay part of balance with a card, pay part of balance with a voucher.

Hide definition
Name Type Description Example
transactionId
important
string

A unique identifier for the transaction.

Required when sending a transaction before talking to the PSP, because the alternative gatewayReference cannot be known. If telling Ravelin about the transaction after processing it (as with a refund, for example) transactionId can be omitted in place of gateway and gatewayReference.

"123-abc-XYZ"
time
important
integer

The time that the transaction is being attempted.

A unix timestamp as an integer count of milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

1480340580291
amount
important
integer

The amount to be charged to the payment method, in the currency's basic units.

1000
currency
optional
string

The currency of the amount of this transaction, as an ISO 4217 currency code.

Pattern: ^[a-zA-Z]{3}$
"GBP"
gateway
important
string

The gateway responsible for processing the transaction. Used to link to chargebacks. Usually only available after attempting the payment.

"braintree"
mcc
important
string

The Merchant Category Code associated with the transaction.

"0742"
mid
optional
string

The merchant ID that the transaction was processed under. The merchant ID is used to identify you to your acquirer and the financial institutions that will be involved in processing the transaction.

"mid-1"
acquirerId
optional
string

The acquirer is a financial institution with whom the merchant has a bank account.

"adyen"
acquirerBin
optional
string

The BIN (Bank Identification Number) of the acquirer.

"123456"
acquirerCountryCode
optional
string

The three letter country code of the country in which your acquirer will settle the payment.

"GBR"
paymentMethod
required
object

The payment method to be charged in completing the checkout process. Mutually exclusive with paymentMethodId.

Hide definition
Name Type Description Example
methodType
required
string

Card payment method indicator.

One of: card, creditcard, or debitcard.

"card"
paymentMethodId
required
string

A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.

"pm-abc123"
cardBin
required
string

The first six digits of the card number/PAN. The Bank Identification Number (BIN), recently more commonly known as the Issuer Identification Number (IIN).

Given the BIN, Ravelin will populate the issuer, country of issuance, and card type on your behalf.

"535522"
instrumentId
important
string

A unique identifier for the physical card, shared between users. Used to link cards in Connect. Must not be a hash of the PAN.

If you use multiple PSPs who each generate their own equivalent of an instrumentId, you should consider prefixing their values to indicate their origin to avoid collisions. Common examples include Stripe's fingerprint, or Braintree's unique_number_identifier).

"fp_abc123"
pan
pci, optional
string

The full Primary Account Number of the card. Used by Ravelin to determine the instrumentId for this card. If specified, you do not need to provide instrumentId, cardBin or cardLastFour.

Only PCI DSS SAQ-D certified merchants should submit the PAN to Ravelin. You must not send requests containing this field to api.ravelin.com, and must instead use pci.ravelin.com.

Please see our PCI DSS documentation for more information.

4111111111111111
cardLastFour
important
string

The last four digits of the card number/PAN.

"0001"
expiryMonth
important
integer

The expiry month of the card.

7
expiryYear
important
integer

The expiry year of the card.

2020
successfulRegistration
optional
boolean

Whether the card was successfully registered with your gateway/PSP.

true
registrationTime
important
integer

The time that the card was saved to the customer's account. (Not the card start date.)

A unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

1512828988826
lastVerified
optional
integer

The time at which the payment method was last verified by the customer. An example mechanism would be a random amount charged to the customer's card that they can confirm the amount of.

A unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

1512828988826

Authentication Attempt

POST /v2/checkout
POST /v2/transaction

After you have attempted to authenticate a customer update us on the outcome.

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

These fields are a subset of the fields available on our Core V2 API /v2/checkout and /v2/transaction endpoints.

{
  "timestamp": 1512828988826,
  "customerId": "abc-123-ZYZ",
  "transaction": {
    "transactionId": "123-abc-XYZ",
    "3ds": {
      "attempted": true,
      "challenged": true,
      "success": true,
      "startTime": 1479231064910,
      "endTime": 1479231064919,
      "timedOut": false,
      "version": "1.0.2",
      "liabilityShifted": true,
      "eci": "5",
      "transStatus": "Y",
      "transStatusReason": "01",
      "messageType": "ARes",
      "iReqCode": "55"
    },
    "time": 1480340580291,
    "amount": 1000,
    "currency": "GBP",
    "gateway": "braintree",
    "mcc": "0742",
    "mid": "mid-1",
    "acquirerId": "adyen",
    "acquirerBin": "123456",
    "acquirerCountryCode": "GBR"
  },
  "paymentMethod": {
    "methodType": "card",
    "paymentMethodId": "pm-abc123",
    "instrumentId": "fp_abc123",
    "cardBin": "535522",
    "cardLastFour": "0001",
    "expiryMonth": 7,
    "expiryYear": 2020,
    "successfulRegistration": true,
    "registrationTime": 1512828988826,
    "lastVerified": 1512828988826
  },
  "paymentMethodId": "pm-abc123"
}
Name Type Description Example
timestamp
required
integer

The time at which this data payload was valid. When sending events in realtime, this will usually be 'now'. This is used to merge data that arrives out-of-order.

A unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

1512828988826
customerId
required
string

The ID of the customer whose order is being submitted or updated. (See customers.)

"abc-123-ZYZ"
paymentMethodId
required
string

The ID of the primary payment method to be charged in completing the checkout process. Mutually exclusive with paymentMethod.

"pm-abc123"
transaction
required
object

A transaction is an attempt to charge a payment method to pay or be refunded for an order. You can think of it as the data included in your request from your application to a payment gateway. One order could have many transactions associated with it: e.g. pay part of balance with a card, pay part of balance with a voucher.

Hide definition
Name Type Description Example
transactionId
important
string

A unique identifier for the transaction.

Required when sending a transaction before talking to the PSP, because the alternative gatewayReference cannot be known. If telling Ravelin about the transaction after processing it (as with a refund, for example) transactionId can be omitted in place of gateway and gatewayReference.

"123-abc-XYZ"
3ds
optional
object

Details on how 3D Secure (3DS) was used to authenticate the transaction.

Show definition
time
important
integer

The time that the transaction is being attempted.

A unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

1480340580291
amount
important
integer

The amount to be charged to the payment method, in the currency's basic units.

1000
currency
optional
string

The currency of the amount of this transaction, as an ISO 4217 currency code.

Pattern: ^[a-zA-Z]{3}$
"GBP"
gateway
important
string

The gateway responsible for processing the transaction. Used to link to chargebacks. Usually only available after attempting the payment.

"braintree"
mcc
important
string

The Merchant Category Code associated with the transaction.

"0742"
mid
optional
string

The merchant ID that the transaction was processed under. The merchant ID is used to identify you to your acquirer and the financial institutions that will be involved in processing the transaction.

"mid-1"
acquirerId
optional
string

The acquirer is a financial institution with whom the merchant has a bank account.

"adyen"
acquirerBin
optional
string

The BIN (Bank Identification Number) of the acquirer.

"123456"
acquirerCountryCode
optional
string

The three letter country code of the country in which your acquirer will settle the payment.

"GBR"
paymentMethod
required
object

The payment method to be charged in completing the checkout process. Mutually exclusive with paymentMethodId.

Hide definition
Name Type Description Example
methodType
required
string

Card payment method indicator.

One of: card, creditcard, or debitcard.

"card"
paymentMethodId
required
string

A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.

"pm-abc123"
cardBin
required
string

The first six digits of the card number/PAN. The Bank Identification Number (BIN), recently more commonly known as the Issuer Identification Number (IIN).

Given the BIN, Ravelin will populate the issuer, country of issuance, and card type on your behalf.

"535522"
instrumentId
important
string

A unique identifier for the physical card, shared between users. Used to link cards in Connect. Must not be a hash of the PAN.

If you use multiple PSPs who each generate their own equivalent of an instrumentId, you should consider prefixing their values to indicate their origin to avoid collisions. Common examples include Stripe's fingerprint, or Braintree's unique_number_identifier).

"fp_abc123"
pan
pci, optional
string

The full Primary Account Number of the card. Used by Ravelin to determine the instrumentId for this card. If specified, you do not need to provide instrumentId, cardBin or cardLastFour.

Only PCI DSS SAQ-D certified merchants should submit the PAN to Ravelin. You must not send requests containing this field to api.ravelin.com, and must instead use pci.ravelin.com.

Please see our PCI DSS documentation for more information.

4111111111111111
cardLastFour
important
string

The last four digits of the card number/PAN.

"0001"
expiryMonth
important
integer

The expiry month of the card.

7
expiryYear
important
integer

The expiry year of the card.

2020
successfulRegistration
optional
boolean

Whether the card was successfully registered with your gateway/PSP.

true
registrationTime
important
integer

The time that the card was saved to the customer's account. (Not the card start date.)

A unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

1512828988826
lastVerified
optional
integer

The time at which the payment method was last verified by the customer. An example mechanism would be a random amount charged to the customer's card that they can confirm the amount of.

A unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

1512828988826

Authorisation Attempt

POST /v2/checkout
POST /v2/transaction

After you have attempted to authorise a transaction update us on the outcome.

These are the fields relevant to an authorisation attempt request. These are a subset of the fields available on our Core V2 API /v2/checkout and /v2/transaction endpoints.

{
  "timestamp": 1512828988826,
  "customerId": "abc-123-ZYZ",
  "transaction": {
    "transactionId": "123-abc-XYZ",
    "time": 1480340580291,
    "amount": 1000,
    "currency": "GBP",
    "type": "auth_capture",
    "gateway": "braintree",
    "gatewayReference": "123-abc-XYZ",
    "success": false,
    "declineCode": "1234",
    "authCode": "1234",
    "cvvResultCode": "pass",
    "mcc": "0742",
    "mid": "mid-1",
    "acquirerId": "adyen",
    "acquirerBin": "123456",
    "acquirerCountryCode": "GBR"
  },
  "paymentMethod": {
    "methodType": "card",
    "paymentMethodId": "pm-abc123",
    "instrumentId": "fp_abc123",
    "cardBin": "535522",
    "cardLastFour": "0001",
    "expiryMonth": 7,
    "expiryYear": 2020,
    "successfulRegistration": true,
    "registrationTime": 1512828988826,
    "lastVerified": 1512828988826
  },
  "paymentMethodId": "pm-abc123"
}
Name Type Description Example
timestamp
required
integer

The time at which this data payload was valid. When sending events in realtime, this will usually be 'now'. This is used to merge data that arrives out-of-order.

A unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

1512828988826
customerId
required
string

The ID of the customer whose order is being submitted or updated. (See customers.)

"abc-123-ZYZ"
paymentMethodId
required
string

The ID of the primary payment method to be charged in completing the checkout process. Mutually exclusive with paymentMethod.

"pm-abc123"
transaction
required
object

A transaction is an attempt to charge a payment method to pay or be refunded for an order. You can think of it as the data included in your request from your application to a payment gateway. One order could have many transactions associated with it: e.g. pay part of balance with a card, pay part of balance with a voucher.

Hide definition
Name Type Description Example
transactionId
important
string

A unique identifier for the transaction.

Required when sending a transaction before talking to the PSP, because the alternative gatewayReference cannot be known. If telling Ravelin about the transaction after processing it (as with a refund, for example) transactionId can be omitted in place of gateway and gatewayReference.

"123-abc-XYZ"
time
important
integer

The time that the transaction is being attempted.

A unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

1480340580291
amount
important
integer

The amount to be charged to the payment method, in the currency's basic units.

1000
currency
optional
string

The currency of the amount of this transaction, as an ISO 4217 currency code.

Pattern: ^[a-zA-Z]{3}$
"GBP"
type
important
string

The type of transaction interacting with the payment method.

  • auth: An auth transaction is used to reserve funds on the customer's card without yet deducting it. Useful to verify whether the customer has sufficient funds in their account and reserving a limit when the final order price cannot be known. Sometimes known as a pre-auth.
  • capture: A capture transaction is used to immediately deduct authorised funds (up to the amount auth'd) from a customer's card.
  • auth_capture: A simultaneous combination of auth and capture in one transaction, for when there is no need to separately auth then capture. Typical with straight-forward "buy now"-style checkout.
  • refund: A refund transaction credit's a customer's payment method. If you do not know the payment method ID you are refunding to, but do know the original transaction, consult refud transaction payment methods.
  • void: A void transaction is the explicit discarding of authorization of funds.
  • use, redeem: Deprecated. See voucherRedemption on /v2/chargeback or /v2/paymentmethod/voucher.

One of: preauth, auth, capture, auth_capture, void, refund, redeem, or use.

"auth_capture"
gateway
important
string

The gateway responsible for processing the transaction. Used to link to chargebacks. Usually only available after attempting the payment.

"braintree"
gatewayReference
important
string

The reference given to this transaction by the processing gateway. Used to link to chargebacks. Usually only available after attempting the payment.

"123-abc-XYZ"
success
important
boolean

Whether the transaction succesfully completed with no error.

false
declineCode
important
string

the decline code from the payment gateway, if applicable.

"1234"
authCode
optional
string

A code returned from the payment gateway after an attempt to charge, if applicable.

"1234"
cvvResultCode
optional
string

The result of CVV verification from the issuer, compatible with common PSP codes.

"pass"
mcc
important
string

The Merchant Category Code associated with the transaction.

"0742"
mid
optional
string

The merchant ID that the transaction was processed under. The merchant ID is used to identify you to your acquirer and the financial institutions that will be involved in processing the transaction.

"mid-1"
acquirerId
optional
string

The acquirer is a financial institution with whom the merchant has a bank account.

"adyen"
acquirerBin
optional
string

The BIN (Bank Identification Number) of the acquirer.

"123456"
acquirerCountryCode
optional
string

The three letter country code of the country in which your acquirer will settle the payment.

"GBR"
paymentMethod
required
object

The payment method to be charged in completing the checkout process. Mutually exclusive with paymentMethodId.

Hide definition
Name Type Description Example
methodType
required
string

Card payment method indicator.

One of: card, creditcard, or debitcard.

"card"
paymentMethodId
required
string

A unique identifier for this payment, specific to this customer. Two customers should not use the same paymentMethodId.

"pm-abc123"
cardBin
required
string

The first six digits of the card number/PAN. The Bank Identification Number (BIN), recently more commonly known as the Issuer Identification Number (IIN).

Given the BIN, Ravelin will populate the issuer, country of issuance, and card type on your behalf.

"535522"
instrumentId
important
string

A unique identifier for the physical card, shared between users. Used to link cards in Connect. Must not be a hash of the PAN.

If you use multiple PSPs who each generate their own equivalent of an instrumentId, you should consider prefixing their values to indicate their origin to avoid collisions. Common examples include Stripe's fingerprint, or Braintree's unique_number_identifier).

"fp_abc123"
pan
pci, optional
string

The full Primary Account Number of the card. Used by Ravelin to determine the instrumentId for this card. If specified, you do not need to provide instrumentId, cardBin or cardLastFour.

Only PCI DSS SAQ-D certified merchants should submit the PAN to Ravelin. You must not send requests containing this field to api.ravelin.com, and must instead use pci.ravelin.com.

Please see our PCI DSS documentation for more information.

4111111111111111
cardLastFour
important
string

The last four digits of the card number/PAN.

"0001"
expiryMonth
important
integer

The expiry month of the card.

7
expiryYear
important
integer

The expiry year of the card.

2020
successfulRegistration
optional
boolean

Whether the card was successfully registered with your gateway/PSP.

true
registrationTime
important
integer

The time that the card was saved to the customer's account. (Not the card start date.)

A unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

1512828988826
lastVerified
optional
integer

The time at which the payment method was last verified by the customer. An example mechanism would be a random amount charged to the customer's card that they can confirm the amount of.

A unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

1512828988826

Update at the end of the transaction

POST /v2/checkout
POST /v2/transaction

You can also update us on the outcome of a transaction only at the end and send us the relevant fields mentioned both at the Authentication Attempt and Authorisation Attempt sections.

Responses

Transaction Optimisation Recommendation

When you send a request asking for a transaction optimisation recommendation, we will return a recommendation to either perform authentication or proceed directly to authorisation, and which SCA Exemption to use if applicable.

The transaction optimisation recommendation will be in a transactionOptimisation JSON object in the data field in the body of the response, and uses the following schema:

Name Type Description Example
transactionId
string

Identifier for this transaction, as supplied by the client

"123-abc-XYZ"
action
string

Whether the transaction should be authenticated or sent straight to authorisation. One of AUTHENTICATE or AUTHORISE

AUTHENTICATE
exemption
string

The SCA exemption type to request for the transaction. One of TRANSACTION_RISK_ANALYSIS or LOW_VALUE

TRANSACTION_RISK_ANALYSIS
threeDSChallengePreference
string

The preference for whether or not a 3DS challenge should be performed. This field is only present if action is AUTHENTICATE . One of NO_PREFERENCE, NO_CHALLENGE_REQUESTED, CHALLENGE_REQUESTED or CHALLENGE_REQUESTED_AS_MANDATE

NO_PREFERENCE
source
string

The source of the given recommendation.

"CLIENT_RULE"
rules
object

Indicates which rules were triggered to cause the given recommendation

threeDS
object

A 3DS object with extra 3DS details. Will include:

  • messageVersion - The version of 3DS to attempt to use
  • threeDSRequestorChallengeInd - The 3DS Requestor Challenge Indicator value following the EMVCo specification.
The 3DS object is not yet live.

Send to 3D Secure for Authentication with Transaction Risk Analysis exemption - Response Example

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

Send to 3D Secure for Authentication without an SCA exemption - Response Example

{
    "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"
            }
        }
    }
}

Proceed to Authorisation with Low Value exemption - Response Example

{
    "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"
        }
    }
}

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

Errors

Our platform has been designed to be resilient to failure. However, in the unlikely event of an error we will attempt to continue to process your request as completely as possible. When requesting a transaction optimisation recommendation you also have to request a fraud score, which means errors could occur in the different platforms.

If an error occurs when generating a transaction optimisation recommendation but not during fraud scoring we will return the fraud score along with a message stating: “Could not generate transaction optimisation recommendation”.

{
    "status": 200,
    "message": "Could not generate transaction optimisation recommendation",
    "timestamp": 709513200,
    "data": {
        "customerId": "012345678",
        "action": "REVIEW",
        "score": 68,
        "source": "NETWORK",
        "scoreId": "012345678-012345678-012345678"
    }
}

If an error occurs during fraud scoring we will not be able to return a transaction optimisation recommendation. However in most cases we will be able to return a cached fraud score, as mentioned in our cached scores section for the Core API. In the rare cases where there is a failure returning a cached fraud score the API returns the conventional HTTP response codes used by our Core V2 API.

For guidance on how to best respond to error codes, please consult our Error Handling documentation or contact a Ravelin engineer.