Misuse Reporting

Part of the receiver client specification is the logging of unexpected or undesirable behavior back to the registry. Since Versa does not handle the receipt data directly, it relies upon network receivers to report misuse. This process should be automated and should not require human intervention on the receiver’s part — rather the automated reports from the receiver will be handled by humans on the Versa team. If necessary, we will reach out to the partner on the sending side to resolve the issue.

Types of Misuse

There are three broad categories of misuse that a receiver should report:

1. Protocol Errors: Generally, this would suggest a bug in the sender’s client implementation, causing missing or malformed data or data that cannot be decrypted.
2. Schema Validation: This category covers JSON schema validation of the receipt data after it has been successfully decrypted.
3. Semantic Validation: This category covers warning signs in the data itself, such as subtotals not adding up to the header total.

Reporting Misuse

When implementing your client, reporting misuse should be baked into the error handling process. After checking out the key for a given receipt, any error falling into one of the above categories should be identified and posted to the registry.

Take the receipt_id you received, and post it along with any relevant misuse codes.

curl --request POST \
  --url 'https://registry.versa.org/report_misuse' \
  --header 'Authorization: Basic CLIENT_ID:CLIENT_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "receipt_id": "rct_5ed073abbf3a4b49a8c03191f87d8ffe",
    "misuse": [{
      "code": "protocol_decryption_failed"
    }],
  }'

The schema validation and semantic validation steps may yield multiple codes, along with descriptions and (in the case of semantic validation) rule names.

The description and rule fields are optional, but may help us resolve the issue with the sender more quickly.

curl --request POST \
  --url 'https://registry.versa.org/report_misuse' \
  --header 'Authorization: Basic CLIENT_ID:CLIENT_SECRET' \
  --header 'Content-Type: application/json' \
  --data '{
    "receipt_id": "rct_5ed073abbf3a4b49a8c03191f87d8ffe",
    "misuse": [{
      "code": "schema_validation_failed",
      "description": "Property `header` does not match schema. A subschema had errors. Instance does not have required property `total`."
    },
    {
      "code": "semantic_validation_failed",
      "description": "All receipts should include a timezone that best represents either the customer’s physical location at the time of purchase, or the merchant’s region of business.",
      "rule": "all_headers_should_have_tz"
    }],
  }'

List of Misuse Codes

The following is a list of misuse codes that can be reported back to the registry:

Misuse Code	Misuse Description
protocol_decryption_failed	Decrypting the received receipt JSON failed.
protocol_deserialization_failed	Decryption succeeded, but the payload was not valid JSON.
schema_validation_failed	Schema validation of the receipt based on the receipt’s provided schema version failed.
schema_version_invalid	The schema version provided is invalid.
schema_version_unknown	The schema version provided was valid but not recognized.
semantic_validation_failed	Semantic validation returned one or more violations.

Semantic Validation

Semantic validation is a separate domain from protocol correctness and JSON schema validation. Semantic validation consists of a set of rules and rule evaluators, which can result in one or more violations. An example is if the header.total does not equal the sum of the itemized subtotals, taxes, and adjustments, then a semantic violation has occurred.

List of Semantic Validation Rules

Below is the list of semantic validation rules we currently support:

Rule	Description
all_headers_should_have_tz	All receipts should include a timezone that best represents either the customer’s physical location at the time of purchase, or the merchant’s region of business.
flight_fare_at_ticket_or_segment_exclusively	Flight receipts should set the fare at the ticket level, or the segment level, but not both.
header_paid_should_be_sum_of_payments	The sum of all payments should always equal the amount in the header’s 'paid' field.
header_total_should_be_sum_of_itemization	The header total should equal the sum of all line items, taxes, and adjustments.
schema_version_should_be_current	The schema should be updated to the latest version.

Best Practices

It is recommended best practice that all misuse be reported back to the registry. We also recommend that senders implement this validation logic before sending receipt data, but flaws in implementation can still occur. Due to the semi-decentralized nature of the protocol, misuse reporting helps us maintain the integrity of the network.

Validation and misuse reporting is included in our official Rust crate, and we will be adding support for other client libraries soon.

When including misuse descriptions, do not include any data from the receipt itself. Field names are acceptable, but values should be omitted and otherwise may result in the report being rejected.