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, manage chargebacks, and more.

Test Accounts

Some features, such as testing a transaction submission require a test account. If you would like to obtain a test account please contact us.

Authentication

Authenticate requests either via basic auth or OAuth Access/Refresh Tokens. To create or delete API keys, please visit your profile. Store your generated API keys securely, and never share your secret key with anyone.

Data Formatting

All API requests must be submitted in the application/json format, matching any given endpoint's structure. Outlines and examples for each endpoint can be found later in this document. Clients can expect all responses and callbacks to be in JSON.

Security

All endpoints require HTTPS and are compliant with the PCI-DSS.

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.

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 should be submitted in the application/json 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

Please see the How Do I... section for instructions on how to use each of these fields.

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
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 or 8 Digits of CC denoting the Bank Identification Number (BIN) 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
gift_cards Gift Cards used as a means of payment JSON (Structure) 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
session_id Session ID string(255) No
cart_contents Cart Contents JSON (Structure) Yes
digital_only_order Is Order for Digital Items Only? E-Giftcards, Crypto, Emailed Event Tickets, etc. boolean No
discount_codes Discount Codes JSON (Structure) Yes
rep_email Sales/Support 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

Response fields

Attribute Description Data Type Info
transaction_id Apruvd Transaction No. integer Auto-incrementing
risk_grade Apruvd Risk Grade string(2) enum
status Apruvd Status string(9) enum
order_num Your Order ID string(25)

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)

Gift Cards (JSON)

If any Gift Cards are used as a payment method, please provide the details available as detailed below. If a Gift Card was used, the fields related to credit cards are not required and can be omitted.

Expected Format

The expected structure of this JSON field is a list of objects. merchant_payment_id is required, with all other keys highly recommended if at all possible. If no currency is provided, the value will automatically be set to the default of your account. If any extra values may be helpful to the review process, those can be included in each object(see undocumented_field in the example) with any unused key/value pairs.

Key Description Required Data Type
merchant_payment_id An Identifier for this gift card string(50)
amount The amount charged against this gift card stringified decimal
currency The currency for the amount charged against this gift card enum (ISO 4217)
last_four The last 4 characters of the gift card code string(4)
issued_on The date the gift card was issued at string(YYYY-MM-DD)
expires_on The date the gift card will expire on string(YYYY-MM-DD)
initial_balance The amount added to this gift card when issued stringified decimal
remaining_balance The amount remaining on this gift card after this order stringified decimal
purchaser_name The name of the individual who purchased this gift card string(100)
purchaser_email The email of the individual who purchased this gift card string(100)
recipient_name The name of the individual who received this gift card string(100)
recipient_email The email of the individual who received this gift card string(100)
type The form factor of the gift card enum

Example input:

[
  {
    "merchant_payment_id": "GC10000001",
    "amount": "12.34"
  },
  {
    "merchant_payment_id": "GC10000002",
    "amount": "34.56",
    "currency": "USD",
    "last_four": "A1B2",
    "issued_on": "2023-12-25",
    "expires_on": "2025-12-25",
    "initial_balance": "100.00",
    "remaining_balance": "65.44",
    "recipient_name": "John Doe",
    "recipient_email": "jdoe@example.com",
    "type": "electronic",
    "undocumented_field": "additional value useful for review",
  }
]

Cart Contents (JSON)

Expected Format

The expected structure of this JSON field is a list of objects. One of item or extra.sku is required, with all other keys highly recommended if at all possible. The extra key, an object, may have extra keys added if asked or if you have additional information that you think will be useful during the order review process.

Key Description Required Data Type
item Name of item string(250)
is_high_risk Whether product is a high fraud risk boolean
is_digital Whether product is a digital item boolean
quantity Number of this item purchased integer
unit_price Price of the item, in transaction currency stringified decimal
extra Other possible keys to add object
link Element of extra, URI of item string(250)
SKU Element of extra, SKU of item string(250)

Example input:

