papers/hanzo-commerce-payments.tex

\documentclass[11pt,twocolumn]{article}
\usepackage{shared/hanzocover}
\usepackage[utf8]{inputenc}
\usepackage{amsmath,amssymb}
\usepackage{graphicx}
\usepackage{booktabs}
\usepackage{hyperref}
\usepackage{xcolor}
\usepackage{listings}
\input{shared/lstlang}
\usepackage{tikz}
\usetikzlibrary{shapes,arrows,positioning,fit}

\definecolor{codegreen}{rgb}{0,0.6,0}
\definecolor{codegray}{rgb}{0.5,0.5,0.5}
\definecolor{codepurple}{rgb}{0.58,0,0.82}
\definecolor{backcolour}{rgb}{0.95,0.95,0.92}

\lstdefinestyle{mystyle}{
    backgroundcolor=\color{backcolour},
    commentstyle=\color{codegreen},
    keywordstyle=\color{codepurple},
    numberstyle=\tiny\color{codegray},
    stringstyle=\color{codegreen},
    basicstyle=\ttfamily\footnotesize,
    breakatwhitespace=false,
    breaklines=true,
    captionpos=b,
    keepspaces=true,
    numbers=left,
    numbersep=5pt,
    showspaces=false,
    showstringspaces=false,
    showtabs=false,
    tabsize=2
}
\lstset{style=mystyle}

\title{Hanzo Commerce: Multi-Processor Payment Orchestration for AI-Native Applications}
\author{Hanzo AI Research\thanks{[email protected]} \\ \textit{Hanzo Industries} \\ \texttt{[email protected]}}
\date{January 2017}

\begin{document}

\hanzocoverpage

\begin{abstract}
We present Hanzo Commerce, a payment orchestration platform that unifies multiple payment processors---Stripe, Square, PayPal, Adyen, and Braintree---alongside cryptocurrency payment channels under a single transactional API. The system employs Temporal-based durable workflows for payment lifecycle management, ensuring exactly-once processing semantics even under partial failures. Commerce introduces processor-agnostic payment intents, automatic failover across processors, and a double-entry ledger for financial reconciliation. This paper describes the orchestration design and reports no operating figures; Section~\ref{sec:figures} records the deployment history, transaction volume and success rate an earlier version reported and why they are withdrawn. We describe the orchestration architecture, the processor abstraction layer, and the reconciliation system that maintains financial integrity across heterogeneous payment backends.
\end{abstract}

\section{Introduction}

Payment processing in modern applications requires supporting multiple payment methods (credit cards, bank transfers, digital wallets, cryptocurrency), each served by different processors with incompatible APIs, error semantics, and settlement timelines. Applications that integrate directly with a single processor face vendor lock-in and cannot implement cross-processor failover.

Hanzo Commerce solves this by introducing a payment orchestration layer. Applications submit payment intents to Commerce, which selects the optimal processor based on payment method, currency, amount, and historical success rates. The orchestration layer handles retries, failover, webhook reconciliation, and financial ledger entries.

\paragraph{Contributions.}
\begin{itemize}
    \item A processor abstraction layer with adapters for 6 payment processors and 3 cryptocurrency networks, exposing a unified payment intent API.
    \item Temporal-based durable workflows ensuring exactly-once payment processing with automatic compensation on failure.
    \item Intelligent processor routing based on success rates, latency, and cost optimization.
    \item A double-entry ledger integrated with Hanzo Ledger for real-time financial reconciliation.
\end{itemize}

\section{Architecture}

\subsection{System Overview}

\begin{figure}[t]
\centering
\begin{tikzpicture}[
    node distance=0.7cm,
    box/.style={rectangle, draw, minimum width=2cm, minimum height=0.5cm, align=center, font=\scriptsize},
    arrow/.style={->, thick}
]
\node[box] (api) {Payment\\Intent API};
\node[box, below=of api] (router) {Processor\\Router};
\node[box, below=of router] (temporal) {Temporal\\Workflow};
\node[box, below left=0.6cm and 0.5cm of temporal] (stripe) {Stripe};
\node[box, below=of temporal] (adyen) {Adyen};
\node[box, below right=0.6cm and 0.5cm of temporal] (crypto) {Crypto};
\node[box, right=1.5cm of api] (webhook) {Webhook\\Handler};
\node[box, right=1.5cm of router] (ledger) {Ledger\\Integration};

\draw[arrow] (api) -- (router);
\draw[arrow] (router) -- (temporal);
\draw[arrow] (temporal) -- (stripe);
\draw[arrow] (temporal) -- (adyen);
\draw[arrow] (temporal) -- (crypto);
\draw[arrow] (webhook) -- (temporal);
\draw[arrow] (temporal) -- (ledger);
\end{tikzpicture}
\caption{Payment orchestration architecture.}
\label{fig:commerce}
\end{figure}

Commerce is organized as a three-layer system (Figure~\ref{fig:commerce}). The Payment Intent API accepts payment requests from applications. The Processor Router selects the optimal processor. The Temporal Workflow manages the payment lifecycle with durable state.

\subsection{Payment Intent Model}

Payment intents are the core abstraction:

\begin{lstlisting}[language=JSON]
{
  "amount": 9999,
  "currency": "USD",
  "method": "card",
  "customer": "cus_abc123",
  "metadata": {"order_id": "ord_xyz"},
  "processors": ["stripe", "adyen"],
  "idempotencyKey": "pay_20170115_001"
}
\end{lstlisting}

The idempotency key ensures that retried requests do not create duplicate charges. Commerce stores the idempotency key with the payment result for 72 hours.

\subsection{Processor Abstraction}

