Crate versa 

Versa Protocol Rust SDK

The official Rust implementation of the Versa Protocol, providing types and utilities for developing Versa client applications.

Overview

Versa is an open protocol that allows any service to send itemized receipts, invoices, and other transaction records directly to their customers in a structured, machine-readable format. This crate provides:

• Schema Types: Strongly-typed representations of Versa receipts and itineraries
• Protocol Types: Core protocol messages for customer registration, webhooks, and misuse reporting
• Client Utilities: Helper functions for sending and receiving Versa documents
• Validation: Schema validation for ensuring document compliance

Feature Flags

This crate uses feature flags to minimize dependencies:

• client: Core client functionality (HTTP requests, encryption, HMAC)
• client_sender: Utilities for services sending receipts
• client_receiver: Utilities for services receiving receipts
• validator: JSON Schema validation support

Quick Start

As a Sender (Merchant/Service)

use versa::schema::receipt::{Receipt, Header, Currency};
use versa::schema::current::SCHEMA_VERSION;
use std::str::FromStr;

// Create a receipt
let receipt = Receipt {
    schema_version: SCHEMA_VERSION.parse()?,
    header: Header {
        total: 10000, // $100.00 in cents
        currency: Currency::from_str("usd")?,
        subtotal: 10000,
        invoiced_at: 1234567890,
        paid: 10000,
        customer: None,
        invoice_asset_id: None,
        invoice_number: None,
        location: None,
        mcc: None,
        receipt_asset_id: None,
        third_party: None,
    },
    itemization: versa::schema::receipt::Itemization::builder().try_into()?,
    payments: vec![],
    footer: versa::schema::receipt::Footer::builder().try_into()?,
};

// Send to customer using client_sender feature
#[cfg(feature = "client_sender")]
{
    use versa::client_sender::send_receipt;
    // send_receipt(&receipt, "customer@example.com").await?;
}

As a Receiver (Inbox/Aggregator)

use versa::protocol::webhook::{WebhookEvent, WebhookEventType};
use versa::schema::receipt::Receipt;

// Parse incoming webhook
let webhook_event: WebhookEvent<Receipt> = serde_json::from_str(&body)?;

// Verify and process the receipt using client_receiver feature
#[cfg(feature = "client_receiver")]
{
    use versa::client_receiver::verify_webhook;
    if verify_webhook(&signature, &body, &"webhook_secret")? {
        match webhook_event.event {
            WebhookEventType::Receipt => {
                println!("Received receipt: ${:.2}", webhook_event.data.header.total as f64 / 100.0);
            }
            _ => {
                println!("Received other webhook event");
            }
        }
    }
}

Architecture

The crate is organized into several modules:

• protocol: Core protocol types for Versa communication
• schema: Document schemas (receipts, itineraries) with full type definitions
• [client]: Common client functionality (available with client feature)
• [client_sender]: Sender-specific utilities (available with client_sender feature)
• [client_receiver]: Receiver-specific utilities (available with client_receiver feature)

Schema Versions

This crate supports multiple schema versions:

• 2.0.0: Current version with nullable array support
• 1.11.0: Legacy version

For more information about the Versa Protocol, visit https://versa.org.

Modules

protocol

Protocol types for Versa communication including customer registration, webhooks, and misuse reporting. Core protocol types for Versa communication.

schema

Document schemas for receipts and itineraries with full type definitions. Schema module containing type definitions for all LTS versions