Capital One Enhanced Data Decisioning

availability

Use of the production Forward API is subject to eligibility.

Contact your Account Manager for more information or submit an inquiry to our Business Development team.

Capital One provides an Enhanced Decisioning Data endpoint which takes in additional transaction data to make better decisions at the time of authorization.

The Forward API can be used for making requests to Capital One's Enhanced Data Decisioning (EDD) endpoint.

Usage

At a minimum, users need to provide three pieces of information, in addition to the nonce identifying a payment instrument.

1. $amount: for specifying the purchase transaction amount
2. $currency: for specifying the currency for the transaction in ISO 4217 format
3. $correlation_id: a string token for uniquely identifying your transaction

To this we will add:

4. $additionalTransactionDataTimestamp: a string in ISO 8601 format of the UTC date-time we send the request
5. $bankIdentificationNumber: bin of payment method
6. $lastFourCardNumber: last 4 digits of payment instrument
7. $directDataSharePartnerId: our id with Capital One

Example call with these minimum required attributes:

curl https://forwarding.sandbox.braintreegateway.com/ \
  -H "Content-Type: application/json" \
  -X POST \
  -u "${BRAINTREE_PUBLIC_KEY}:${BRAINTREE_PRIVATE_KEY}" \
  -d '{
    "merchant_id": "'"$BRAINTREE_MERCHANT_ID"'",
    "payment_method_nonce": "fake-valid-nonce",
    "name": "Capital One EDD",
    "url": "https://api-it.capitalone.com/credit-cards/e-commerce/fraud-prevention/additional-transaction-data-references",
    "method": "POST",
    "data": {"amount": "1.00", "currency": "840", "correlation_id": "XXYYZZ"},
  }'

Returns:

{
  "additionalTransactionDataReferenceId": "7d36-d6c9-5fc9-96a2"
}

However, a user will likely send additional non-mandatory fields as part of their request. To do so, they should populate the override attribute with a body attribute, where the value of the body attribute is a JSON or XML string containing the optional attributes to be sent and their values. Override Documentation

note

Any data sent to us this way appear in our logs. Users should refrain from sending us sensitive data and customer PII.

Example of request passing optional orderData data

curl https://forwarding.sandbox.braintreegateway.com/ \
-H "Content-Type: application/json" \
-X POST \
-u "${BRAINTREE_PUBLIC_KEY}:${BRAINTREE_PRIVATE_KEY}" \
-d '{
  "merchant_id": "'"$BRAINTREE_MERCHANT_ID"'",
  "payment_method_nonce": "fake-valid-nonce",
  "name": "Capital One EDD",
  "override": {
    "body": {
      "orderData":{
        "itemCount": 5,
        "highestPriceItemCategory": "Bowling shoes",
        "isRecurringPurchase": true
      }
    }
  },
  "url": "https://api-it.capitalone.com/credit-cards/e-commerce/fraud-prevention/additional-transaction-data-references",
  "method": "POST",
  "data": {"amount": "1.00", "currency": "840", "correlation_id": "XXYYZZ"},
}'

See Capital One's API docs for full list of optional fields.

Errors

There are different errors you can potentially receive when making the request:

OAuth Errors

To make a request to Capital One's Enhanced Decisioning Data endpoint, Braintree first makes a request to get an OAuth token from Capital One. If we fail to obtain the OAuth token we will return an OAuth Error in the response body to your application. The body is a JSON structure with a format resembling this example:

{
  "error": "OAuth error",
  "message": {
    "oauth_error?": true,
    "oauth_status": 400,
    "error": "invalid_client"
  },
  "request-uuid": "a-unique-identifier-for-the-request"
}

See more about OAuth Error types and descriptions.

Common Request Errors

When something goes wrong with your request, the error code and description included in the response body will provide insight into the problem. Here is an example of what the response body would look like:

{
  "status": 401 
  "body": {
    "description":"The Authorization header token is invalid. Invalid access token",
    "code":101216
  }
}

See this table from Capital One that contains common error codes and descriptions.