[
  {
    "item": "Widget Name",
    "is_high_risk": true,
    "is_digital": false,
    "quantity": 1,
    "unit_price": "100.50",
    "extra": {
      "link": "https://www.example.com/products/productidentifier/",
      "sku": "SKU-123"
    }
  },
  {
    "item": "Simple Widget",
    "is_high_risk": false,
    "quantity": 1
  },
  {
    "item": "High-Fraud Widget",
    "is_high_risk": true,
    "quantity": 1
  },
  {
    "item": "Gift Card",
    "is_digital": true,
    "quantity": 1,
    "unit_price": "250.00"
  }
]

Discount Codes (JSON)

Expected Format

The expected structure of this JSON field is a list of objects. While no specific keys are required, all are highly recommended if at all possible. The extra key, an object, may have extra keys added if asked or if you have additional information that you think will be useful during the order review process.

Key Description Required Data Type
code The discount code itself string(250)
description A description of the discount code string(250)
amount The total discount amount applied to the order stringified decimal
discount_type The type of discount, such as Free Shipping, Fixed, or Percent string(250)
extra Other possible keys to add object

Example input:

[
  {
    "code": "NEWSLETTER-FREE-SHIP",
    "description": "Discount for loyal customers",
    "amount": "5.99",
    "discount_type": "Free Shipping",
    "extra": {
      "email_campaign": "ID-123"
  },
  {
    "code": "5OFF",
    "discount_type": "Percent"
  }
]

Callbacks

Content Type

Callbacks use Content-Type application/json, meaning all requests will appear in JSON format. These are the fields that you can anticipate when receiving callbacks from different portions of our API.

callback_url

Attribute Description Data Type Info
transaction_id Apruvd Transaction No. integer Auto-incrementing
order_num Your Order ID string(25)
status Apruvd Status string enum
corrected_email Correction to a typo in a customer's email address. string Optional -- may be omitted
notes Notes submitted by a reviewer when approving or declining a transaction text Optional -- may be omitted

settings_url

Attribute Description Data Type Info
service_plan Your current service plan with Apruvd string
enforce_unique_order_num Are order numbers unique? boolean Defaults to false
js_url Link to a generated script for API integration string See the JavaScript Drop-In section for more information

Deprecated fields

The following fields are deprecated, but are still included in callback requests to settings_url as a way of maintaining backwards compatibility for existing customers.

Your settings_url endpoint should still be able to accept these fields, but they will not contain any important information so you do not need to process them.

Deprecated Fields Sent to settings_url

Attribute Data Type Info
id integer Deprecated: Always null
basic_rules Array Deprecated: Always Empty []
data_connection boolean Deprecated: Always false
training_data boolean Deprecated: Always false
enforce_unique_order_id boolean Deprecated: Always false
require_notes_on_approves boolean Deprecated: Always false
require_notes_on_declines boolean Deprecated: Always false
strictly_protect_pii boolean Deprecated: Always false
integration_version string(2) Deprecated: Always V3

How Do I...

Submit a Transaction

Transaction submissions will be your main interaction with our API. Many of the fields for a Transaction object are optional, but they each have a purpose and you are encouraged to submit as much relevant data as you can so that we may get a clearer idea of a transaction's story. Please see the Transaction Objects table for a complete list of fields.

Each transaction will return one of four statuses: Submitted, Reviewing, Approved, or Declined. An Approved or Declined transaction has completed review, meaning that this state reflects our final decision for the transaction that you have submitted. Transactions marked as Reviewing are still pending -- they are in our reviewer queue and will be processed shortly.

You will only see Submitted transactions if you have opted to submit all of your transactions and then elevate suspicious ones later on. Otherwise, all transactions will automatically be reviewed. You can retrieve the status of a transaction manually, or you can configure a callback endpoint to receive an automatic update each time an order is approved or declined. See Configure Callback Endpoints and Check a Transaction's Status for more detail.

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

Test a Transaction Submission

(Test Account Required)

You can test submitting a transaction and force the decision (Approved, Declined or Submitted) for the transaction by setting specific values within the above json object. Each row in the table below shows which values to set for each data point to achieve the desired outcome.

Key Operator Value Outcome Decision
email Starts With "approve" Approved
email Starts With "decline" Decline
email Starts With "submit" Submitted
billing_first_name Equals "approve" Approved
billing_first_name Equals "decline" Declined
billing_first_name Equals "submit" Submitted
first_six Equals 444444 Approved
first_six Equals 555555 Declined
first_six Equals 333333 Submitted

Configure Callback Endpoints

We strongly recommend that you configure a callback_url for your account, which can be set in the options section of your profile. This URL should accept application/json data and perform updates within your platform to record that the order has been approved or declined.

Below is a list of dedicated static IP addresses that callbacks are generated from. We recommend that you whitelist these to ensure that Apruvd servers have access to your endpoint.

Static IP Addresses
3.101.46.125
52.8.174.47
54.193.137.66
54.241.213.200
54.241.49.17

We offer reverse API key authentication for callbacks and settings updates. In the following examples, 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.

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

{
  "service_plan": "Complete Coverage",
  "enforce_unique_order_num": false,
  "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 server will make an HTTP POST request to that URL when we complete a transaction review. You should program that URL to accept our JSON data and make any appropriate changes to your database each time a callback is received.


Fields sent to callback_url

In this example, the request coming from Apruvd would look like:

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",
         }' \
     "https://your.domain.com/your/endpoint/"

Your endpoint should expect to receive the following request:

Authorization: Basic $BASE64_ENCODED_API_KEYS
Accept: application/json
content-type: "application/json;charset=UTF-8"
method: POST
path: /your/endpoint/

{
  "transaction_id": 1,
  "order_num": "12345",
  "status": "Approved",
}

Any given transaction will have a status status of Submitted, Reviewing, Approved, or Declined. However, because callbacks to the callback_url are only triggered after a review is completed, your API should only expect to see Approved, or Declined. These fields indicate the final outcome for this particular order.

Depending on the transaction, you may see two additional fields: notes and corrected_email These fields are optional: they will only appear if a reviewer adds notes or changes a typo in an email address domain. Your API must be implemented in a way that will accept these values without making them mandatory.


Fields sent to settings_url

When you set a settings_url, our servers will make an HTTP POST request to that URL whenever certain settings change on our side. You should write an endpoint at that URL to ingest JSON data and make any appropriate changes to your own internal database.

The request coming from Apruvd would look like:

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 '{
           "service_plan": "{YOUR_SERVICE_PLAN}",
           "enforce_unique_order_num": false,
           "js_url": "https://mjs.apruvd.com/{hash}/entry.js"
         }' \
     "https://your.domain.com/your/settings-endpoint/"

