Quick Reference

API Endpoints

JavaScript

Integration Guide - HTTPS API

Introduction

The Apruvd API exposes simple functions that allow clients to submit transactions for review and to later update, cancel, or request the review status of their transactions. Additional endpoints allow for creating callbacks so that clients can take action on decisions, change account settings, and more.

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.

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 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, and especially sensitive data such as passwords and API keys are hashed.

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

Expected Fields

Our API requires very few fields in order to support the varied use cases of our customers. However, we request that all recommended fields are passed to us upon transaction creation, as available. Please contact us with any questions or concerns regarding data available to your integration.

Legend

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
shipping_method Shipping Method string(255) No
cart_contents Cart Contents JSON (Structure) Yes
rep_email Sales/Support Representative Email string(254) Yes
additional_1 Additional Notes 1 text No
additional_2 Session ID 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
(AMEX) F, H, J, K, L, O, Q, T, 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

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",
           "shipping_method":"Next-Day Air"
         }' \
        "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+",
  "order_num":"12345"
}

Configure Callback Endpoints

You can now configure the callback_url and the new settings_url endpoints through the API. The response value of id is always null, and the value of basic_rules is always an empty array ([]), as a placeholder for forthcoming functionality.

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:

Endpoint
callbacks/
Full URL
https://app.apruvd.com/api/callbacks/
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 '{
           "callback_url": "https://your.domain.com/your/endpoint/",
           "settings_url": "https://your.domain.com/your/settings-endpoint/",
           "callback_api_key_id": "9381F8D34546AF55174A2A1E",
           "callback_api_key_secret": "d9b8182ae01fb9ee3875d3c646d1b6d7148d"
         }' \
        "https://app.apruvd.com/api/callbacks/"
POST /api/callbacks/ 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

{
  "id": null,
  "service_plan": "Complete Coverage",
  "basic_rules": [],
  "data_connection": false,
  "training_data": false,
  "require_notes_on_approves": false,
  "require_notes_on_declines": false,
  "strictly_protect_pii": false,
  "enforce_unique_order_id": false,
  "integration_version": "V3",
  "callback_url": "https://your.domain.com/your/endpoint/",
  "settings_url": "https://your.domain.com/your/settings-endpoint/",
  "callback_api_key_id": "9381F8D34546AF55174A2A1E",
  "callback_api_key_secret": "d9b8182ae01fb9ee3875d3c646d1b6d7148d"
}

How Callbacks Work

Callbacks are also known as "webhooks". When you set a callback_url, our servers will make an HTTP POST request to that URL when we complete a transaction review. You should program that URL to ingest our JSON data and make any appropriate changes in your database.

We offer reverse API key authentication for callbacks and settings updates. In the example above, a callback_api_key_id and callback_api_key_secret were configured by you. You should check these values in the Authorization header of callback requests, to verify that the request actually comes from an Apruvd server.

callback_url

Example using cURL (request comes from Apruvd here):

cURL -X POST \
     -u "$CALLBACK_API_KEY_ID:$CALLBACK_API_KEY_SECRET" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json;charset=UTF-8" \
     -d '{
           "transaction_id": 1,
           "order_num": "12345",
           "status": "Approved",
           "notes": "Customer is friends with recipient"
         }' \
     "https://your.domain.com/your/endpoint/"

When you set a settings_url, our servers will make an HTTP POST request to that URL when the merchant settings, such as integration_version, are changed on our side. You should program that URL to ingest our JSON data and make any appropriate changes in your database.

settings_url

Example using cURL (request comes from Apruvd here):

cURL -X POST \
     -u "$CALLBACK_API_KEY_ID:$CALLBACK_API_KEY_SECRET" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json;charset=UTF-8" \
     -d '{
           "id": null,
           "service_plan": "{YOUR_SERVICE_PLAN}",
           "basic_rules": [],
           "data_connection": false,
           "training_data": false,
           "require_notes_on_approves": false,
           "require_notes_on_declines": false,
           "strictly_protect_pii": false,
           "enforce_unique_order_id": false,
           "integration_version": "{V3_OR_V4}"
         }' \
     "https://your.domain.com/your/settings-endpoint/"

Trigger Callbacks

Endpoint
callbacks/{callback}/trigger/
Full URL
https://app.apruvd.com/api/callbacks/{callback}/trigger/
Method
POST

You can trigger callbacks by making a POST request to the /callbacks/{callback}/trigger/ endpoint. The {callback} can be either review-complete or settings-update. To trigger a review-complete callback, you must also include a transaction_id in the request body.

Example using cURL:

cURL -X POST \
     -u "$API_KEY_ID:$API_KEY_SECRET" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{
           "transaction_id": 1
         }' \
        "https://app.apruvd.com/api/callbacks/review-complete/trigger/"
POST /api/callbacks/review-complete/trigger/ 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": "12345",
  "status": "Approved",
  "notes": "Customer is friends with recipient"
}

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":{
    "2020-Mar-15 10:28 AM":{
      "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"
}

Authenticating with OAuth Access and Refresh Tokens

Endpoint
o/token/?grant_type={grant_type}
Full URL
https://app.apruvd.com/o/token/?grant_type={grant_type}
Method
GET

