¶ Documents
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 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.
- Filter documents to exclude fields for customization.
¶ 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
When viewing an items' details page page look for the Document button on the top right of the details page.
Click the button and a pop up will appear. The pop up includes the ability to filter the output document. Read more about document filters below.
¶ API
Conduct a document > retrieve request, using the id field as a search field and specifying the originating item type. RevCent will using the item_type and search specific fields using the value for the id property.
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.
{
"request": {
"type": "document",
"method": "retrieve",
"document_type": "sale",
"item_type": "sale",
"id": "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.
| document_type | item_type | Fields Searched | Explained |
|---|---|---|---|
| sale | sale |
|
Searching for a sale using the RevCent sale id |
| sale | transaction |
|
Searching for a sale using the either the RevCent ID of a transaction, or the gateway transaction ID of a transaction. |
| sale | shipping |
|
Searching for a sale using the either the RevCent ID of a shipment, or the tracking number of a shipment. |
| sale | 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. |
| sale | 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.
{
"request": {
"type": "document",
"method": "retrieve",
"document_type": "sale",
"item_type": "transaction",
"id": "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.
{
"request": {
"type": "document",
"method": "retrieve",
"document_type": "sale",
"item_type": "shipping",
"id": "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
There are various ways to filter the output document. Filtering allows you to include or exclude an entire section or sub items within a section based on a specific value(s).
¶ Methods
Filter using field name, and sub field name with dot notation, specifying the fields you wish to exclude, include or search.
¶ Exclude
Exclude fields using the - operator. Example: -api_call will omit the entire api call section. -api_call.id will omit only the id property from the api call section.
¶ Include
Include only certain fields by providing only the fields you want. Example: api_call will include only the API call section in the resulting document. api_call.id will include only the id property in the api call section.
¶ Search
For list sections. Include only items within a list that match a name:value property. Example: transactions.gateway_id=12345 will include only transactions that have the gateway_id equal to 12345 included in the transactions list.
¶ Web App
In the web app, you can filter by using the Advanced tab when creating a document. Input each filter expression on a new line.
¶ API
When creating a document using the API, utilize the document_fields filter. In the example below, we are omitting the api_call and campaign sections entirely.
{
"request": {
"type": "document",
"method": "retrieve",
"document_type": "sale",
"item_type": "sale",
"id": "K77iR5KRvbPnmOa7VZpW",
"filters": {
"document_field_filter": [
"-api_call",
"-campaign"
]
}
}
}
¶ Example Filters
Below are example document field filters with explanations.
Important: If providing documents to third parties and are applying filters, we highly recommend you test the filters to ensure the output document matches your desired output.
-api_callWill exclude the api_call section from the output document.
-api_call
transactions.amountWill exclude the api_call section from the output document.
Will include only the amount property for each transaction in the output document transactions list.
transactions.gateway_id=abc123
transactions.amount
transactions.gateway_transaction_idWill include only transactions in which the gateway_id property equals abc123
Will include only the amount and gateway_transaction_id properties for each transaction in the output document transactions list.
products.sku=PR0001
products.sku=PR0002
-products.nameWill include only products in which the sku property equals PR0001 or PR0002
Will exclude the name property for each product in the output document products list.
-products.sku=PR0005
-tracking_entries
-products.nameWill exclude products in which the sku property equals PR0005
Will exclude the entire tracking entries section
Will exclude the name property for each product in the output document products list.
¶ 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.
We can use the document filters to change the output of the document. Notice in the functions' API call, the document_field_filter property. This allows us to restrict third parties to viewing only the details of sale that are necessary.
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/v1',
'headers': {
'Content-Type': 'application/json',
'x-api-key': process.env.revcent_api_key
},
'json': true,
'body': {
"request": {
"type": "document",
"method": "retrieve",
"document_type": "sale",
"item_type": context.source.url_params.item_type,
"id": context.source.url_params.id,
"filters": {
"document_field_filter": ["-api_call", "-tracking_entries"]
}
}
}
};
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.