Your endpoint should expect to receive the following request:

Authorization: Basic $BASE64_ENCODED_API_KEYS
Accept: application/json
content-type: "application/json;charset=UTF-8"
method: POST
path: /your/settings-endpoint/

{
  "service_plan": "{YOUR_SERVICE_PLAN}",
  "enforce_unique_order_num": false,
  "js_url": "https://mjs.apruvd.com/{hash}/entry.js"
}

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

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

Submit Chargebacks

Did we miss one? This is the first step toward making it right.

Parameters

Attaching Files

To attach required files when creating or updating a chargeback claim, use Content-Type: multipart/form-data.

Name Location Data Type Description
order_num required Request Body String Your order number or ID (Transaction.order_num)
claim_status Request Body String Defaults to Reviewing. If this is an alert for a pending chargeback claim, Alert can be passed in instead.
claim_amount Request Body Number Defaults to Transaction.total
claim_amount_currency Request Body String Defaults to Transaction.currency
claim_file Request Body File Chargeback claim documentation
claim_file_2 Request Body File Chargeback claim documentation
claim_file_3 Request Body File Chargeback claim documentation
appeal_file Request Body File Decision appeal documentation

Example

Request
POST /api/v2/chargebacks/ HTTP/1.1
Host: app.apruvd.com
Authorization: Basic $BASE64_ENCODED_API_KEYS
Content-Type: multipart/form-data;boundary="boundary"
Accept: application/json

--boundary
Content-Disposition: form-data; name="order_num"

12345
--boundary
Content-Disposition: form-data; name="claim_amount"

100.00
--boundary
Content-Disposition: form-data; name="claim_file"; filename="claim_file.pdf"
Content-Type: application/pdf