You may obtain OAuth access and refresh tokens using the password grant type and your account's API Key ID and API Key Secret as credentials.

Access tokens expire after 24 hours; refresh tokens expire after 30 days. Both tokens are 255 characters in length.

[obtain tokens] Example using cURL:

cURL -X GET \
     -u "$API_KEY_ID:$API_KEY_SECRET" \
     -H "Accept: application/json" \
        "https://app.apruvd.com/o/token/?grant_type=password"
GET /o/token/ 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

{
  "access":{
    "type":"Bearer",
    "expires_in":86399,
    "token":"EXAMPLE_TOKENirjogMi93ujxdK90OL5PFv1IjouU85S7rsihuuagkOxE45rogPBznt5Q78ICbGIX4dp7VdxpIbprjFi8IWOrmSYw6UjY64FAV1N6ZWqz3AoA8pc8dPIIQvI3vDnpedrqYleymWFDPmpvhDFHHYxQuOSoFqmw1EQSLggfiv15agQm78HZmSOl8Jg4xE80D91070CxGHcizcLYp8k5YLPpkZiFrGSLZDtBbLoCYt3RKMLhSf"
  },
  "refresh":{
    "type":"Bearer",
    "expires_in":2591724,
    "token":"EXAMPLE_TOKENMHWjc5YXkLXuM0b4gvBiJuuaIDip87KVLM76ZIt9WkgVCUTZarE4htJdftC0jI3ELtcQfIioDWIBAJEIi3GBcOtBFhSLKXTTaUr8q3bBSh1Qi3z1Gag5krMM3E7m3ZkInl5j6sMUMczJ07Kbzs0ao5fNX7A2157kBbLDSbFTbgLKg1nCr3QAthLVkEpRoRGCUzKm4dXBIx8rJWJ6nLBE9T8E05GNfiIcrCXtyw2ZxcS6ao"
  }
}

To refresh your access token, use the refresh grant type and Bearer authorization, with your refresh token.

[refresh access token] Example using cURL:

cURL -X GET \
     -H "Authorization: Bearer $REFRESH_TOKEN" \
     -H "Accept: application/json" \
        "https://app.apruvd.com/o/token/?grant_type=refresh"
GET /o/token/ HTTP/1.1
Host: app.apruvd.com
Authorization: Bearer $REFRESH_TOKEN
Accept: application/json

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

{
  "access":{
    "type":"Bearer",
    "expires_in":86399,
    "token":"EXAMPLE_TOKENyX9fDpRwdUEXAUtPEcPq9wPVcoHDx8uaHDVyJsPV7oBmQrV81KO9bUYC4J6pdm9R73RVleGkYOjI9MueLjfPsPKxtnyufpwDXk1COM8U0xDmylVFmsltXYJ0QkoR4Dt1ndA9PSPC5nrAgLQ7WvKJZIfAMvtQyf7VYJdylZzSivfVYhQuorkIN2Cz71SOAy2gROWvaPCXiJ6qZ8DLYzUfQTAwYGm6uUTdf1W40lTEEyCF9N"
  },
  "refresh":{
    "type":"Bearer",
    "expires_in":2591724,
    "token":"EXAMPLE_TOKENMHWjc5YXkLXuM0b4gvBiJuuaIDip87KVLM76ZIt9WkgVCUTZarE4htJdftC0jI3ELtcQfIioDWIBAJEIi3GBcOtBFhSLKXTTaUr8q3bBSh1Qi3z1Gag5krMM3E7m3ZkInl5j6sMUMczJ07Kbzs0ao5fNX7A2157kBbLDSbFTbgLKg1nCr3QAthLVkEpRoRGCUzKm4dXBIx8rJWJ6nLBE9T8E05GNfiIcrCXtyw2ZxcS6ao"
  }
}

JavaScript Drop-In

Our JavaScript snippets are required for all merchants. They add additional insight into your customers, and help to make our reviews even more accurate. One goes in the head of your site's checkout page, and the other goes in the body, to support browsers which may have JavaScript turned off.

Variables in the table below are represented in the snippet with curly braces. These placeholders must be replaced with the actual value before using the snippet on your site. If you're unsure how to work this into your site, please contact our developer support department and we will be happy to help.

Variable Required Expected Value
org_id Static value available upon request
session_id A universally unique value that identifies the current user's browser session. It must be generated server-side. We recommend hashing an existing session cookie ID if available. Otherwise, you can assign a value when the user first visits your site, and store it in their browser's Window.sessionStorage for reuse during the browsing session.
<html>
  <head>
    <!-- your head content here -->
    <!-- below is the Apruvd script tag -->
    <script async
      type="text/javascript"
      src="https://content.apruvd.com/fp/tags.js?org_id={org_id}&session_id={session_id}">
    </script>
  </head>

  <body>
    <!-- your body content here -->
    <!-- below is the Apruvd noscript tag -->
    <noscript>
      <iframe
        style="width: 100px; height: 100px; border: 0; position: absolute; top: -5000px;"
        src="https://content.apruvd.com/fp/tags?org_id={org_id}&session_id={session_id}">
      </iframe>
    </noscript>
  </body>
</html>