Basics
Welcome to Covery API documentation
API follows the REST architecture where endpoints are built around the concept of resources, actions are represented by the respective HTTP verb and response statuses are represented using HTTP status codes.
If you have any questions or need an assistance, please contact us.
API endpoint
https://api.covery.ai
Encoding
API uses UTF-8 character encoding.
Access tokens
Every request, sent to the Covery API, must contain access token and signature, based on token secret. Access information is always supplied to customers in pairs during the onboarding process:
Type | Example |
---|---|
Access token | 21a3358f36e5af968b75357590b75c28 |
Token secret | eNfrVfsXQtI+yCIQ9XmuKYP5yBjK0ip7 |
Token levels
There are seven customer token levels:
Level | Permission |
---|---|
event |
sendEvent and nodeName |
decision |
sendEvent, makeDecision and nodeName |
management |
covery portal |
trustchain |
getReputation |
ip screening |
makeIpScreening |
device fingerprint |
device-fingerprint-js |
device screening |
device-fingerprint-js and makeDeviceScreening |
Requests
Request must have a JSON encoded body and following headers:
Header | Description | |
---|---|---|
X-Auth-Token |
mandatory | Access token, received from Covery administrators |
X-Auth-Nonce |
mandatory | Random unique string, used as salt in packet signature |
X-Auth-Signature |
mandatory | Packet signature |
X-Identities |
List of identity nodes in format name1=id1&name2=id2&… , used only in Event and Decision APIs |
hash('sha256', $nonce . $request->getContent() . $secret)
X-Auth-Signature
is sha256 hash, calculated using concatenation of X-Auth-Nonce
,
whole request body (without headers) and auth token secret (received from Covery administrators).
Responses
HTTP/1.1 200 OK
Content-Type: application/json
X-Maxwell-Status: OK
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Maxwell-Status: Exception
X-Maxwell-Error-Type: Maxwell\Exception\NoRouteException
X-Maxwell-Error-Message: Unable to found route for POST /api/wrong/endpoint
API response body can be empty or JSON encoded object or array.
API response status is reported using the appropriate HTTP status code. Additional details are provided by headers.
Name | Description | |
---|---|---|
Content-Type |
mandatory | application/json for most cases, but can be text/plain for errors |
X-Maxwell-Status |
mandatory | OK for success, Exception for errors |
X-Maxwell-Error-Type |
optional | Exception class name in common |
X-Maxwell-Error-Message |
optional | Exception text in common |
X-Maxwell-Error-Context |
optional | May contain additional information about error, such as id when trying to insert entry, that already exists |
Status codes
Code | Description |
---|---|
200 |
OK |
204 |
OK, but no content to respond |
401 |
One of mandatory auth headers missing, or invalid auth token, or invalid auth signature |
403 |
Token access level not sufficient to access requested API |
404 |
No API method for URL or wrong HTTP method |
406 |
Wrong/malformed incoming request data |
409 |
Entry already exist, inspect X-Maxwell-Error-Context header for id |
410 |
Entry not found |
429 |
Too many requests with same sequence_id |
500 |
Internal error |
503 |
API method presents but misconfigured in dependency injection. Please contact us ASAP |
509 |
Too many requests |
510 |
Failed to build application using dependency injection config. Please contact us ASAP |
Health check API
Response example
{
"customerId": 1,
"access":
{
"event": true,
"decision": false,
"management": false,
"utility": false
}
}
Covery API status can be checked by sending ping
request:
Detail | Description |
---|---|
Method | POST |
Endpoint | api/ping |
Access level | Any |
Returns JSON with the information about granted access level for the used token.
If any issues are noticed, please check the system status and contact us ASAP.
Node name API
Request example
{ "nodeNames" : [
{
"nodeType": "Node type1",
"nodeId": "Node id1",
"nodeName": "name1"
},
{
"nodeType": "Node type2",
"nodeId": "Node id2",
"nodeName": "name2"
}
]
}
With Node name API method you can map Node id into readable in reports Node name:
Detail | Description |
---|---|
Method | PUT |
Endpoint | api/nodeName |
Access level | Event, Decision |
Request fields
Field | Type | Description | |
---|---|---|---|
nodeNames | object list |
mandatory | |
nodeType | string |
mandatory | |
nodeId | int |
mandatory | |
nodeName | string |
mandatory |
Event API
Use Event API to send user actions in your product for further analysis of events sent to Decision API.
Detail | Description |
---|---|
Method | POST |
Endpoint | api/sendEvent |
Access level | Event |
Install
Request fields
Field | Type | Description | |
---|---|---|---|
type | string |
mandatory | Value has to be install |
install_timestamp | int |
mandatory | Unix timestamp in seconds |
user_merchant_id | string |
||
sequence_id | string(40) |
See event merge | |
country | string |
ISO ALPHA-3 format, e.g. usa |
|
website_url | string |
||
traffic_source | string |
||
affiliate_id | string |
||
campaign | string |
Implement device fingerprinting to investigate suspicious devices.
Registration
Request fields
Field | Type | Description | |
---|---|---|---|
type | string |
mandatory | Value has to be registration |
registration_timestamp | int |
mandatory | Unix timestamp in seconds |
user_merchant_id | string |
mandatory | |
sequence_id | string(40) |
See event merge | |
age | int |
||
country | string |
ISO ALPHA-3 format, e.g. usa |
|
string |
|||
password | string |
Encrypted user password | |
firstname | string |
||
lastname | string |
||
gender | string |
||
phone | string |
||
social_type | string |
||
user_name | string |
||
website_url | string |
||
traffic_source | string |
||
affiliate_id | string |
||
campaign | string |
Implement device fingerprinting to investigate suspicious devices.
Confirmation
Request fields
Field | Type | Description | |
---|---|---|---|
type | string |
mandatory | Value has to be confirmation |
confirmation_timestamp | int |
mandatory | Unix timestamp in seconds |
user_merchant_id | string |
mandatory | |
sequence_id | string(40) |
See event merge | |
string |
|||
phone | string |
||
email_confirmed | bool |
||
phone_confirmed | bool |
Implement device fingerprinting to investigate suspicious devices.
Login
Request fields
Field | Type | Description | |
---|---|---|---|
type | string |
mandatory | Value has to be login |
login_timestamp | int |
mandatory | Unix timestamp in seconds |
user_merchant_id | string |
mandatory | |
sequence_id | string(40) |
See event merge | |
login_failed | bool |
||
string |
|||
password | string |
Encrypted user password | |
phone | string |
||
gender | string |
||
traffic_source | string |
||
affiliate_id | string |
||
campaign | string |
Implement device fingerprinting to investigate suspicious devices.
Order item
Request fields
Field | Type | Description | |
---|---|---|---|
type | string |
mandatory | Value has to be order_item |
event_id | string |
mandatory | |
event_timestamp | int |
mandatory | Unix timestamp in seconds |
amount | float |
mandatory | |
currency | string |
mandatory | |
order_type | string |
mandatory | Examples: sku, tax, fee, shipping, complex |
amount_converted | float |
If not sent, will be converted to base currency of your account | |
sequence_id | string |
See event merge | |
group_id | string |
See event merge | |
user_merchant_id | string |
||
string |
|||
firstname | string |
||
lastname | string |
||
phone | string |
||
product_description | string |
||
product_name | string |
||
product_quantity | int |
||
website_url | string |
||
product_url | string |
||
product_image_url | string |
||
customer_comment | string |
||
social_type | string |
||
affiliate_id | string |
||
campaign | string |
||
coupon_end_date | int |
Unix timestamp in seconds | |
coupon_id | string |
||
coupon_name | string |
||
coupon_start_date | int |
Unix timestamp in seconds | |
shipping_address | string |
||
shipping_city | string |
||
shipping_country | string |
ISO ALPHA-3 format, e.g. usa | |
shipping_currency | string |
||
shipping_fee | float |
||
shipping_fee_converted | float |
If not sent, will be converted to base currency of your account | |
shipping_state | string |
||
shipping_zip | string |
||
transaction_id | string |
||
carrier | string |
||
carrier_shipping_id | string |
||
carrier_url | string |
||
carrier_phone | string |
||
delivery_estimate | int |
Unix timestamp in seconds | |
order_source | string |
||
source_fee | float |
||
source_fee_currency | string |
||
source_fee_converted | float |
If not sent, will be converted to base currency of your account | |
tax_currency | string |
||
tax_fee | float |
||
tax_fee_converted | float |
Implement device fingerprinting to investigate suspicious devices.
Order submit
Request fields
Field | Type | Description | |
---|---|---|---|
type | string |
mandatory | Value has to be order_submit |
event_id | string |
mandatory | |
event_timestamp | int |
mandatory | Unix timestamp in seconds |
amount | float |
mandatory | |
currency | string |
mandatory | |
items_quantity | int |
mandatory | |
amount_converted | float |
If not sent, will be converted to base currency of your account | |
sequence_id | string |
See event merge | |
group_id | string |
See event merge | |
user_merchant_id | string |
||
string |
|||
firstname | string |
||
lastname | string |
||
phone | string |
||
website_url | string |
||
product_url | string |
||
product_image_url | string |
||
customer_comment | string |
||
social_type | string |
||
affiliate_id | string |
||
campaign | string |
||
coupon_end_date | int |
Unix timestamp in seconds | |
coupon_id | string |
||
coupon_name | string |
||
coupon_start_date | int |
Unix timestamp in seconds | |
shipping_address | string |
||
shipping_city | string |
||
shipping_country | string |
ISO ALPHA-3 format, e.g. usa | |
shipping_currency | string |
||
shipping_fee | float |
||
shipping_fee_converted | float |
If not sent, will be converted to base currency of your account | |
shipping_state | string |
||
shipping_zip | string |
||
transaction_id | string |
||
carrier | string |
||
carrier_shipping_id | string |
||
carrier_url | string |
||
carrier_phone | string |
||
delivery_estimate | int |
Unix timestamp in seconds | |
order_source | string |
||
source_fee | float |
||
source_fee_currency | string |
||
source_fee_converted | float |
If not sent, will be converted to base currency of your account | |
tax_currency | string |
||
tax_fee | float |
||
tax_fee_converted | float |
Implement device fingerprinting to investigate suspicious devices.
Transaction
Request fields
Field | Type | Description | |
---|---|---|---|
type | string |
mandatory | Value has to be transaction |
transaction_amount | float |
mandatory | |
transaction_currency | string |
mandatory | ISO ALPHA-3 format, e.g. usd |
transaction_id | string |
mandatory | |
transaction_timestamp | int |
mandatory | Unix timestamp in seconds |
user_merchant_id | string |
mandatory | |
sequence_id | string(40) |
See event merge | |
payment_method | string |
||
payment_system | string |
||
payment_mid | string |
||
transaction_mode | string |
||
transaction_type | string |
||
payment_account_id | string |
||
card_id | string |
See card id generation | |
card_bin | int |
||
card_last4 | string |
||
expiration_month | int |
||
expiration_year | int |
||
age | int |
||
billing_address | string |
||
billing_city | string |
||
billing_country | string |
ISO ALPHA-3 format, e.g. usa |
|
billing_fullname | string |
If not sent, will consist of billing first and last names | |
billing_firstname | string |
||
billing_lastname | string |
||
billing_state | string |
||
billing_zip | string |
||
country | string |
ISO ALPHA-3 format, e.g. usa |
|
string |
|||
firstname | string |
||
lastname | string |
||
gender | string |
||
merchant_ip | string |
||
merchant_country | string |
ISO ALPHA-3 format, e.g. usa |
|
mcc | string |
||
acquirer_merchant_id | string |
||
phone | string |
||
product_description | string |
||
product_name | string |
||
product_quantity | float |
||
transaction_amount_converted | float |
If not sent, will be converted to base currency of your account | |
user_name | string |
||
website_url | string |
||
transaction_source | string |
||
affiliate_id | string |
||
campaign | string |
Implement device fingerprinting to investigate suspicious devices.
Refund
Request fields
Field | Type | Description | |
---|---|---|---|
type | string |
mandatory | Value has to be refund |
refund_timestamp | int |
mandatory | Unix timestamp in seconds |
refund_id | string |
mandatory | |
refund_amount | float |
mandatory | |
refund_currency | string |
mandatory | ISO ALPHA-3 format, e.g. usd |
refund_amount_converted | float |
If not sent, will be converted to base currency of your account | |
user_merchant_id | string |
||
sequence_id | string(40) |
See event merge | |
string |
|||
phone | string |
||
refund_method | string |
||
refund_system | string |
||
refund_mid | string |
||
refund_source | string |
||
refund_type | string |
E.g. full, partial | |
refund_code | string |
Reason code why refund issued | |
refund_reason | string |
Reason why refund issued | |
agent_id | string |
Person who issued refund |
Implement device fingerprinting to investigate suspicious devices.
Payout
Request fields
Field | Type | Description | |
---|---|---|---|
type | string |
mandatory | Value has to be payout |
payout_timestamp | int |
mandatory | Unix timestamp in seconds |
payout_id | string |
mandatory | |
user_merchant_id | string |
mandatory | |
payout_amount | float |
mandatory | |
payout_currency | string |
mandatory | ISO ALPHA-3 format, e.g. usd |
payout_amount_converted | float |
If not sent, will be converted to base currency of your account | |
sequence_id | string(40) |
See event merge | |
payout_method | string |
||
payout_system | string |
||
payout_mid | string |
||
payout_account_id | string |
||
payout_card_id | string |
See card id generation | |
firstname | string |
||
lastname | string |
||
country | string |
ISO ALPHA-3 format, e.g. usa |
|
string |
|||
phone | string |
||
payout_card_bin | int |
||
payout_card_last4 | string |
||
payout_expiration_month | int |
||
payout_expiration_year | int |
Implement device fingerprinting to investigate suspicious devices.
Transfer
Request fields
Field | Type | Description | |
---|---|---|---|
event_type | string |
mandatory | Value has to be transfer |
event_id | string |
mandatory | |
event_timestamp | int |
mandatory | Unix timestamp in seconds |
user_merchant_id | string |
mandatory | |
account_system | string |
mandatory | |
account_id | string |
mandatory | |
second_account_id | string |
mandatory | |
amount | float |
mandatory | |
currency | string |
mandatory | ISO ALPHA-3 format, e.g. usd |
amount_converted | float |
If not sent, will be converted to base currency of your account | |
sequence_id | string(40) |
See event merge | |
operation | string |
||
transfer_source | string |
||
firstname | string |
||
lastname | string |
||
fullname | string |
||
bic | string |
SWIFT code | |
iban | string |
||
string |
|||
phone | string |
||
birth_date | int |
Unix timestamp in seconds | |
gender | string |
||
country | string |
ISO ALPHA-3 format, e.g. usa |
|
state | string |
||
city | string |
||
address | string |
||
zip | string |
||
second_firstname | string |
||
second_lastname | string |
||
second_fullname | string |
||
second_iban | string |
||
second_email | string |
||
second_phone | string |
||
second_birth_date | int |
Unix timestamp in seconds | |
second_gender | string |
||
second_country | string |
ISO ALPHA-3 format, e.g. usa |
|
second_state | string |
||
second_city | string |
||
second_address | string |
||
second_zip | string |
||
product_name | string |
||
product_description | string |
||
product_quantity | float |
Implement device fingerprinting to investigate suspicious devices.
KYC start
This event initiates KYC procedure for the end user. If it wouldn't be rejected by risk logic - in the decision you will receive a verification URL, where you need to redirect end user.
Request fields
Feature name | Type | Description | |
---|---|---|---|
type | string |
mandatory | Value has to be kyc_start |
event_id | string |
mandatory | |
event_timestamp | int |
mandatory | Unix timestamp in seconds |
user_merchant_id | string |
mandatory | string |
verification_mode | string |
mandatory | Possible values: any, image, video |
verification_source | string |
mandatory | Possible values: any, online, offline |
consent | bool |
mandatory | |
allow_na_ocr_inputs | bool |
If the parameter value is set to 0, the end-user will be required to fill all input fields on OCR confirmation form. | |
decline_on_single_step | bool |
When the value of this parameter is set to 1, it declines the entire verification request when any one of the verification steps fails | |
backside_proof | bool |
If the value of this parameter is set to 1, the end-user will require to capture/upload both sides of the document to verify the identity | |
sequence_id | string(40) |
See event merge | |
group_id | string(40) |
See event merge | |
country | string |
ISO ALPHA-3 format, e.g. usd |
|
kyc_language | string |
ISO ALPHA-2 format, e.g. en |
|
redirect_url | string(256) |
||
string |
|||
firstname | string |
||
lastname | string |
||
profile_id | string |
||
phone | string |
||
birth_date | int |
Unix timestamp in seconds | |
reg_number | string |
||
issue_date | int |
Unix timestamp in seconds | |
expiry_date | int |
Unix timestamp in seconds |
Implement device fingerprinting to investigate suspicious devices.
KYC profile
The event is used to send data about particular profile, e.g. person or company, for ongoing KYC procedure.
Request fields
Field | Type | Description | |
---|---|---|---|
event_type | string |
mandatory | Value has to be kyc_profile |
event_id | string |
mandatory | |
event_timestamp | int |
mandatory | Unix timestamp in seconds |
user_merchant_id | string |
mandatory | |
sequence_id | string(40) |
See event merge | |
group_id | string(40) |
See event merge | |
status | string |
Profile status | |
code | string |
||
reason | string |
||
provider_id | string |
KYC provider event id | |
provider_result | string |
Result from third-party provider | |
provider_code | string |
||
provider_reason | string |
||
profile_id | string |
Profile ID | |
profile_type | string |
Profile type e.g. person, company or document | |
profile_sub_type | string |
Profile subtype e.g. company or document type | |
firstname | string |
||
lastname | string |
||
fullname | string |
Can be also used to send company name | |
gender | string |
||
industry | string |
||
wallet_type | string |
||
website_url | string |
||
description | string |
E.g. clarification of industry or document details | |
final_beneficiary | bool |
||
employment_status | string |
||
source_of_funds | string |
||
birth_date | int |
Unix timestamp in seconds | |
reg_date | int |
Unix timestamp in seconds | |
issue_date | int |
Unix timestamp in seconds | |
expiry_date | int |
Unix timestamp in seconds | |
reg_number | string |
||
vat_number | string |
||
string |
|||
email_confirmed | bool |
||
phone | string |
||
phone_confirmed | bool |
||
contact_email | string |
||
contact_phone | string |
||
country | string |
ISO ALPHA-3 format, e.g. usa |
|
state | string |
||
city | string |
||
address | string |
||
zip | string |
||
nationality | string |
||
second_country | string |
ISO ALPHA-3 format, e.g. usa |
|
second_state | string |
||
second_city | string |
||
second_address | string |
||
second_zip | string |
Implement device fingerprinting to investigate suspicious devices.
KYC submit
The event is used to submit ongoing KYC procedure for the analysis.
Request fields
Field | Type | Description | |
---|---|---|---|
event_type | string |
mandatory | Value has to be kyc_submit |
event_id | string |
mandatory | |
event_timestamp | int |
mandatory | Unix timestamp in seconds |
user_merchant_id | string |
mandatory | |
sequence_id | string(40) |
See event merge | |
group_id | string(40) |
See event merge | |
status | string |
Profile status | |
code | string |
||
reason | string |
||
provider_result | string |
Result from third-party provider | |
provider_code | string |
||
provider_reason | string |
Implement device fingerprinting to investigate suspicious devices.
Event merge
Sequence of user actions
sequence_id
is an optional field in all the events.
It is used to associate consecutive user actions inside your product for deeper understanding of user behavior and more precise decisions.
Sequence example: registration and then transaction made by user within relatively short period of time.
Group of user actions
group_id
is an optional field in the events that support grouping.
It is used to associate a set of user actions under particular sequence_id
to divide the whole sequence into smaller groups of actions.
Group example: registration, [KYC profile of personal details, KYC profiles of documents, KYC submit] - this is a group, and then transaction.
Decision API
Use Decision API to get a risk assessment of user actions in your product. Events which are used only for analysis of other actions should be sent to Event API.
Detail | Description |
---|---|
Method | POST |
Endpoint | api/makeDecision |
Access level | Decision |
Response example
{
"requestId": 7896010,
"type": "transaction",
"createdAt": 1449049571.123,
"sequenceId": "3f3c5e978f90f2a9495bce7492467a65f61333be",
"merchantUserId": "0b836e51a44382126952694dbc0031230fbccf3b",
"score": 80,
"accept": false,
"reject": true,
"manual": false,
"reason": "User 5 cards 1 day, Disposable email domain, Anonymous proxy",
"action": "Additional verification",
"note": "Customer verified manually",
"verificationUrl": "https://covery.ai/comics"
}
Response fields
Field | Type | Description |
---|---|---|
requestId | int |
ID of inserted data |
type | string |
type from request |
createdAt | float |
timestamp |
sequenceId | string |
sequence_id from request |
merchantUserId | string |
user_merchant_id from request |
score | int |
calculated risk score |
accept | bool |
event accepted |
reject | bool |
event rejected |
manual | bool |
event sent to manual review |
reason | string |
explanation of made decision |
action | string |
business flow for made decision |
note | string |
for manual decision only |
verificationUrl | string |
for KYC Start only |
Postback API
Request example when
request_id
is known
{
"request_id": 123456,
"transaction_status": "success",
"code": "4002",
"reason": "Insufficient funds",
"secure3d": "0",
"avs_result": "U",
"cvv_result": "M"
}
Request example when only
transaction_id
is known
{
"transaction_id": "TR123456",
"transaction_status": "success",
"code": "4002",
"reason": "Insufficient funds",
"secure3d": "0",
"avs_result": "U",
"cvv_result": "M"
}
Response example
{
"requestId": 123456
}
This API is used to supply additional data after event processing.
Detail | Description |
---|---|
Method | POST |
Endpoint | api/postback |
Access level | Event |
Request fields
Field | Type | Description |
---|---|---|
request_id | int |
mandatory if no transaction_id present |
transaction_id | string |
mandatory if no request_id present |
transaction_status | string |
|
code | string |
|
reason | string |
|
secure3d | string |
|
avs_result | string |
|
cvv_result | string |
|
psp_code | string |
|
psp_reason | string |
|
arn | string |
Response fields
Field | Type |
---|---|
requestId | int |
Card ID API
This method allows to generate unique sustainable ID of the card for customers who are not PCI DSS compliant. The service is provided in cooperation with our partner Maxpay that is PCI DSS level 1 compliant. Card ID would be generated only for valid card number.
API endpoint:
https://gateway.maxpay.com/api/cc
Request fields
Field | Type | Description | |
---|---|---|---|
api_version | int |
mandatory | Value has to be 1 |
merchant_account | string |
mandatory | Provided by Covery specialist |
merchant_password | string |
mandatory | Provided by Covery specialist |
transaction_type | string |
mandatory | Value has to be CARD_HASH |
card_number | string |
mandatory | Full number of card |
Response
Response example
{
"requestId": 7896010,
"type": "transaction",
"createdAt": 1449049571.123,
"secureStorageId": "5aaaa194f3baaaaade427",
"merchantUserId": "0b836e51a44382126952694dbc0031230fbccf3b"
}
Field | Type | Description |
---|---|---|
requestId | int |
ID of inserted data |
type | string |
type from request |
createdAt | float |
timestamp |
secureStorageId | string |
use as card_id or as payout_card_id |
merchantUserId | string |
user_merchant_id from request |
Trustchain API
This API is used to get item reputation details from Trustchain database.
Detail | Description |
---|---|
Method | POST |
Endpoint | api/getReputation |
Access level | Trustchain |
Request fields
Field | Type | Description | |
---|---|---|---|
itemType | string |
mandatory | Possible values: email, email_domain, card_id, phone, ip, system_account_id, device_fingerprint, device_id, entity_id, person_id, iban, bic |
itemValue | string |
mandatory |
Response example
{
"requestId": 12,
"createdAt": 1579590089,
"private": {
"reputation": "trusted",
"sources": "Test data, Pilot data",
"firstSeenDate": 1579076134,
"reputationСhangeDate": 1579076134
},
"global": {
"reputation": "trusted",
"sources": "Test data, Pilot data",
"firstSeenDate": 1579076134,
"reputationСhangeDate": 1579076134
},
"industries": [
{
"name": "charity",
"reputation": "trusted",
"sources": "Test data, Pilot data",
"firstSeenDate": 1579076134,
"reputationСhangeDate": 1579076134
},
{
"name": "airlines",
"reputation": "trusted",
"sources": "Test data, Pilot data",
"firstSeenDate": 1579076134,
"reputationСhangeDate": 1579076134
}
]
}
Response fields
Field | Type | Description |
---|---|---|
requestId | int |
ID of inserted data |
createdAt | int |
Timestamp |
private | object |
See Private and Global Object |
global | object |
See Private and Global Object |
industries | object |
See Industries Object |
Private and Global Objects
Field | Type | Description |
---|---|---|
reputation | string |
Possible values: Trusted, Suspicious, Untrusted, Neutra |
source | string list |
Possible values: Auto decision - fraud, Auto decision - hacked, Auto decision - not fraud, Auto decision - verified, Client request - fraud, Client request - hacked, Client request - not fraud, Client request - verified, Manual decision - fraud, Manual decision - hacked, Manual decision - not fraud, Manual decision - verified, Bonus abuse, Emulation, Bot, Self-exclusion, VIP customer, Underage, Watch list, Payment - bank negative list, Payment - canceled subscription, Payment - chargeback, Payment - fraud alert, Payment - lost or stolen card, Payment - retrieval request, Pilot data, Test data, Third party - marketing, Third party - other |
firstSeenDate | int |
|
reputationСhangeDate | int |
Industries Object
Field | Type | Description |
---|---|---|
name | string |
Possible values: Airlines, Charity, Crowdfunding, Dating, Digital, Educatoin, Finance, Food, Gambling, Gaming, Hospitality, Insurance, Luxury, Manufacturing, Nutra, Other, Payment aggregators, Pharma, Retail, Telecommunications, Ticketing, Transportation, Travel, Utilities |
reputation | string |
Possible values: Trusted, Suspicious, Untrusted, Neutra |
source | string list |
Possible values: Auto decision - fraud, Auto decision - hacked, Auto decision - not fraud, Auto decision - verified, Client request - fraud, Client request - hacked, Client request - not fraud, Client request - verified, Manual decision - fraud, Manual decision - hacked, Manual decision - not fraud, Manual decision - verified, Bonus abuse, Emulation, Bot, Self-exclusion, VIP customer, Underage, Watch list, Payment - bank negative list, Payment - canceled subscription, Payment - chargeback, Payment - fraud alert, Payment - lost or stolen card, Payment - retrieval request, Pilot data, Test data, Third party - marketing, Third party - other |
firstSeenDate | int |
|
reputationСhangeDate | int |
IP screening API
This API is used to get risk assessment of IP.
Response example
{
"requestId": 12,
"createdAt": 1579590089,
"reputation": [
"private": {
"reputation": "trusted",
"sources": "Test data, Pilot data",
"firstSeenDate": 1579076134,
"reputationСhangeDate": 1579076134
},
"global": {
"reputation": "trusted",
"sources": "Test data, Pilot data",
"firstSeenDate": 1579076134,
"reputationСhangeDate": 1579076134
},
"industries": [
{
"name": "charity",
"reputation": "trusted",
"sources": "Test data, Pilot data",
"firstSeenDate": 1579076134,
"reputationСhangeDate": 1579076134
},
{
"name": "airlines",
"reputation": "trusted",
"sources": "Test data, Pilot data",
"firstSeenDate": 1579076134,
"reputationСhangeDate": 1579076134
}
]
]
"ipProperties" [
"city": "battle creek",
"country": "usa",
"countryLanguages": [
"en-us",
"en-us",
"en",
"es-us",
"es-us",
"es",
"haw",
"fr"
],
"countryTimeZones": [
-420,
-600,
-360,
-540,
-300,
-480,
-240
],
"isp": "comcast cable communications inc.",
"latitude": -85.2066,
"longtitude": 42.2967,
"postalCode": "49015"
"isProxy": true
"proxyType": "corporate"
]
"screeningResult" [
"score": 80
"reason": ["User 5 cards 1 day, Disposable email domain, Anonymous proxy"]
"decision": "reject"
"action": "Additional verification"
]
}
Details | Description |
---|---|
Method | POST |
Endpoint | api/makeIpScreening |
Access level | Ip screening |
Request fields
Field | Type | Description |
---|---|---|
IP | string |
mandatory |
Response fields
Field | Type | Description |
---|---|---|
requestId | int |
ID of inserted data |
createdAt | int |
Timestamp |
reputation | object |
See reputation object |
ipProperties | object |
See ipProperties object |
score | int |
Calculated risk score |
reason | string list |
Explanation of made decision |
decision | string |
Possible values: accept, manual, reject |
action | string |
business flow for made decision |
Reputation Object
Field | Type | Description |
---|---|---|
private | object |
See Private and Global Object |
global | object |
See Private and Global Object |
industries | object |
See Industries Object |
ipProperties Object
Field | Type | Description |
---|---|---|
city | string |
|
country | string |
|
countryLanguages | string list |
|
countryTimeZones | int list |
|
isp | string |
|
latitude | double |
|
longtitude | double |
|
postalCode | string |
|
isProxy | boolean |
|
proxyType | string |
Device fingerprint
We scan user device and grab an enormous amount of parameters, inluding an operating system, browser and its version, installed plug-ins, screen resolution, platform, IP address, and many others. Using the combination of these parameters, our system generates unic device fingerprint ID.
In order to use device fingerprint pixel, you must provide the URL, on which it will be placed, or use the method of dynamic pixel generation. Dynamic pixel will be valid for a seconds and can be placed on any page without URL whitelisting from Covery side.
Details | Description |
---|---|
Method | GET |
Endpoint | resources/device-fingerprint-js |
Access level | Device fingerprint or Device screening |
Response will contains one time valid js script.
Device fingerprint pixel
Example of handleCoveryFpKey function
<script>
var deviceFingerprint;
function handleCoveryFpKey(key) {
deviceFingerprint = key;
// device fingerprint is stored
// in a global variable deviceFingerprint
}
</script>
Every event contains optional fields listed below to help us investigate suspicious devices. In order to allow us handle all the work for you, please follow the next steps:
Include <script async src=“https://api.covery.ai/resources/covery.js“></script> on the destination page
Define function handleCoveryFpKey and covery.js will call it with the device fingerprint as argument
Send the device fingerprint in the device_fingerprint field
Device fields
Field | Type | Description | |
---|---|---|---|
ajax_validation | bool |
presence of AJAX - Asynchronous JavaScript And XML | |
cookie_enabled | bool |
cookie option in a web browser | |
cpu_class | string |
central processing unit (CPU) of the device | |
device_fingerprint | string |
unique device identifier, the "key" from js responce | |
device_id | string |
mobile device identifier assigned inside the mobile application | |
do_not_track | bool |
incognito mode in a web browser | |
ip | string |
||
real_ip | string |
IP behind the proxy server | |
local_ip_list | string list |
list of local IP addresses connected to the device | |
language | string |
user's browser language | |
languages | string |
user's preferred languages | |
language_browser | string |
user's operating system language | |
language_user | string |
user's locale operating system language | |
language_system | string |
default operating system language | |
os | string |
operating system of the device | |
screen_resolution | string |
resolution of the device screen | |
screen_orientation | string |
orientation of the device screen | |
client_resolution | string |
web browser or other application resolution that displays the web page | |
timezone_offset | int |
current minute offset from UTC (Coordinated Universal Time) for the given time zone | |
user_agent | string |
string of user agent | |
plugins | string list |
list of installed plugins on web browser | |
referer_url | string |
||
origin_url | string |
Device screening API
This API is used to get risk assessment of device.
Response example
{
"requestId": 12,
"createdAt": 1579590089,
"ipReputation": {
"private": {
"reputation": "trusted",
"sources": [
"Test data",
"Pilot data"
],
"firstSeenDate": 1579076134,
"reputationСhangeDate": 1579076134
},
"global": {
"reputation": "trusted",
"sources": [
"Test data",
"Pilot data"
],
"firstSeenDate": 1579076134,
"reputationСhangeDate": 1579076134
},
"industries": [
{
"name": "charity",
"reputation": "trusted",
"sources": [
"Test data",
"Pilot data"
],
"firstSeenDate": 1579076134,
"reputationСhangeDate": 1579076134
},
{
"name": "airlines",
"reputation": "trusted",
"sources": [
"Test data",
"Pilot data"
],
"firstSeenDate": 1579076134,
"reputationСhangeDate": 1579076134
}
]
},
"ipProperties": {
"city": "battle creek",
"country": "usa",
"countryLanguages": [
"en-us",
"en-us",
"en",
"es-us",
"es-us",
"es",
"haw",
"fr"
],
"countryTimeZones": [
-420,
-600,
-360,
-540,
-300,
-480,
-240
],
"isp": "comcast cable communications inc.",
"latitude": -85.2066,
"longtitude": 42.2967,
"postalCode": "49015",
"isProxy": true,
"proxyType": "corporate"
},
"deviceReputation": {
"private": {
"reputation": "trusted",
"sources": [
"Test data",
"Pilot data"
],
"firstSeenDate": 1579076134,
"reputationСhangeDate": 1579076134
},
"global": {
"reputation": "trusted",
"sources": [
"Test data",
"Pilot data"
],
"firstSeenDate": 1579076134,
"reputationСhangeDate": 1579076134
},
"industries": [
{
"name": "charity",
"reputation": "trusted",
"sources": [
"Test data",
"Pilot data"
],
"firstSeenDate": 1579076134,
"reputationСhangeDate": 1579076134
},
{
"name": "airlines",
"reputation": "trusted",
"sources": [
"Test data",
"Pilot data"
],
"firstSeenDate": 1579076134,
"reputationСhangeDate": 1579076134
}
],
"deviceProperties": {
"ajaxValidation": "false",
"cookieEnabled": "true",
"cpuClass": "554",
"deviceFingerprint": "dvtwl9ef7d98faf03e93ff19619e19d2",
"doNotTrack": "false",
"ipList": [
"192.168.1.1",
"192.168.1.2"
],
"language": "fr-fr",
"languageBrowser": "fr-fr",
"languageSystem": "fr-fr",
"languageUser": "fr-fr",
"languages": "fr-fr",
"os": "windows 10",
"screenOrientation": "horizontal",
"screenResolution": "1366x768",
"clientResolution": "674x496",
"timezoneOffset": 60,
"userAgent": "mozilla\/5.0 (windows nt 10.0; win64; x64) applewebkit\/537.36 (khtml, like gecko) chrome\/79.0.3945.130 safari\/537.36",
"plugins": [
"chrome pdf plugin",
"native client",
"chrome pdf viewer"
],
"refererUrl": "https:\/\/hpp.covery.com",
"originUrl": "https:\/\/hpp.covery.com"
},
"screeningResult": {
"score": 80,
"reason": [
"User 5cards 1day",
"Disposable email domain",
"Anonymous proxy"
],
"decision": "reject",
"action": "Additional verification"
}
}
}
Details | Description |
---|---|
Method | POST |
Endpoint | api/makeDeviceScreening |
Access level | Device screening |
Request fields
Field | Type | Description |
---|---|---|
device_fingerprint | string |
mandatory |
Response fields
Field | Type | Description |
---|---|---|
requestId | int |
ID of inserted data |
createdAt | int |
Timestamp |
ipReputation | object |
See Reputation object |
deviceReputation | object |
See Reputation object |
ipProperties | object |
See ipProperties object |
deviceProperties | object |
See deviceProperties object |
score | int |
Calculated risk score |
reason | string list |
Explanation of made decision |
decision | string |
Possible values: accept, manual, reject |
action | string |
Business flow for made decision |
deviceProperties Object
Field | Type | Description |
---|---|---|
cookieEnabled | boolean |
|
deviceFingerprint | string |
|
doNotTrack | boolean |
|
ipList | string list |
|
language | string |
|
os | string |
|
screenResolution | string |
|
clientResolution | string |
|
timezoneOffset | int |
offset in minutes |
userAgent | string |
|
plugins | string list |
|
refererUrl | string |
|
originUrl | string |
Fraud alert API
This subset of APIs is dedicated for fraud alert handling.
Fraud alert fields
Fraud alert example
{
"id": 8464503,
"source": "ethoca",
"externalId": "5SNLJ1WOKODEUPLY396439RT4",
"type": "issuer_alert",
"state": "none",
"cardBin": "502006",
"cardLast4": "7616",
"alertTimestamp": 1459521191,
"transactionTimestamp": 1459521191,
"transactionAmount": 28.55,
"transactionCurrency": "USD",
"is3dSecure": null,
"arn": "43792622030200003292612",
"chargebackAmount": 0,
"chargebackCurrency": "",
"chargebackReasonCode": "",
"merchantDescriptor": "EXAMPLE"
}
Field | Type | Description |
---|---|---|
id | int |
Fraud alert identifier |
source | string |
Fraud alert source |
externalId | string |
External fraud alert identifier |
type | string |
Fraud alert type |
state | string |
Current fraud alert state |
cardBin | string |
First 6 numbers of user's credit card number |
cardLast4 | string |
Last 4 numbers of user's credit card number |
arn | string |
Acquirer reference number |
merchantDescriptor | string |
Merchant descriptor |
is3dSecure | boolean or null |
Was transaction under 3D secure or not (true , false , null for unknown) |
alertTimestamp | int |
Alert time (Unix timestamp) |
transactionAmount | float |
Original transaction amount |
transactionCurrency | string |
Original transaction currency |
transactionTimestamp | int |
Original transaction time (Unix timestamp) |
chargebackAmount | float |
Chargeback amount |
chargebackCurrency | string |
Chargeback currency |
chargebackTimestamp | int |
Chargeback time (Unix timestamp) |
List of values for type
field
Value | Description |
---|---|
empty string | |
issuer_alert |
Confirmed fraud |
fraudreporter_alert |
Confirmed fraud |
customerdispute_alert |
Customer dispute |
Confirmed fraud states
Value | Description |
---|---|
none |
Fraud alert just received |
stopped |
|
partially_stopped |
|
previously_cancelled |
|
missed |
|
notfound |
|
account_suspended |
|
in_progress |
|
shipper_contacted |
|
other |
Customer dispute states
Value | Description |
---|---|
none |
Fraud alert just received |
resolved |
|
previously_refunded |
|
unresolved_dispute |
|
notfound |
|
other |
Latest alerts
Use this API to receive all latest fraud alerts available for your account.
Detail | Description |
---|---|
Method | POST |
Endpoint | api/manage/fraud/latest |
Access level | Decision, Management |
Request fields
Field | Type | Description |
---|---|---|
limit | int |
Limit amount of entries (1-100) |
Response
List of fraud alerts with the fields listed above.
Alert by ID
Use this API to receive details for particular fraud alert using its ID.
Detail | Description |
---|---|
Method | POST |
Endpoint | api/manage/fraud/find |
Access level | Decision, Management |
Request fields
Field | Type | Description |
---|---|---|
id | int |
Identifier of fraud alert |
Response
Single fraud alert with the fields listed before.
Alert confirmation
Use this API to confirm retrieval of fraud alerts.
Detail | Description |
---|---|
Method | POST |
Endpoint | api/manage/fraud/confirm |
Access level | Decision |
Request fields
Field | Type | Description |
---|---|---|
id | int |
Identifier of fraud alert |
Response
Empty response.
Alert feedback
Use this API to process received fraud alerts.
Detail | Description |
---|---|
Method | POST |
Endpoint | api/manage/fraud/feedback |
Access level | Management |
Request fields
Field | Type | Description |
---|---|---|
id | int |
Identifier of fraud alert |
result | string |
See Confirmed fraud and Customer dispute states |
refunded | string |
none , refunded , not_refunded , not_settled |
Response
Empty response.
Alert callback
If it is configured, Covery will send callback for every incoming fraud alert to the defined URL.
Callback contains fraud alert details (same as get fraud alert by ID) with the following headers:
Type | Description |
---|---|
X-Auth-Nonce |
Signature salt |
X-Auth-Signature |
Callback signature |
$signature = $hash = hash('sha256', $nonce . $body . $secret);
Callback signature is calculated as sha256 checksum from concatenated signature salt, request body and secret, which was sent to you during the configuration process.
If you have any questions or need an assistance, please contact us.
VMPI API
OI provides merchants the ability to share transaction details with the Issuer for charges that questioned by the cardholder. This information is then used by the issuer in their communication with the cardholder in an attempt to resolve the customer’s needs without initiating a chargeback.
Requests
Request must have a JSON encoded body and following headers:
Header | Description | |
---|---|---|
X-Auth-Token |
mandatory | Should be provided by Covery customer |
X-Auth-Nonce |
mandatory | Random unique string, used as salt in packet signature |
X-Auth-Signature |
mandatory | Packet signature. It is sha256 hash, calculated using concatenation of X-Auth-Nonce, whole request body (without headers) and auth token secret (should be provided by Covery customer). |
Request fields
Field | Type | Description | |
---|---|---|---|
requestId | int |
mandatory | internal Covery alert ID |
sellerID | string |
mandatory | |
arn | string |
Acquirer Reference Number associated with settled transactions | |
settlementAmount | double |
settlement amount of the transaction | |
settlementCurrency | string |
settlement currency for the transaction | |
settlementDate | int |
settlement date of the transaction, unix timestamp | |
creditCardBin | int |
first 6 digits (BIN) of the credit card used for the transaction | |
creditCard4 | string |
last 4 digits of the credit card used for the transactio | |
authorizationAmount | double |
authorization amount of the transaction | |
authorizationCurrency | string |
authorization currency for the transaction | |
authorizationDate | int |
authorization date of the transaction, unix timestamp | |
authorizationCode | string |
authorization code for the transaction | |
orderId | string |
merchant-created unique value that references the cardholders purchase request | |
transactionId | string |
||
nodeType | string |
||
nodeId | string |
Response
Top-Level Object
Field | Type | Description | |
---|---|---|---|
arn | string |
mandatory, if was present in request | Acquirer Reference Number associated with settled transactions, Max Length 23 |
orderId | string |
mandatory, if was present in request | Merchant-created unique value that references the cardholders purchase request |
orderDate | int |
mandatory, if was present in request | Date of the order |
paymentDescriptor | string |
mandatory, if was present in request | Merchant payment descriptor found on the cardholder’s bank statement, Max Length 25 |
authorizationCode | string |
mandatory, if was present in request | Authorization code for the transaction |
authorizationDate | int |
mandatory, if was present in request | Authorization date of the transaction |
authorizationCurrency | string |
mandatory, if was present in request | Authorization currency for the transaction |
authorizationAmount | float |
mandatory, if was present in request | Authorization amount of the transaction |
settlementDate | int |
mandatory, if was present in request | Settlement date of the transaction |
settlementCurrency | string |
mandatory, if was present in request | Settlement currency for the transaction |
settlementAmount | float |
mandatory, if was present in request | Settlement amount of the transaction |
creditCardBin | int |
mandatory, if was present in request | First 6 digits (BIN) of the credit card used for the transaction |
creditCardLast4 | string |
mandatory, if was present in request | Last 4 digits of the credit card used for the transaction |
details | object |
Details Object |
Details Object
Field | Type | Description |
---|---|---|
transactionDetail | object |
Transaction Detail Object |
customerInformation | object |
Customer Information Object |
pastTransactions | object list |
Past Transactions Object |
productPurchased | object list |
Product Purchased Object |
customFields | object list |
Custom Fields Object |
deliveryDetails | object |
Delivery Details Object |
crmDetails | object list |
CRM Details Object |
attachments | object list |
Attachments Object |
Transaction Detail Object
Field | Type | Description |
---|---|---|
taxAmount | float list |
Tax amount(s) charged on the transaction |
taxAmountCurrency | string list |
Tax amount currency(ies) for the transaction. The number of tax amounts must be equal to the number of tax currencies. |
shippingAndHandlingAmount | float list |
Shipping and handling amount(s) for the purchase |
shippingAndHandlingCurrency | string list |
Shipping and handling currency(ies) for the purchase. The number of shipping and handling amounts must be equal to the number of shipping and handling currency(ies). |
totalAmount | float |
Total amount of the transaction, including purchase price, tax, and shipping and handling |
totalAmountCurrency | string |
Total amount currency for the transaction |
recurringTransaction | string |
If recurring transactions, state frequency for recurring period, eg. month on 25th, every 4 weeks, annually on May15, etc |
paymentInstrument | string |
Card type – Visa, MC, AMEX or Discover |
billingAddress | string |
Customer’s billing address – if billing address is not collected then indicate “billing address not collected” |
shippingAddress | string list |
Address(es) listed for associated delivery |
billingAddressDetails | object |
Address Object |
shippingAddressDetails | object list |
Address Object |
avsChecked | boolen |
Whether credit card AVS response was received |
avsResultCode | string |
AVS response code received – provide the code and description e.g., Y – exact match or A – zip match only |
cvvChecked | boolen |
Whether credit card CVV code was checked |
cvvResultCode | string |
CVV response code received – provide the code and description e.g., M – match or N – no match |
threeDSHallenged | boolen |
Whether there was a 3DSecure attempt from the merchant |
threeDSEciCode | string |
Two-digit code indicating the outcome of the 3DSecure attemp. Max Length 2 |
threeDSTransactionId | string |
Transaction identifier resulting from 3DSecure call (xid) |
threeDSAuthenticationValue | string |
Cardholder Authentication Verification. Value resulting from completion of 3DSecure (cavv) |
refundProcessed | boolen |
True if a refund was processed |
refundAmount | float |
Refund amount, if applicable |
refundCurrency | string |
Refund currency |
dateOfRefund | int |
Date of refund. If multiple, provide the most recent date of refund |
registeredCustomer | boolen |
True if the customer is registered with the merchant. |
deviceName | string |
Name of device used to submit order (e.g., John’s iphone or John’s desktop) |
deviceId | string |
Device ID that was used to place order |
deviceLocation | string |
Location of device at the time of the order (city, state, country) |
ipAddress | string |
IP address associated with the device |
orderChannel | string |
Identifies how the order was submitted: web, physical store, mobile, etc |
orderLocation | string |
Location of order: GPS coordinates, friendly location, city name, street address, etc. |
paymentTerms | string |
The seller’s payment terms (Merchant Link) |
refundPolicy | string |
The seller’s refund policy (Merchant Link) |
warrantyTerms | string |
The seller’s warranty terms (Merchant Link) |
termsAndConditions | string |
The seller’s terms and conditions (Merchant Link) |
notes | string |
Any seller notes |
Customer Information Object
Field | Type | Description |
---|---|---|
firstName | string |
Customer’s first name |
lastName | string |
Customer’s last name |
dateOfBirth | int |
Customer’s date of birth |
customerId | string |
Unique customer ID with merchant |
firstTransactionDate | int |
Date of customer’s first transaction |
lengthOfRelationship | string |
Length of customer relationship: 5 years, 3 months, etc. |
authenticationUsed | string |
Authentication completed by customer to begin subscription: driver’s license, facebook profile, etc. |
notes | string |
Any notes associated with the customer |
phoneNumber | object list |
Phone Number Object |
emailAddress | object list |
Email Address Object |
Address Object
Field | Type | Description |
---|---|---|
address | string list |
Street address plus additional address lines such as suite number, apartment, etc. |
city | string |
City |
state | string |
State |
zip | string |
Zip or postal code |
country | string |
Country, ISO ALPHA,-3 format, e.g. usa |
Phone Number Object
Field | Type | Description |
---|---|---|
phoneType | string |
Customer’s phone type: home, work, etc |
phoneNumber | string |
Customer’s phone number |
Email Address Object
Field | Type | Description |
---|---|---|
emailName | string |
Customer’s email name: personal, work |
emailAddress | string |
Customer’s email address |
Past Transactions Object
Field | Type | Description |
---|---|---|
dateOfPurchase | int |
Date of past transaction |
currencyOfPurchase | string |
Currency of past transaction |
amountOfPurchase | float |
Amount of past transaction |
creditCardBin | int list |
First 6 digits (BIN) of the credit card used for the transaction |
creditCardLastFour | string list |
Last 4 digits of the credit card used for the transaction |
orderId | string list |
Merchant-created unique value that references the cardholders purchase request |
transactionId | string |
Transaction id |
transactionType | string |
Sale or Refund |
recurringTransaction | string |
If recurring transactions, state frequency for recurring period, eg. month on 25th, every 4 weeks, annually on May15, etc. |
Product Purchased Object
Field | Type | Description |
---|---|---|
productName | string |
The product name |
productModel | string |
The product model |
productSku | string |
The product SKU (item ID) |
productDescription | string |
The product description – use as much detail as possible |
productUrl | string |
URL to product purchase site |
productImageUrl | string |
URL to product image |
unitPriceCurrency | string |
Unit price currency for the product |
unitPriceAmount | float |
Unit price amount of the product |
quantity | int |
Number of products purchased |
notes | string |
Any notes associated with the purchase |
industryDetails | object |
Industry Details Object |
Custome Fields Object
Field | Type | Description |
---|---|---|
<name> |
string |
Custom field naming to present to Issuers. Up to 10. Max Length 500 |
<value> |
string |
Content associated with the custom field name provided. Up to 10. Max Length 500 |
Delivery Details Object
Field | Type | Description |
---|---|---|
physicalFulfillment | object list |
Physical Fulfillment Object |
digitalServiceDelivery | object list |
Digital Service Delivery Object |
Physical Fulfillment Object
Field | Type | Description |
---|---|---|
shippingCarrierUrl | string |
Shipper’s URL |
shippingCarrierPhone | string |
Shipper’s phone number |
trackingNumber | string |
Shipper’s tracking number |
dateOfShipment | int |
Shipper’s date of shipment |
dateOfDelivery | int |
Shipper’s date of delivery |
signatureConfirmation | string |
Signature confirming shipment arrival |
signedBy | string |
Name of individual signing to confirm arrival of merchandise |
exceptionNotes | string |
Notes specific to any delivery fulfillment (Example: wrong email, wrong address, signature required, etc.) |
notes | string |
Delivery notes specific to customer interaction |
Digital Service Delivery Object
Field | Type | Description |
---|---|---|
proofOfDelivery | string |
Evidence the digital product/service is available to customer (Example: downloads, activation email, etc.) |
proofOfUsage | string |
Evidence the customer interacted with the product/service (Login, and time of use, etc.) |
locationOfUsage | string |
Location or IP address of device at the time of last usage |
frequencyOfUsage | string |
Number of times the service was accessed/used |
notes | string |
Any customer notes associated with digital goods/services |
CRM Details Object
Field | Type | Description |
---|---|---|
dateOfInteraction | int |
Date of customer contact |
contactMethod | string |
Email, mail, chat, phone |
merchantAgentUser | string |
Name of customer service agent interacting with the customer |
contactName | string |
Consumer Name |
ipAddress | string |
IP Address during contact |
emailAddress | object |
Email Address Object |
phoneNumber | object |
Phone Number Object |
deviceName | string |
Name of device used to make contact |
deviceId | string |
Device ID that was used during contact |
deviceLocation | string |
Location of device at the time pf contact |
communicationInitator | string |
Consumer or Merchant |
communicationType | string |
Order Confirmation, Shipping Confirmation, Notice of Renewal |
communicationStatus | string |
If email, was email bounced back, viewed, opened, etc |
notes | string |
Details of customer contact – this could include details like “customer called to check on status of order” or “customer submitted chat request with questions on accessing site” and include details of resolution by merchant. If no contact from customer then must include “customer has not contacted us at this time” |
Industry Details Object
Field | Type | Description |
---|---|---|
flightDetails | object |
Flight Details Object |
hotelDetails | object |
Hotel Details Object |
flightNumber | string |
Flight number |
flightDate | int |
Date of flight |
manifest | string |
Flight manifest information |
memberRewardsNumber | string |
Member rewards number |
pointsRedeemed | boolen |
Did consumer use reward points towards purchase |
Flight Details Object
Field | Type | Description |
---|---|---|
flightNumber | string |
Flight number |
flightDate | int |
Date of flight |
manifest | string |
Flight manifest information |
memberRewardsNumber | string |
Member rewards number |
pointsRedeemed | boolen |
Did consumer use reward points towards purchase |
Hotel Details Object
Field | Type | Description |
---|---|---|
reservationNumber | string |
Reservation number |
reservationDate | int |
Date reservation was made |
checkInDate | int |
Check in Date |
checkOutDate | int |
Check out Date |
memberRewardsNumber | string |
Member rewards number |
pointsRedeemed | boolen |
Did consumer use reward points towards purchase? |
Attachments Object
Field | Type | Description | |
---|---|---|---|
id | string |
Merchant’s ID for the document | |
fileName | string |
mandatory | Attachment file name |
friendlyFileName | string |
Friendly file name that will override file naming convention if entered | |
mimeType | string |
mandatory | MIME Content Type |
receivedDate | int |
Date file was received by merchant | |
fileSource | string |
Source of the file – uploaded by customer, generated by merchant, merchant contract | |
data | string |
mandatory | File attachment content, BASE64 encoded |