Accept uses knowledge of the card issuer’s behaviour to recommend whether the best course of action is to authenticate a customer using 3D Secure or whether you should proceed directly to authorisation.
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. 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, but if the issuer does enforce it you’ll get a soft decline and have to go back and authenticate the customer, and then perform a second authorisation. This is undesirable because you may be charged per authorisation attempt, and each attempt adds additional latency to the payment process.
Accept will optimise your transaction routing for the best possible chance of success.
Accept can be used with Ravelin Detect to also take into account the risk profile of the transaction using Transaction Risk Analysis.
There are two steps to integrating with Ravelin Accept:
Request an initial SCA recommendation
Send us details of a transaction and we will return a recommendation to start with either authentication or authorisation.
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 Accept please don’t hesitate to ask us.
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.
In order to make it easy to use Accept alongside our Detect fraud platform, Accept uses the Core V2 API.
To identify a transaction to be handled by Accept add the ?sca_recommend=true
query parameter to the end of the request’s URL.
The sca_recommend=true
query parameter can be used in conjunction with the score=true
query parameter for requesting a fraud score.
Link them with an ampersand: /v2/checkout?score=true&sca_recommend=true
.
POST
/v2/checkout?sca_recommend=true
POST
/v2/pretransaction?sca_recommend=true
An initial SCA recommendation can be requested by sending a transaction to either the /v2/checkout or /v2/pretransaction endpoints.
This must be done before starting authentication or authorisation.
These are the fields relevant to an initial Accept 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 |
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. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymentMethod
required
|
object |
The payment method to be charged in completing the checkout process. Mutually exclusive with paymentMethodId. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
POST
/v2/checkout?sca_recommend=true
POST
/v2/transaction?sca_recommend=true
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,
"authenticationValue": "MDEyMzQ1Njc4OTAxMjM0NTY3ODk=",
"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 |
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. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymentMethod
required
|
object |
The payment method to be charged in completing the checkout process. Mutually exclusive with paymentMethodId. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
POST
/v2/checkout?sca_recommend=true
POST
/v2/transaction?sca_recommend=true
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 |
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. |
||
paymentMethod
required
|
object |
The payment method to be charged in completing the checkout process. Mutually exclusive with paymentMethodId. |
||
Our preferred method of receiving transaction updates is via our /v2/checkout
and /v2/transaction
endpoints as explained above,
however we may also be able to receive authentication and authorisation webhook notifications directly from your payment gateway.
Please speak to your Ravelin account manager about the possibility of this for your gateway.
When you send a request to Accept, we will return an SCA recommendation to either perform authentication, proceed to authorisation or perform no further action on the transaction. This will be based on both our issuer intelligence and on previous authentication and authorisation events for the transaction.
The SCA recommendation will be in a recommendation
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" |
authenticate |
boolean | Should this customer be sent to 3D Secure to be authenticated |
true |
authorise |
boolean | Should you proceed to authorise the transaction with the issuing bank |
false |
use3DSVersion |
string | The version of 3D Secure to attempt to use. This field is only present if |
"2.1.0" |
Send to 3D Secure for Authentication - Response Example
If we recommend authentication we will also recommend a version of 3D Secure to use in the use3DSVersion
field.
{
"status": 200,
"timestamp": 709513200,
"data": {
"recommendation": {
"transactionId": "123-abc-XYZ",
"authenticate": true,
"use3DSVersion": "1.0.2",
"authorise": false
}
}
}
Proceed to Authorisation - Response Example
{
"status": 200,
"timestamp": 709513200,
"data": {
"recommendation": {
"transactionId": "123-abc-XYZ",
"authenticate": false,
"authorise": true
}
}
}
Take no further action with this transaction - Response Example
The transaction has completed successfully, or authentication or authorisation have failed.
{
"status": 200,
"timestamp": 709513200,
"data": {
"recommendation": {
"transactionId": "123-abc-XYZ",
"authenticate": false,
"authorise": false
}
}
}
If you have requested both an Accept SCA recommendation and a fraud score we will return the fraud score details alongside the SCA recommendation.
{
"status": 200,
"timestamp": 709513200,
"data": {
"customerId": "012345678",
"action": "REVIEW",
"score": 68,
"source": "NETWORK",
"scoreId": "012345678-012345678-012345678",
"recommendation": {
"transactionId": "123-abc-XYZ",
"authenticate": true,
"authorise": false,
"use3DSVersion": "1.0.2"
}
}
}
You can test your Accept integration by sending a request with either the paymentMethod.cardBin
field
set to a test card BIN value or the paymentMethod.paymentMethodId
field
set to a value which has a test payment method ID suffix appended.
These requests will always produce the same corresponding “authenticate”, “authorise” or “no action required” recommendation. You can then ensure your system handles the response accordingly.
The test card BINs and test payment method ID suffixes are shown in the table below.
Test Card BIN | Test Payment Method ID Suffix | Recommendation | Example Response |
---|---|---|---|
"000001" |
"_accept_test_authenticate" |
Authenticate |
"authenticate": true "authorise": false
|
"000002" |
"_accept_test_authorise" |
Authorise |
"authenticate": false "authorise": true
|
"000003" |
"_accept_test_none" |
No further action |
"authenticate": false "authorise": false
|
We can configure Accept for you so that we always make the same initial SCA recommendation depending on the fraud action we’ve calculated for you.
The possible SCA recommendations we can configure are:
The default configuration is shown below:
Fraud Action | Default SCA Recommendation |
---|---|
ALLOW | Recommend based on issuer intelligence |
REVIEW | Recommend authentication |
PREVENT | Recommend no further action |
We can change your configuration for you at your request.
Note, your configuration settings only affect your initial SCA recommendation. SCA recommendations after you’ve performed an authentication or authorisation will no longer take the fraud action into account.
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. If you request both an SCA recommendation and a fraud score, and an error occurs which only affects one platform, we will still return the response from the unaffected platform.
If an error occurs during fraud scoring but not in Accept we will still return the SCA recommendation along with a message stating: “Could not generate a fraud score”.
{
"status": 200,
"message": "Could not generate a fraud score",
"timestamp": 709513200,
"data": {
"recommendation": {
"transactionId": "123-abc-XYZ",
"authenticate": true,
"authorise": false,
"use3DSVersion": "1.0.2"
}
}
}
If an error occurs in Accept but not fraud scoring we will return the fraud score along with a message stating: “Could not generate an SCA recommendation”.
{
"status": 200,
"message": "Could not generate an SCA recommendation",
"timestamp": 709513200,
"data": {
"customerId": "012345678",
"action": "REVIEW",
"score": 68,
"source": "NETWORK",
"scoreId": "012345678-012345678-012345678"
}
}
Otherwise Accept uses the same 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.