$CLAIM_FILE_CONTENTS
--boundary--
Response
HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "order_num": "12345",
  "timestamp": "2021-02-09T10:10:02.444696-07:00",
  "claim_status": "Reviewing",
  "claim_amount_currency": "USD",
  "claim_amount": "100.00",
  "denial_reason": null,
  "claim_file": "https://example/chargebacks/merchant1example.com-claim_file.pdf",
  "claim_file_2": null,
  "claim_file_3": null,
  "appeal_file": null
}

Parameters

This request takes no parameters.


Example

Request
GET /api/v2/chargebacks/ HTTP/1.1
Host: app.apruvd.com
Authorization: Basic $BASE64_ENCODED_API_KEYS
Accept: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "previous": "https://url/to/previous-page",
  "next": "https://url/to/next-page",
  "results": [
    {
      "order_num": "12345",
      "timestamp": "2021-02-09T10:10:02.444696-07:00",
      "claim_status": "Accepted, Paid",
      "claim_amount_currency": "USD",
      "claim_amount": "100.00",
      "denial_reason": null,
      "claim_file": "https://example/chargebacks/merchant1example.com-claim_file.pdf",
      "claim_file_2": null,
      "claim_file_3": null,
      "appeal_file": null
    },
    {
      "order_num": "12346",
      "timestamp": "2021-02-14T10:10:02.444696-07:00",
      "claim_status": "Reviewing",
      "claim_amount_currency": "USD",
      "claim_amount": "200.00",
      "denial_reason": null,
      "claim_file": "https://example/chargebacks/merchant1example.com2-claim_file.pdf",
      "claim_file_2": null,
      "claim_file_3": null,
      "appeal_file": null
    }
  ]
}

Parameters

Attaching Files

To attach required files when creating or updating a chargeback claim, use Content-Type: multipart/form-data.

Name Location Data Type Description
order_num required Path String Your order number or ID (Transaction.order_num)
claim_status Request Body String If the current status is Alert, Reviewing can be passed in this value to elevate the claim.
claim_amount Request Body Number Defaults to Transaction.total
claim_amount_currency Request Body String Defaults to Transaction.currency
claim_file Request Body File Chargeback claim documentation
claim_file_2 Request Body File Chargeback claim documentation
claim_file_3 Request Body File Chargeback claim documentation
appeal_file Request Body File Decision appeal documentation

Example

Request
PUT /api/v2/chargebacks/12345/ HTTP/1.1
Host: app.apruvd.com
Authorization: Basic $BASE64_ENCODED_API_KEYS
Content-Type: multipart/form-data;boundary="boundary"
Accept: application/json

--boundary
Content-Disposition: form-data; name="claim_amount"

100.00
--boundary
Content-Disposition: form-data; name="claim_file"; filename="claim_file.pdf"
Content-Type: application/pdf

$CLAIM_FILE_CONTENTS
--boundary
Content-Disposition: form-data; name="claim_file_2"; filename="claim_file_2.pdf"
Content-Type: application/pdf

$CLAIM_FILE_2_CONTENTS
--boundary--
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "order_num": "12345",
  "timestamp": "2021-02-09T10:10:02.444696-07:00",
  "claim_status": "Reviewing",
  "claim_amount_currency": "USD",
  "claim_amount": "100.00",
  "denial_reason": null,
  "claim_file": "https://example/chargebacks/merchant1example.com-claim_file.pdf",
  "claim_file_2": "https://example/chargebacks/merchant1example.com-claim_file_2.pdf",
  "claim_file_3": null,
  "appeal_file": null
}

Parameters

Attaching Files

To attach required files when creating or updating a chargeback claim, use Content-Type: multipart/form-data.

Name Location Data Type Description
order_num required Path String Your order number or ID (Transaction.order_num)
claim_status Request Body String If the current status is Alert, Reviewing can be passed in this value to elevate the claim.
claim_amount Request Body Number Defaults to Transaction.total
claim_amount_currency Request Body String Defaults to Transaction.currency
claim_file Request Body File Chargeback claim documentation
claim_file_2 Request Body File Chargeback claim documentation
claim_file_3 Request Body File Chargeback claim documentation
appeal_file Request Body File Decision appeal documentation

Example

Request
PATCH /api/v2/chargebacks/12345/ HTTP/1.1
Host: app.apruvd.com
Authorization: Basic $BASE64_ENCODED_API_KEYS
Content-Type: multipart/form-data;boundary="boundary"
Accept: application/json

