There are two steps to integrate with transaction optimisation:
Request a recommendation
Send us details of a transaction. We will return a recommendation to either perform authentication or authorisation.
Update us with authentication and authorisation attempts
This could be after each attempt or at the end of the transaction.
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 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": "REVIEW",
"score": 68,
"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"
}
}
}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": "2.2.1",
"liabilityShifted": true,
"eci": "5",
"transStatus": "Y",
"messageType": "ARes"
}
}
}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"
}
}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 |
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 |
Test your transaction optimisation integration
Learn how to correctly handle transaction optimisation errors
Was this page helpful?