Additions Coming Soon!

The Apruvd API V3 documentation is a work in progress. It currently covers all the information necessary to begin submitting orders for review via the API. Topics covered:

More topics coming soon:

Integration Guide - HTTPS API

Introduction

The Apruvd API exposes four simple functions. These allow clients to submit transactions for review and to later update, cancel, or request the review status of their transactions.

API Keys

To use the Apruvd API, a valid set of API keys must be submitted as basic authentication on each request. To create or delete API keys, please visit your profile. Your keys will be automatically downloaded into a file called apiKeys.properties. Keep this file in a secure location, and never share your API Secret with anyone.

For best security practices, it is strongly recommended that you create new API keys, and delete any old ones, at least once per 30 days.

Security

To harmonize security considerations and ease of use, we only require basic authentication over HTTPS. We maintain this policy primarily because we do not accept especially sensitive information, such as credit card PANs or other data protected by the PCI-DSS, as well as to simplify the integration process.

A Note about Security

We always want to implement the right security measures to meet clients' needs. If you would like to discuss additional security features for your account, such as OAuth, multi-factor auth, two-way TLS, etc, please contact our API development team and we will be happy to work with you.

The Apruvd database server only accepts inbound traffic from Apruvd application servers. Its databases are encrypted at rest.

Requests & Responses

Requests are sent to https://app.apruvd.com/api/{endpoint} and include a set of API keys in the basic auth header. POST data can have either the application/json or the application/x-www-form-urlencoded MIME type.

Responses are returned in application/json format and include informative HTTP status codes and, in most applicable cases, an error message in the response body. Here is an example using cURL:

cURL -X POST \
     -u "$API_KEY_ID:$API_KEY_SECRET" \
        "https://app.apruvd.com/api/transactions/submit/"