--boundary
Content-Disposition: form-data; name="appeal_file"; filename="appeal_file.pdf"
Content-Type: application/pdf

$APPEAL_FILE_CONTENTS
--boundary--
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "order_num": "12345",
  "timestamp": "2021-02-09T10:10:02.444696-07:00",
  "claim_status": "Reviewing",
  "claim_amount_currency": "USD",
  "claim_amount": "100.00",
  "denial_reason": null,
  "claim_file": "https://example/chargebacks/merchant1example.com-claim_file.pdf",
  "claim_file_2": "https://example/chargebacks/merchant1example.com-claim_file_2.pdf",
  "claim_file_3": null,
  "appeal_file": "https://example/chargebacks/merchant1example.com-appeal_file.pdf"
}

Parameters

Name Location Data Type Description
order_num required Path String Your order number or ID (Transaction.order_num)

Example

Request
GET /api/v2/chargebacks/12345/ HTTP/1.1
Host: app.apruvd.com
Authorization: Basic $BASE64_ENCODED_API_KEYS
Accept: application/json
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "order_num": "12345",
  "timestamp": "2021-02-09T10:10:02.444696-07:00",
  "claim_status": "Accepted, Paid",
  "claim_amount_currency": "USD",
  "claim_amount": "100.00",
  "denial_reason": null,
  "claim_file": "https://example/chargebacks/merchant1example.com-claim_file.pdf",
  "claim_file_2": null,
  "claim_file_3": null,
  "appeal_file": null
}

Parameters

Name Location Data Type Description
order_num required Path String Your order number or ID (Transaction.order_num)

Example

Request
DELETE /api/v2/chargebacks/12345/ HTTP/1.1
Host: app.apruvd.com
Authorization: Basic $BASE64_ENCODED_API_KEYS
Accept: application/json
Response
HTTP/1.1 204 NO CONTENT

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.

To find your JavaScript snippet, please visit the JavaScript Snippet tab on your profile. If you have configured a settings_url endpoint to accept callbacks from our server, the ws_url field will contain a URL that points to this script.

This script generates individual sessions with different vendors, which help us rapidly determine each individual transaction's risk. You should use this script to integrate our API into your checkout process. Certain eCommerce platforms (such as Shopify, Magento, etc) will take care of this step automatically. You may not need to interact with this script if you are using an integrated platform.

If your website utilizes a Content Security Policy (CSP), please see our CSP documentation for required policy additions.

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 not sure how to work this into your site, please contact our developer support department and we will be happy to help.

Variable Required Expected Value
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 localStorage for later use. This same value must be passed to the Transaction Submit API via the session_id data element.
page_id An optional unique identifier for a store's checkout page. If one is not provided we will generate one from a hash of the checkout page URL.

Content Security Policy (CSP)

A Content Security Policy (CSP) is a useful browser feature for enhancing the security of your website. The main purpose of a CSP is to mitigate and detect Cross-Site Scripting (XSS) attacks, a type of injection in which malicious scripts from an outside domain are injected into trusted websites. This forces the victim's browser to execute malicious or unknown scripts since the browser blindly trusts the source of the content. A CSP prevents this by only allowing specific domains to perform explicitly defined actions, referred to as directives.

Click here for more information on CSP's, their purpose, and implementation.

Integration with Apruvd does not currently require a CSP. However, if you use our JavaScript snippet with a CSP enabled, you will need to make some modifications. Below is a list of directives and domains to add to an existing CSP to ensure all Apruvd services will function correctly.

Note: The connect_src directive for wss://bioprint.apruvd.com CANNOT be combined or wildcarded as it is specific to the protocol (https:// and wss:// respectively) and wildcard protocols are not supported.

Directive URL
connect_src *.apruvd.com
connect_src wss://bioprint.apruvd.com
frame-src *.apruvd.com
frame-src *.online-metrix.net
img-src *.apruvd.com
img-src *.online-metrix.net
script-src *.apruvd.com
script-src *.online-metrix.net

Notes and Errata

This document is subject to change as our API continues to develop. If anything seems incomplete or out of place, please reach out to api.dev@apruvd.com.
We appreciate feedback and are happy to assist wherever we can.