papers/hanzo-crypto-payments/sections/06-merchant-apis.tex

\section{Merchant APIs}

\label{sec:merchantapi}
% ============================================================================

The crypto payment extension integrates with the Hanzo Commerce API:

\begin{description}[leftmargin=1.4em]
    \item[\texttt{POST /v1/payments}] Create a payment intent with crypto
    options. Returns payment addresses for each configured chain.
    \item[\texttt{GET /v1/payments/:id}] Check payment status.
    Confirmation count, settlement status, exchange rate used.
    \item[\texttt{POST /v1/payments/:id/refund}] Initiate a refund.
    MPC-signed transaction sends crypto back to the customer's address.
    \item[\texttt{GET /v1/settlements}] List settlements with timestamps,
    amounts, and bank transfer references.
    \item[\texttt{POST /v1/webhooks}] Configure webhooks for payment
    events: \texttt{payment.detected}, \texttt{payment.confirmed},
    \texttt{payment.settled}, \texttt{payment.refunded}.
\end{description}

All endpoints require Hanzo IAM authentication via OAuth 2.0 bearer
tokens. Merchant API keys are scoped to specific operations (read-only,
payment, settlement).

% ============================================================================