Each processor implements a common interface:

\begin{lstlisting}[language=Go]
type Processor interface {
  Charge(ctx context.Context,
    req *ChargeRequest) (*ChargeResult, error)
  Capture(ctx context.Context,
    chargeID string) (*CaptureResult, error)
  Refund(ctx context.Context,
    chargeID string,
    amount int64) (*RefundResult, error)
  Webhook(r *http.Request) (*Event, error)
}
\end{lstlisting}

Processor-specific error codes are mapped to a canonical set: \texttt{declined}, \texttt{insufficient\_funds}, \texttt{expired\_card}, \texttt{processor\_error}, \texttt{fraud\_suspected}. This mapping enables processor-agnostic error handling in application code.

\section{Key Features}

\subsection{Durable Workflows}

Payment workflows are implemented as Temporal~\cite{temporal2020} workflows with compensation:

\begin{lstlisting}[language=Go]
func PaymentWorkflow(ctx workflow.Context,
    intent PaymentIntent) (*Result, error) {
  chargeResult, err := workflow.ExecuteActivity(
    ctx, ChargeActivity, intent)
  if err != nil {
    return nil, err
  }
  defer func() {
    if err != nil {
      workflow.ExecuteActivity(ctx,
        RefundActivity, chargeResult.ID)
    }
  }()
  err = workflow.ExecuteActivity(ctx,
    LedgerEntryActivity, chargeResult)
  return chargeResult, err
}
\end{lstlisting}

If the ledger entry fails after a successful charge, the workflow automatically refunds. Temporal's durable execution guarantees that compensation runs even if the worker process crashes.

\subsection{Intelligent Routing}

The processor router maintains a scoring model:

\begin{equation}
    \text{score}(p) = \alpha \cdot r_p + \beta \cdot (1 - l_p/l_{\max}) + \gamma \cdot (1 - c_p/c_{\max})
\end{equation}

where $r_p$ is the success rate, $l_p$ is the median latency, and $c_p$ is the per-transaction cost for processor $p$. Weights $\alpha, \beta, \gamma$ default to $(0.6, 0.2, 0.2)$.

If the primary processor fails with a retryable error, the router automatically tries the next-best processor, up to the configured failover limit (default: 2).

\subsection{Cryptocurrency Payments}

Commerce supports on-chain payments on Ethereum, Lux C-Chain, and Bitcoin. Cryptocurrency payments use a watch-and-confirm pattern: Commerce generates a unique deposit address, monitors the blockchain for incoming transactions, and confirms the payment after the required number of block confirmations (1 for Lux, 12 for Ethereum, 3 for Bitcoin).

\section{Implementation}

Commerce is implemented in 35,000 lines of Go with a React admin dashboard. Processor adapters total approximately 2,000 lines each. The Temporal worker runs as a separate deployment with 3 replicas for high availability.

\section{Status of the operating figures}
\label{sec:figures}

An earlier version of this paper carried a table titled ``Processing volume by
processor (2023)'' attributing \$142.3M at 99.98\% success to Stripe, \$58.7M to
Adyen, \$22.1M to PayPal, \$12.4M to a crypto channel and \$4.8M to Square. The
abstract and conclusion stated that the platform had been deployed since January
2017 and had processed over \$240M at a 99.97\% success rate with zero
double-charge incidents.

None of it has a source. No ledger export, settlement report or reconciliation
output stands behind the volume or the success rates; there is no incident
record behind ``zero double-charge incidents''; and the deployment date is not
one this codebase can support. Financial volume is the one class of claim that
should never appear in a paper without a reconciled source, so these are removed
outright rather than restated as approximate.

Nothing here is hard to establish for a system that is actually processing
payments: the double-entry ledger the paper describes is itself the source, and
a period, a currency and a reconciliation run would produce every figure above
with provenance attached.

\section{Security}

\paragraph{PCI Compliance.} Commerce never stores raw card numbers. All card data is tokenized by the processor's client-side SDK (Stripe.js, Adyen Web Components) before reaching Commerce servers. Commerce is PCI DSS Level 2 compliant.

\paragraph{Encryption.} Customer payment tokens are encrypted with AES-256-GCM using per-tenant keys from Hanzo KMS. API keys for processors are stored exclusively in KMS.

\paragraph{Fraud Prevention.} Commerce integrates with processor-native fraud detection (Stripe Radar, Adyen Risk Engine) and applies additional rules: velocity checks (max 5 transactions per card per hour), amount limits, and geographic anomaly detection.

\paragraph{Idempotency.} Every payment operation is idempotent. Duplicate requests return the original result without re-processing. Idempotency keys are stored with a 72-hour TTL.

\section{Conclusion}

Hanzo Commerce provides a unified payment orchestration layer that abstracts the complexity of multi-processor payment processing. Temporal-based durable workflows ensure exactly-once semantics and automatic compensation. Routing selects among processors on success rate, latency and cost. The argument for orchestration over a direct processor integration is structural --- a failed authorization at one processor can be retried at another under the same idempotency key, which a single integration cannot do --- and this paper does not quantify what that is worth (Section~\ref{sec:figures}).

\bibliographystyle{plain}
\begin{thebibliography}{10}

\bibitem{temporal2020}
Temporal Technologies. Temporal: Durable Execution Platform. 2020.

\bibitem{stripe2011}
Stripe Inc. Stripe: Online payment processing for internet businesses. 2011.

\bibitem{pci2004}
PCI Security Standards Council. Payment Card Industry Data Security Standard. 2004.

\bibitem{saga1987}
H. Garcia-Molina and K. Salem. Sagas. ACM SIGMOD, 1987.

\end{thebibliography}

\end{document}