Accept API Reference

Overview

Accept uses knowledge of Card Issuer 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:

1. Request an initial SCA 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 Accept 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

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.

Initial SCA Recommendation

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

Authentication Attempt

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

Authorisation Attempt

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

Webhooks

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.

Responses

SCA Recommendation

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:

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 useProtocolVersion field.

{
    "status": 200,
    "timestamp": 709513200,
    "data": {
        "recommendation": {
            "transactionId": "123-abc-XYZ",
            "authenticate": true,
            "useProtocolVersion": "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
        }
    }
}

SCA Recommendation and Fraud Score

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,
            "useProtocolVersion": "1.0.2"
        }
    }
}

Testing

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.

Configuration

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:

• recommend based on issuer intelligence
• recommend authentication
• recommend authorisation
• recommend no further action

The default configuration is shown below:

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.

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. 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,
            "useProtocolVersion": "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.