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"
}
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 as an integer count of seconds, milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

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"
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 as an integer count of seconds, milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

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 as an integer count of seconds, milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

1512828988826

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",
      "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 as an integer count of seconds, milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

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 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"
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 as an integer count of seconds, milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

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 as an integer count of seconds, milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

1512828988826

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"
}
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 as an integer count of seconds, milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

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

One of: M, N, U, I, A, E, pass, fail, unavailable, unchecked, 0, 1, 2, 4, 8, P, S, 3, 5, 6, missing, issuer_not_certified, issuer_not_signed_up, not_checked, B, C, D, F, G, H, J, K, L, O, Q, R, T, V, W, X, Y, or Z.

"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"
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 as an integer count of seconds, milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

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 as an integer count of seconds, milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

1512828988826

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:

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
useProtocolVersion
string

The version of 3D Secure to attempt to use. This field is only present if authenticate is set to true

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

We have test card BINs which you can use to test your Accept integration. Sending a request with the paymentMethod.cardBin field set to one these test card BIN values will produce the responses listed in the table below. From this you can ensure your system handles the response accordingly.

Test Card BIN Response Example
"000001" Authenticate recommended "authenticate": true
"authorise": false
"000002" Authorise recommended "authenticate": false
"authorise": true
"000003" No further action recommended "authenticate": false
"authorise": false
"000004" Simulated Accept internal server error
See the Errors section for more details
"status": 500, message": "Internal Server Error"
or if requested with a fraud score:
"message": "Could not generate an SCA recommendation"

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:

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.

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.