POST /api/transactions/submit/ HTTP/1.1
Host: app.apruvd.com
Authorization: Basic $BASE64_ENCODED_API_KEYS
Accept: */*

HTTP/1.1 403 FORBIDDEN
Content-Type: application/json

{"error": "Invalid or disabled credentials"}

Data & Object Structure

Transaction Objects

Legend

Shipping data are only required if an item is being shipped.

Required
One Required
Recommended
Default if Absent
Attribute Description Required Data Type Validated
mode Review Mode enum Yes
type Transaction Type enum Yes
total Amount Charged decimal Yes
currency Currency Charged enum (ISO 4217) Yes
order_num Your Unique Internal ID string(25) No
ip IPv4 Address string(39) Yes
email Email Address string(254) Yes
billing_phone Phone Number string(25) No
cc_name Account/Cardholder First Name string(50) No
cc_name_2 Account/Cardholder Last Name string(50) No
first_six First 6 Digits of CC integer Yes
last_four Last 4 Digits of CC integer Yes
avs AVS Response enum (Values) Yes
cvv CVV Response enum (Values) Yes
auth_attempts CC Auth Attempts integer Yes
billing_first_name Billing First Name string(100) No
billing_last_name Billing Last Name string(100) No
billing_company Billing Company string(100) No
billing_address_1 Billing Address Line 1 string(255) No
billing_address_2 Billing Address Line 2 string(255) No
billing_city Billing City string(100) No
billing_postal Billing Postal/ZIP Code string(25) No
billing_state Billing State string(50) No
billing_region Billing Region string(50) No
billing_country Billing Country string(100) No
shipping_email Shipping Email string(254) Yes
egc_recipient E-Gift Card Recipient Email string(254) Yes
shipping_phone Shipping Phone Number string(25) No
shipping_first_name Shipping First Name string(100) No
shipping_last_name Shipping Last Name string(100) No
shipping_company Shipping Company string(100) No
shipping_address_1 Shipping Address Line 1 string(255) No
shipping_address_2 Shipping Address Line 2 string(255) No
shipping_city Shipping City string(100) No
shipping_postal Shipping Postal/ZIP Code string(25) No
shipping_state Shipping State string(50) No
shipping_region Shipping Region string(50) No
shipping_country Shipping Country string(100) No
cart_contents Cart Contents JSON (Structure) Yes
rep_email Representative Email string(254) Yes
additional_1 Additional Notes 1 text No
additional_2 Additional Notes 2 text No
additional_3 Additional Notes 3 text No

AVS & CVV Response Values

Currently Accepted Values

As systems like AVS and CVV change, we are adding new values to our accepted choices regularly. Please contact us if you would like to request that we add any other values you might need support for.

AVS CVV
X, Y, A, W, Z, N, U, R, E, S, D, M, B, P, C, I, G M, N, P, S, U
(Chase) I1, I2, I3, I4, I5, I6, I7, I8, IG, IU, ID, IE, IS, IA, IB, IC, IP
(Chase) N1, N2, A1, A3, A4, A7, B3, B4, B7, B8, V
'' (empty string)

Cart Contents (JSON)

Expected Format

The expected structure of this JSON field is a list of objects, each with three required keys and one optional key. The extra key, an object, is freeform and has no required structure.

Key Required for Each Entry Data Type
item string(250)
quantity integer
is_high_risk boolean
extra object

Example input:

[
  {
    "item": "Simple Widget",
    "is_high_risk": false,
    "quantity": 1
  },
  {
    "item": "High-Fraud Widget",
    "is_high_risk": true,
    "quantity": 1
  },
  {
    "item": "Widget with extra description",
    "is_high_risk": true,
    "quantity": 1,
    "extra": {
      "link": "https://www.example.com/products/productidentifier/",
      "in_stock": false
  },
]

Responses & Callbacks

Content Type

Responses and callbacks use application/json as the HTTP Content-Type. Below is the data structure that you can anticipate in parsing the objects returned by the API and the asynchronous callbacks.

Attribute Description Data Type Info
transaction_id Apruvd Transaction No. integer Auto-incrementing
order_num Your Order ID string(25)
risk_grade Apruvd Risk Grade string(2) enum
status Apruvd Status string(9) enum
canceled Order Canceled by You boolean
high_risk Order is High Risk boolean
analysis Detailed Risk Analysis object Customizable
ip_is_high_risk Element of analysis boolean
email_is_high_risk Element of analysis boolean
cc_is_from_bill_country Element of analysis boolean
ip_is_in_bill_country Element of analysis boolean
cc_is_prepaid Element of analysis boolean
ship_addr_is_high_risk Element of analysis boolean

Responses & Callbacks

Content Type

Responses and callbacks use application/json as the HTTP Content-Type. Below is the data structure that you can anticipate in parsing the objects returned by the API and the asynchronous callbacks.

Attribute Description Data Type Info
transaction_id Apruvd Transaction No. integer Auto-incrementing
order_num Your Order ID string(25)
risk_grade Apruvd Risk Grade string(2) enum
status Apruvd Status string(9) enum
canceled Order Canceled by You boolean
high_risk Order is High Risk boolean
analysis Detailed Risk Analysis object Customizable
ip_is_high_risk Element of analysis boolean
email_is_high_risk Element of analysis boolean
cc_is_from_bill_country Element of analysis boolean
ip_is_in_bill_country Element of analysis boolean
cc_is_prepaid Element of analysis boolean
ship_addr_is_high_risk Element of analysis boolean

Functions


Submit a Transaction

Endpoint
transactions/submit/
Full URL
https://app.apruvd.com/api/transactions/submit/
Method
POST

Example using cURL:

cURL -X POST \
     -u "$API_KEY_ID:$API_KEY_SECRET" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json;charset=UTF-8" \
     -d '{
           "mode":"Live",
           "type":"Ecommerce",
           "total":123.45,
           "currency":"USD",
           "order_num":"12345",
           "ip":"112.118.212.218",
           "email":"example@email.com",
           "billing_phone":"1 (480) 555-1234",
           "cc_name":"JOHN",
           "cc_name_2":"DOE",
           "first_six":"417420",
           "last_four":"1234",
           "billing_first_name":"John",
           "billing_last_name":"Doe",
           "billing_address_1":"123 N Main St.",
           "billing_address_2":"Ste 300",
           "billing_city":"New York",
           "billing_state":"NY",
           "billing_postal":"10001",
           "billing_country":"United States",
           "shipping_first_name":"Jane",
           "shipping_last_name":"Doe",
           "shipping_address_1":"321 S Main St.",
           "shipping_address_2":"#200",
           "shipping_city":"New York",
           "shipping_state":"NY",
           "shipping_postal":"10002",
           "shipping_country":"United States"
         }' \
        "https://app.apruvd.com/api/transactions/submit/"
POST /api/transactions/submit/ HTTP/1.1
Host: app.apruvd.com
Authorization: Basic $BASE64_ENCODED_API_KEYS
Accept: application/json

HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "transaction_id":1,
  "status":"Reviewing",
  "risk_grade":"A+"
}

It is strongly recommended that you configure a callback_url for your account, which can be set in your profile. This URL should accept application/json data and perform whatever internal updates you prefer, to make a record that the order has been Approved or Declined. A callback from our server to yours would look like this if performed via cURL:

cURL -X POST \
     -d '{
           "transaction_id":1,
           "status":"Approved",
           "notes":"Customer is friends with recipient"
         }' \
     "https://your.domain.com/your/endpoint/"

Check a Transaction's Status

If, instead of setting up a callback endpoint, you would prefer to periodically request transaction updates, use this function.

Endpoint
transactions/status/?transaction_id={transaction_id}
Alternative Use
transactions/status/?order_num={order_num}
Full URL
https://app.apruvd.com/api/transactions/status/?transaction_id={transaction_id}
Method
GET

Example using cURL:

cURL -X GET \
     -u "$API_KEY_ID:$API_KEY_SECRET" \
     -H "Accept: application/json" \
        "https://app.apruvd.com/api/transactions/status/?transaction_id=1"
GET /api/transactions/status/ HTTP/1.1
Host: app.apruvd.com
Authorization: Basic $BASE64_ENCODED_API_KEYS
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "transaction_id":1,
  "status":"Approved",
  "canceled":false
}

Alternative Use Example using cURL:

cURL -X GET \
     -u "$API_KEY_ID:$API_KEY_SECRET" \
     -H "Accept: application/json" \
        "https://app.apruvd.com/api/transactions/status/?order_num=ABC10001"
GET /api/transactions/status/ HTTP/1.1
Host: app.apruvd.com
Authorization: Basic $BASE64_ENCODED_API_KEYS
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "21": {
    "transaction_id":21,
    "order_num":"ABC10001",
    "status":"Approved",
    "canceled":false
  },
  "22": {
    "transaction_id":22,
    "order_num":"ABC10001",
    "status":"Approved",
    "canceled":false
  }
}

Update a Transaction's Details

Endpoint
transactions/{transaction_id}/update/
Full URL
https://app.apruvd.com/api/transactions/{transaction_id}/update/
Method
POST

There may be times when the details of an order change before fulfillment. For example, your customer might call you and ask to adjust the quantity of one of the items ordered. When this happens, we need to review the order again, with the updated information.

Package Re-Routing

We strongly recommend that you do not allow packages to be rerouted in transit, as this presents a significant fraud risk and introduces a lot of friction to the fraud prevention process.

If you choose to allow package rerouting for your customers, please make efforts to ensure that you are notified when a package is rerouted, and that an update is sent to this endpoint to notify us of the new shipping address as well. If the new shipping address indicates fraud, we will notify you as soon as possible.

Example using cURL:

cURL -X POST \
     -u "$API_KEY_ID:$API_KEY_SECRET" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json;charset=UTF-8" \
     -d '{
           "total":246.90,
           "shipping_address_1":"8355 NW 74th St",
           "shipping_city":"Medley",
           "shipping_state":"FL",
           "shipping_postal":"33166",
         }' \
        "https://app.apruvd.com/api/transactions/1/update/"
POST /api/transactions/1/update/ HTTP/1.1
Host: app.apruvd.com
Authorization: Basic $BASE64_ENCODED_API_KEYS
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "transaction_id":1,
  "status":"Reviewing",
  "changelog":{
    "2016-Mar-15 10:28 AM":{
      "status":{
        "from":"Approved",
        "to":"Reviewing"
      },
      "total":{
        "from":123.45,
        "to":246.90
      },
      "shipping_address_1":{
        "from":"321 S Main St.",
        "to":"8355 NW 74th St"
      },
      "shipping_city":{
        "from":"New York",
        "to":"Medley"
      },
      "shipping_state":{
        "from":"NY",
        "to":"FL"
      },
      "shipping_postal":{
        "from":"10002",
        "to":"33166"
      }
    }
  }
}

Cancel a Transaction

Endpoint
transactions/{transaction_id}/cancel/
Full URL
https://app.apruvd.com/api/transactions/{transaction_id}/cancel/
Method
POST

Your customer may decide to cancel an order that you submitted to us for fraud review. If this happens, we will also cancel the order, including waiving the fees and the guarantee associated with it. If an order gets canceled, use this endpoint to let us know.

This endpoint accepts POST requests but does not require any data in the request body.

Example using cURL:

cURL -X POST \
     -u "$API_KEY_ID:$API_KEY_SECRET" \
     -H "Accept: application/json" \
        "https://app.apruvd.com/api/transactions/1/cancel/"
POST /api/transactions/1/cancel/ HTTP/1.1
Host: app.apruvd.com
Authorization: Basic $BASE64_ENCODED_API_KEYS
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "transaction_id":1,
  "status":"Reviewing",
  "canceled":true
}

Elevate a Submitted Transaction for Review

Endpoint
transactions/elevate/
Full URL
https://app.apruvd.com/api/transactions/elevate/
Method
POST

This endpoint will not be used by most integrations. However, if we have configured your transactions to default into the "Submitted" status instead of "Reviewing", then you can make another API call later to mark a transaction for fraud review.

This endpoint only requires transaction_id or order_num in the request body. If you use transaction_id, only a single transaction will be elevated for review. However, our database does not enforce uniqueness on the order_num parameter, so using it may cause multiple transactions to be elevated.

Example using cURL:

cURL -X POST \
     -u "$API_KEY_ID:$API_KEY_SECRET" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json;charset=UTF-8" \
     -d '{
           "order_num":"100014135",
         }' \
        "https://app.apruvd.com/api/transactions/elevate/"
POST /api/transactions/elevate/ HTTP/1.1
Host: app.apruvd.com
Authorization: Basic $BASE64_ENCODED_API_KEYS
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "transaction_id":1,
  "order_num":"100014135",
  "status":"Reviewing"
}

Registration-Time Risk Analysis (beta)

Endpoint
beta/registrationrisk/
Full URL
https://app.apruvd.com/api/beta/registrationrisk/
Method
POST

Your site may be able to benefit from risk analysis at the moment of registration, to prevent a new user from causing problems in your ecommerce model. This is especially relevant for electronic gift cards, online auctions, and travel agencies.

Input data is the same as the Submit Transaction endpoint. This endpoint returns a JSON object with the following data:

Name Type Description
transaction_id integer The data is stored as a Transaction object in our database
risk_grade enum A letter grade assigned by our internal risk scoring algorithm. A+ is low-risk, F- is high-risk
status enum For users of this endpoint during beta, this will always return "Submitted"
high_risk boolean True if we consider this registration to be high-risk
analysis object Contains several boolean values that can be used for risk analysis
analysis.ip_is_high_risk boolean IP is a proxy or has been previously associated with malicious activity
analysis.email_is_high_risk boolean Email provider is primarily used by fraudsters or email has been previously associated with fraud
analysis.cc_is_from_bill_country boolean Credit card was issued by a bank in the billing country
analysis.ip_is_in_bill_country boolean IP is located in the billing country
analysis.cc_is_prepaid boolean Credit card is prepaid
analysis.ship_addr_is_high_risk boolean Shipping address is a freight forwarder or other high-risk location

Example using cURL:

cURL -X POST \
     -u "$API_KEY_ID:$API_KEY_SECRET" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json;charset=UTF-8" \
     -d '{
           "mode":"Live",
           "type":"Ecommerce",
           "total":123.45,
           "currency":"USD",
           "order_num":"12346",
           "ip":"68.14.208.208",
           "email":"example@email.com",
           "billing_phone":"1 (480) 555-1234",
           "cc_name":"JOHN",
           "cc_name_2":"DOE",
           "first_six":"417420",
           "last_four":"1234",
           "billing_first_name":"John",
           "billing_last_name":"Doe",
           "billing_address_1":"123 N Main St.",
           "billing_address_2":"Ste 300",
           "billing_city":"New York",
           "billing_state":"NY",
           "billing_postal":"10001",
           "billing_country":"United States",
           "shipping_first_name":"Jane",
           "shipping_last_name":"Doe",
           "shipping_address_1":"8355 NW 74th St",
           "shipping_address_2":"DNUA42738901",
           "shipping_city":"Medley",
           "shipping_state":"FL",
           "shipping_postal":"33166",
           "shipping_country":"United States"
         }'
        "https://app.apruvd.com/api/beta/registrationrisk/"
POST /api/beta/registrationrisk/ HTTP/1.1
Host: app.apruvd.com
Authorization: Basic $BASE64_ENCODED_API_KEYS
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "transaction_id":3,
  "status":"Submitted",
  "risk_grade":"C-",
  "high_risk":true,
  "analysis":{
    "ip_is_high_risk":true,
    "email_is_high_risk":false,
    "cc_is_from_bill_country":true,
    "ip_is_in_bill_country":true,
    "cc_is_prepaid":false,
    "ship_addr_is_high_risk":true
  }
}