Chargeback Documents
Overview and details on Chargeback Documents in RevCent.
Documents in RevCent allow you to download via web app, or via API, the important details regarding a specific item. This is mainly as a tool for chargeback mitigation or individual sale analysis. However, additional capabilities will be added as the document feature in RevCent is expanded.
Why Use Chargeback Documents?
- Provide detailed information to third parties.
- Get a broad overview of a sale in a docx file.
- Fight chargebacks using detailed information on a sale.
Document Types
At this time there is only one document type, sale. Additional document types will be added as the document feature is expanded.
Sale Document
The sale document allows you to download relevant information specific to a sale. Each sale document has “sections”, and each section has properties (object), or multiple items (list) with properties.
Sale ZIP File
Download a Sample ZIP file which contains example .docx and .json files for the sale document type.
Sale Sections
| Section | Type | Description |
|---|---|---|
| api_call | object | The API call specific to the sale. |
| campaign | object | The campaign specific to the sale. |
| chargebacks | list | A list of chargebacks related to the sale. |
| customer | object | The customer specific to the sale. |
| fraud_detections | list | A list of fraud detections related to the sale. |
| fraud_detection_requests | list | A list of fraud detection requests related to the sale. |
| metadata | list | Metadata specific to the sale. |
| notes | list | Notes specific to the customer. |
| products | list | Products specific to the sale. |
| refunds | list | Refunds specific to the sale. |
| shipping | list | A list of shipping specific to the sale. |
| tax | list | A list of tax specific to the sale. |
| tracking_entries | list | The tracking entries, specific to the tracking visitor of the sale. |
| tracking_visitor | object | The tracking visitor specific to the sale. |
| transactions | list | A list of transactions specific to the sale. |
Retrieve A Document
Easily retrieve a document via the web app or the API. When downloading a document, you will receive a ZIP file, which when unpacked will contain the .docx file and raw .json file specific to the sale.
Web App
On a sale’s details page, find Document in the Tools panel at the upper right.
Click Document to open the confirmation dialog, then Create Document to generate the document. The current dialog does not include an Advanced tab or filter inputs.
API
Create a document request using item_value as a search value and specifying the originating item type. RevCent uses item_type and item_value to search the relevant fields.
The API response will contain a zip_url field, which is the downloadable link to the ZIP file containing the docx and json file. The API response will also contain the contents of the json file as the document_json property.
In the example below, we are attempting to generate a sale document using the sale ID. In this case, RevCent will search sales (indicated via item_type: sale) where the ID of the sale is KnmOa7VZ77iR5KRvbPpW.
{
"item_type": "sale",
"item_value": "KnmOa7VZ77iR5KRvbPpW"
}API Search Fields
The table below lists the item_type you can use to search, as well as fields which are searched by RevCent using the id property as the search value.
| item_type | Fields Searched | Explained |
|---|---|---|
| sale |
|
Searching for a sale using the RevCent sale id |
| transaction |
|
Searching for a sale using the either the RevCent ID of a transaction, or the gateway transaction ID of a transaction. |
| shipping |
|
Searching for a sale using the either the RevCent ID of a shipment, or the tracking number of a shipment. |
| fraud_detection |
|
Searching for a sale using the either the RevCent ID of a fraud detection, the third party ID of a fraud detection, a fraud detection case number or fraud detection arn. |
| chargeback |
|
Searching for a sale using the either the RevCent ID of a chargeback, the gateway transaction ID of a chargeback, the third party ID of a chargeback, a chargeback case number or chargeback arn. |
API Search Example 1
In the example below, we are attempting to generate a sale document using a gateway transaction ID. In this case, RevCent will search transactions (indicated via item_type: transaction) where the RevCent ID of the transaction is 1234567 or the gateway transaction ID of the transaction is 1234567.
{
"item_type": "transaction",
"item_value": "1234567"
}API Search Example 2
In the example below, we are attempting to generate a sale document using a tracking number. Since it is a tracking number we want to use the ‘shipping’ item_type. RevCent will search shipments (indicated via item_type: shipping) where the RevCent ID is 9405536115112062747214 or the tracking number is 9405536115112062747214.
{
"item_type": "shipping",
"item_value": "9405536115112062747214"
}API Response
Below is an example API response you will receive when making an API call to retrieve a document.
{
"api_call_id": "nb9FakR8V1BK1G17rMkO",
"api_call_processed": true,
"api_call_region": "1",
"api_call_unix": 1694792104,
"code": 1,
"current_count": 1,
"current_page": 1,
"request_method": "retrieve",
"request_type": "document",
"results": [
{
"document_json": {
"api_call": {
"api_account": "4aG0HMJ1ZnMpy2r4MW5A",
"code": 1,
"id": "k6UGlB1mNLWEr9orPvR4",
"method": "create",
"request": {
"bill_to": {
"first_name": "George",
"last_name": "Washington",
"address_line_1": "1600 Pennsylvania Aveive",
"address_line_2": "",
"city": "Washington",
"state": "DC",
"zip": "20500",
"country": "US",
"email": "georgew@whitehouse.com",
"phone": "1234567890"
},
"campaign": "B2Rd8raX8XEQk6S1z1P9",
"customer_id": "n8LOEjvgilkPd6bWVPXj",
"ip_address": "123.456.789.0",
"metadata": [],
"method": "create",
"payment_profile": "pY24LzukqKoJgVE6bM2J",
"product": [
{
"id": "P8y4YTnXAnLk1bJ6OgWw",
"quantity": 1
}
],
"ship_to": {
"first_name": "George",
"last_name": "Washington",
"address_line_1": "1600 Pennsylvania Aveive",
"address_line_2": "",
"city": "Washington",
"state": "DC",
"zip": "20500",
"country": "US",
"email": "georgew@whitehouse.com",
"phone": "1234567890"
},
"shipping": [
{
"amount": 0,
"cost": 0,
"provider": "USPS",
"provider_method": "Ground",
"free_shipping": true
}
],
"type": "sale",
"unique_request_id": "777777"
},
"type": "sale"
},
"campaign": {
"id": "B2Rd8raX8XEQk6S1z1P9",
"name": "My Campaign"
},
"chargebacks": [],
"customer": {
"address_line_1": "1600 Pennsylvania Aveive",
"address_line_2": "",
"blocked": false,
"city": "Washington",
"company": "",
"country": "US",
"device_details": {
"region_timezone": "-04:00",
"os": "iOS",
"device_type": "phone",
"window_size": "0x0",
"screen_resolution": "414x896",
"browser": "APPLE_WEB_KIT",
"region_language": "en-US"
},
"email": "georgew@whitehouse.com",
"email_details": {
"email": "georgew@whitehouse.com",
"score": 1,
"deliverable": true,
"domain_details": { // SEON Specific
"domain": "whitehouse.com",
"tld": ".com",
"registered": true,
"registrar_name": "US Gov.",
"registered_to": "Whitehouse",
"disposable": false,
"free": true,
"custom": false,
"dmarc_enforced": true,
"spf_strict": true,
"valid_mx": true,
"accept_all": true,
"suspicious_tld": false,
"website_exists": true
},
"account_details": { // SEON Specific
"apple": {
"registered": true
},
"facebook": {
"registered": true,
"url": null,
"name": null,
"photo": null
},
"google": {
"registered": true,
"photo": null
},
"instagram": {
"registered": true
},
"linkedin": {
"registered": null,
"photo": null
},
"microsoft": {
"registered": true
},
"myspace": {
"registered": false
},
"pinterest": {
"registered": false
},
"skype": {
"registered": false
},
"spotify": {
"registered": false
},
"tumblr": {
"registered": false
},
"twitter": {
"registered": true
},
"yahoo": {
"registered": true
}
}
},
"enabled": false,
"first_name": "George",
"full_address": "1600 Pennsylvania Ave, Washington, DC 20500, USA",
"geocode_success": true,
"google_place_id": "ChIJGVtI4by3t4kRr51d_Qm_x58",
"id": "n8LOEjvgilkPd6bWVPXj",
"internal_id": "",
"ip_details": {
"ip": "123.456.789.0",
"score": 3,
"country": "US",
"state_prov": "",
"city": "",
"timezone_offset": "-04:00",
"isp_name": "Acme ISP",
"latitude": 42.86563,
"longitude": -73.77095,
"type": "ISP",
"tor": false,
"vpn": false,
"web_proxy": false,
"public_proxy": false,
"spam_number": 3
},
"last_name": "Washington",
"lat": "42.123456",
"lon": "-73.123456",
"phone": "+11234567890",
"phone_details": { // SEON Specific
"number": 11234567890,
"valid": true,
"type": "MOBILE",
"country": "US",
"carrier": "VERIZON WIRELESS - DC",
"score": 0,
"account_details": {
"facebook": {
"registered": true
},
"google": {
"registered": false
},
"twitter": {
"registered": false
},
"instagram": {
"registered": true
},
"yahoo": {
"registered": null
},
"whatsapp": {
"registered": false,
"photo": null,
"last_seen": null
},
"telegram": {
"registered": false,
"photo": null,
"last_seen": null
},
"viber": {
"registered": null,
"photo": null,
"last_seen": null
}
}
},
"state": "DC",
"state_long": "DC",
"zip": "20500"
},
"fraud_detection_requests": [
{
"created_date": "2023-07-13T00:13:33+00:00",
"fraud_score": 4,
"id": "L1mrPvBnBo0hGlBNLWEn",
"is_error": false,
"is_fraud_detected": false,
"is_sentinel": false,
"is_third_party_integration": true,
"raw_response": "{}",
"score_threshold": 25,
"score_threshold_bound": "upper",
"third_party_fraud_detection_id": "123456",
"third_party_integration": {
"id": "b0aO8VWoAlvMQp9r6kdt",
"name": "SEON",
"third_party": {
"id": "0pJngyjNlyimGmYnM8Eb",
"name": "SEON"
}
}
},
{
"created_date": "2023-07-13T00:13:33+00:00",
"fraud_score": 0,
"id": "m7LJ7266pg8G9lfly8Y9",
"is_error": false,
"is_fraud_detected": false,
"is_sentinel": true,
"is_third_party_integration": false,
"raw_response": "",
"score_threshold": 0,
"score_threshold_bound": "upper",
"third_party_fraud_detection_id": "",
"third_party_integration": null
}
],
"iso_currency": "USD",
"metadata": [],
"payment_type": {
"id": "KnQ0KlNE6kf5mobyV0pN",
"name": "Credit Card"
},
"products": [
{
"id": "P8y4YTnXAnLk1bJ6OgWw",
"internal_id": "my_product_id",
"name": "My Product",
"price": 49.99,
"quantity": 1,
"sku": "my_product_sku",
"total_amount": 49.99
}
],
"sale": {
"amount": 49.99,
"created_date": "2023-07-13T00:13:32+00:00",
"id": "ypgXrBmYav8ULMAnaRWW",
"unique_request_id": "123456"
},
"shipping": [
{
"amount": 0,
"created_date": "2023-07-13T00:13:39+00:00",
"fulfillment_account": {
"id": "adJZ2629LbOEFpM27WdQ",
"name": "My Fulfillment",
"fulfillment_center": {
"id": "wLN45BQGRmh78OnKbVk0",
"name": "ShipStation"
}
},
"fulfillment_account_notified": true,
"fulfillment_account_notified_date": "2023-07-13T00:15:40+00:00",
"id": "hdr8525wljv8GALg9E0p",
"is_delivered": true,
"is_free": true,
"is_shipped": true,
"provider": "USPS",
"provider_delivered_date_unix": 1689596220,
"provider_method": "usps_other",
"provider_tracking": "9400100000000000000000",
"provider_tracking_url": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400100000000000000000",
"ship_date_unix": 1689206400,
"ship_to": {
"first_name": "George",
"last_name": "Washington",
"address_line_1": "1600 Pennsylvania Aveive",
"address_line_2": "",
"city": "Washington",
"state": "DC",
"zip": "20500",
"country": "US",
"company": "",
"email": "georgew@whitehouse.com",
"phone": "1234567890"
},
"shipping_status": "Delivered"
}
],
"tracking_entries": [
{
"created_date": "2023-07-13T00:04:02+00:00",
"host": "www.mywebsite.com",
"hosted_page": null,
"id": "GaK0GZEAyJQ2mo9LzAsn",
"pathname": "/",
"tracking_domain": {
"name": "mywebsite.com",
"id": "rJZs4YbXMrvjKP6K0LJk",
"domain": "mywebsite.com"
}
}
],
"tracking_visitor": {
"created_date": "2023-07-13T00:04:02+00:00",
"fingerprint": "f0744494dbb96cca22baeee0262bed79",
"id": "m62V4R1rkw8KYJ5vPcKw",
"ip_address": "123.456.789.0",
"ip_details": {
"ip": "123.456.789.0",
"is_eu": false,
"city": "Washington",
"region": "DC",
"region_code": "DC",
"region_type": "state",
"country_name": "United States",
"country_code": "US",
"continent_name": "North America",
"continent_code": "NA",
"latitude": 12.0124124124124,
"longitude": -72.0124124124124,
"postal": null,
"calling_code": "1",
"asn": {
"asn": "AS123456",
"name": "Acme ISP",
"domain": "acme.com",
"route": "12.34.5.6/16",
"type": "business"
},
"company": {
"name": "Acme ISP",
"domain": "acme.com",
"network": "12.34.5.6/16",
"type": "business"
},
"languages": [
{
"name": "English",
"native": "English",
"code": "en"
}
],
"currency": {
"name": "US Dollar",
"code": "USD",
"symbol": "$",
"native": "$",
"plural": "US dollars"
},
"time_zone": {
"name": "America/New_York",
"abbr": "EDT",
"offset": "-0400",
"is_dst": true,
"current_time": "2023-07-13T00:04:02-04:00"
},
"threat": {
"is_tor": false,
"is_icloud_relay": false,
"is_proxy": false,
"is_datacenter": false,
"is_anonymous": false,
"is_known_attacker": false,
"is_known_abuser": false,
"is_threat": false,
"is_bogon": false,
"blocklists": []
}
},
"user_agent": "Mozilla/5.0"
},
"transactions": [
{
"amount": 49.99,
"approved": true,
"created_date": "2023-07-13T00:13:38+00:00",
"customer_card": {
"type": "Visa",
"id": "bOArW0JnjLkhY2z69K4A",
"first_6": "424242",
"last_4": "4242",
"expiry_date": "12/44",
"expiry_month": "12",
"expiry_year": "2044",
"bin_details": { // SEON Specific
"card_bin": "424242",
"bin_bank": "BANK N.A.",
"bin_card": "VISA",
"bin_type": "DEBIT",
"bin_level": "STANDARD",
"bin_country": "UNITED STATES",
"bin_country_code": "US",
"bin_website": "www.bank.com",
"bin_phone": "1-800-123-4567",
"bin_valid": true,
"card_issuer": "VISA"
}
},
"declined": false,
"error": false,
"gateway_auth_code": "",
"gateway_avs_result_code": "M",
"gateway_cavv_result_code": "",
"gateway_cvv_result_code": "M",
"gateway_id": "L0bZVn7Z8GPbHm068OzM",
"gateway_name": "My Gateway",
"gateway_result_phrase": "approved",
"gateway_transaction_id": "60158956353",
"held": false,
"id": "7NJrwLG0Q5mSb42vWPK5",
"merchant_account_id": "1234567",
"result": "Approved",
"result_code": 1
}
]
},
"expires_on": "2023-09-16T15:35:04+00:00",
"id": "mwPLLyf1rWW4a9Jn6Plo",
"zip_url": "https://userdocument.revcent.com/RANDOM_STRING.zip"
}
],
"total_count": 1,
"total_pages": 1
}Document Filters
Document filters are not available in the current web-app dialog or the current document API request schema. The dialog below replaces the former Advanced filter screen.
Third Party Access
You can provide the ability for external third parties to download documents without the need for an API key. This is done using the RevCent Functions feature.
You can create a Function which has a URL trigger. The function will retrieve the document when the URL is called and return it to the caller.
Function Trigger
Select URL as the function trigger. A unique URL will be generated for the function. Provide this URL to a third party. We recommend setting an IP restriction or other form of authentication to ensure that calls to the URL are from accepted sources.
Function Code
In the function code below, we are using the id and item_type from the URL params to create the document.
If the URL is https://functions.revcent.com/15fff1e7e0ef?item_type=transaction&id=12345 then RevCent will search for a sale where the transaction has a value of 12345 in either its ID or Gateway Transaction ID.
The function passes the URL parameters to the document API request to retrieve the matching sale document.
const request = global.request;
if (typeof context?.source?.url_params?.id === 'string'
&& context.source.url_params.id.length > 0
&& typeof context?.source?.url_params?.item_type === 'string'
&& context.source.url_params.item_type.length > 0) {
findDocument();
} else {
callback(null, 'No ID in URL.')
}
function findDocument() {
let options = {
'method': 'POST',
'url': 'https://api.revcent.com/v2/documents',
'headers': {
'Content-Type': 'application/json',
'x-api-key': process.env.revcent_api_key
},
'json': true,
'body': {
"item_type": context.source.url_params.item_type,
"item_value": context.source.url_params.id
}
};
request(options, function(error, response, body) {
if (error) {
callback(error);
} else {
if (typeof body !== 'undefined') {
callback(null, body);
} else {
callback(null, 'Document not found.');
}
}
});
}Function Import
Download the function import file to import into your RevCent account.