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.
Some features, such as testing a transaction submission require a test account. If you would like to obtain a test account please contact us.
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.
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.
All endpoints require HTTPS and are compliant with the PCI-DSS.
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 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"}
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.
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 |
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) |
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) |
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.
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",
}
]
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"
}
]
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 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 |
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.
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 |
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.
transactions/submit/
https://app.apruvd.com/api/transactions/submit/
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"
}
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
|
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.
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
:
callbacks/
https://app.apruvd.com/api/callbacks/
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"
}
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.
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.
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"
}
callbacks/{callback}/trigger/
https://app.apruvd.com/api/callbacks/{callback}/trigger/
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"
}
If, instead of setting up a callback endpoint, you would prefer to periodically request transaction updates, use this function.
transactions/status/?transaction_id={transaction_id}
transactions/status/?order_num={order_num}
https://app.apruvd.com/api/transactions/status/?transaction_id={transaction_id}
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
}
}
transactions/{transaction_id}/update/
https://app.apruvd.com/api/transactions/{transaction_id}/update/
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.
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"
}
}
}
}
transactions/{transaction_id}/cancel/
https://app.apruvd.com/api/transactions/{transaction_id}/cancel/
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
}
transactions/elevate/
https://app.apruvd.com/api/transactions/elevate/
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"
}
o/token/?grant_type={grant_type}
https://app.apruvd.com/o/token/?grant_type={grant_type}
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"
}
}
Did we miss one? This is the first step toward making it right.
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 |
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--
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
}
This request takes no parameters.
GET /api/v2/chargebacks/ 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
{
"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
}
]
}
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 |
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--
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
}
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 |
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--
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"
}
Name | Location | Data Type | Description |
---|---|---|---|
order_num required | Path | String | Your order number or ID (Transaction.order_num ) |
GET /api/v2/chargebacks/12345/ 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
{
"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
}
Name | Location | Data Type | Description |
---|---|---|---|
order_num required | Path | String | Your order number or ID (Transaction.order_num ) |
DELETE /api/v2/chargebacks/12345/ HTTP/1.1
Host: app.apruvd.com
Authorization: Basic $BASE64_ENCODED_API_KEYS
Accept: application/json
HTTP/1.1 204 NO CONTENT
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. |
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
|
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.