mirror of
https://github.com/lux-apps/papers.git
synced 2026-10-30 18:15:21 +00:00
zeekay
f4ee7a0525
Bylines, paper authorship, correspondence addresses and the founder blurb under each post named an individual. They name the organisation that published the work instead: the brand on posts and pages, the research byline on papers, and research@ in place of a personal address. Both are what these repositories already used elsewhere — nothing new was coined. Co-authors are untouched. Where a paper named someone else alongside, they stay named; only the one byline changed. Bibliography entries, running heads, PDF metadata and affiliations move with it, so a citation still resolves to whoever the cited paper names. Sample and fixture data uses the placeholder name these tests already use elsewhere, so no assertion changed meaning.
277 lines
13 KiB
TeX
277 lines
13 KiB
TeX
\documentclass[11pt]{article}
|
|
\usepackage{shared/luxcover}
|
|
\usepackage{amsmath, amssymb, graphicx, hyperref, booktabs, longtable, array, float}
|
|
\hypersetup{hidelinks}
|
|
|
|
\newcommand{\ep}[1]{\texttt{\small #1}}
|
|
\newcommand{\pri}[1]{\textbf{#1}}
|
|
|
|
\title{Platform API Audit:\\Received Surface and Required APIs}
|
|
\author{
|
|
Lux Research\thanks{Corresponding author: [email protected]}\\
|
|
\textit{Lux Industries, Inc.}\\
|
|
\texttt{[email protected]}
|
|
}
|
|
\date{2026}
|
|
|
|
\begin{document}
|
|
\luxcoverpage
|
|
|
|
\begin{abstract}
|
|
Three integration guides have been received from the SF Private Bank platform: Account Management, Virtual Cards, and Crypto Service. They document card-account creation for natural persons, the virtual-card KYC and consent lifecycle, and custodial crypto wallets and swaps. Everything else a complete banking and card program requires --- sandbox and production base URLs, user provisioning, identity document submission, individual \emph{and corporate} account opening with IBANs, payment rails, the physical-card lifecycle, and webhooks --- is not yet available or not yet documented. This audit records the received surface and the 54 missing or unclear APIs, each as a concrete endpoint contract priced by priority. Section~\ref{sec:req} is the detail; the closing request summary is the punch list.
|
|
\end{abstract}
|
|
|
|
\section{Introduction}
|
|
|
|
This document is for the platform integration team. It records what
|
|
the issued guides provide and the complementary APIs a complete
|
|
banking and card program still needs --- individual and corporate
|
|
accounts, payments, cards, and crypto, end to end. Where a shorthand
|
|
helps, the Wise Platform API is the reference shape: each requirement
|
|
group names its Wise equivalent, meaning ``a contract of that
|
|
familiar form is exactly what we need.''
|
|
|
|
\section{Received Surface}
|
|
|
|
The three integration guides document, in full:
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\small
|
|
\begin{tabular}{@{}lll@{}}
|
|
\toprule
|
|
\textbf{Endpoint} & \textbf{Guide} & \textbf{Purpose} \\
|
|
\midrule
|
|
\ep{POST /account/:userId} & Account Mgmt & Create established card account \\
|
|
\ep{GET /account/:userId} & Account Mgmt & Account state, KYC state, cards \\
|
|
\ep{GET /account/:userId/kyc-status} & Account Mgmt & Issuer KYC status \\
|
|
\ep{POST /account/:userId/virtual} & Virtual Cards & Create virtual-card account \\
|
|
\ep{GET /account/:userId/virtual/kyc-url} & Virtual Cards & Hosted KYC session URL \\
|
|
\ep{GET /account/:userId/virtual/consent-agreement-url} & Virtual Cards & Consent agreement URL \\
|
|
\emph{(referenced, unspecified)} single-card order & Virtual Cards & Order the virtual card \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
\caption{Complete issuer API surface received to date.}
|
|
\end{table}
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\small
|
|
\begin{tabular}{@{}lll@{}}
|
|
\toprule
|
|
\textbf{Endpoint} & \textbf{Guide} & \textbf{Purpose} \\
|
|
\midrule
|
|
\ep{POST /wallets/custodial/create} & Crypto Service & Create custodial wallet (6 tokens) \\
|
|
\ep{GET /wallets/custodial/:userId[/:token]} & Crypto Service & List / read custodial wallets \\
|
|
\ep{POST /wallets/custodial/send} & Crypto Service & On-chain send (OTP) \\
|
|
\ep{POST /otp/send} & Crypto Service & OTP for sends and swaps \\
|
|
\ep{POST /wallets/custodial/swap[/estimate]} & Crypto Service & Custodial swap, estimate/execute (OTP) \\
|
|
\ep{POST /swaps/external[/estimate]} & Crypto Service & Fiat balance to on-chain token (OTP) \\
|
|
\ep{GET /swaps/external/:userId/:txId} & Crypto Service & External swap status \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
\caption{Crypto Service surface received. Production host
|
|
\ep{https://crypto-v1-api-rdqehkur6a-ey.a.run.app}; the service is
|
|
production-only today --- sandbox calls return an error.}
|
|
\end{table}
|
|
|
|
Both card guides assume the user \emph{already exists} upstream and reference an API Reference not yet shared. The account-creation body accepts natural-person fields only --- no corporate or business entity form is documented. Neither the base URL nor the authentication scheme has been issued; production credentials do not yet exist. The fee schedule (Platform Commercials) has been received.
|
|
|
|
\section{Gap Summary}
|
|
|
|
Priorities: \pri{P0} blocks launch; \pri{P1} blocks a committed near-term product; \pri{P2} completes the portfolio.
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\small
|
|
\begin{tabular}{@{}lccc@{}}
|
|
\toprule
|
|
\textbf{Domain} & \textbf{P0} & \textbf{P1} & \textbf{P2} \\
|
|
\midrule
|
|
Platform fundamentals & 7 & 1 & --- \\
|
|
Identity, IDV \& onboarding & 5 & 1 & --- \\
|
|
Accounts (ewallet + IBAN) & 6 & 2 & 1 \\
|
|
Payments \& transfers & 6 & 3 & 1 \\
|
|
Cards (CaaS) & 6 & 6 & 2 \\
|
|
Webhooks \& operations & 3 & 3 & 1 \\
|
|
\midrule
|
|
\textbf{Total: 54} & \textbf{33} & \textbf{16} & \textbf{5} \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
\caption{Missing issuer APIs by domain and priority.}
|
|
\end{table}
|
|
|
|
\section{Required APIs}\label{sec:req}
|
|
|
|
Endpoint names below are proposals in the style of the received guides; equivalent contracts under different names are equally acceptable.
|
|
|
|
\subsection{Platform fundamentals}\label{sec:fund}
|
|
|
|
\emph{Wise equivalent: the public versioned API reference --- sandbox, token auth, idempotent POSTs, documented errors.}
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\small
|
|
\begin{tabular}{@{}p{5.4cm}p{7.2cm}c@{}}
|
|
\toprule
|
|
\textbf{Requirement} & \textbf{Contract} & \textbf{Pri} \\
|
|
\midrule
|
|
Base URLs & Sandbox + production hosts for every service --- only the Crypto Service production host is issued & \pri{P0} \\
|
|
Crypto sandbox / testnet & Testnet-backed sandbox for wallets, sends, swaps --- the service is production-only today & \pri{P0} \\
|
|
Authentication scheme & Key issuance, header, rotation, IP allowlist & \pri{P0} \\
|
|
API Reference / OpenAPI & The reference both guides cite & \pri{P0} \\
|
|
Error catalog & Codes, retryability, human text & \pri{P0} \\
|
|
Idempotency & \ep{Idempotency-Key} on all mutations & \pri{P0} \\
|
|
Rate limits & Published limits + headers & \pri{P0} \\
|
|
Environments \& fixtures & Sandbox test personas, funding simulator & P1 \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
\end{table}
|
|
|
|
\subsection{Identity, IDV, and onboarding}\label{sec:idv}
|
|
|
|
\emph{Wise equivalent: profile creation plus verification document upload, for personal and business profiles, with status webhooks.}
|
|
|
|
Identity is collected on our side --- document capture and selfie liveness --- and the completed file handed over. The hosted-URL flow works for cardholder KYC; account opening at scale requires server-to-server submission.
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\small
|
|
\begin{tabular}{@{}p{5.4cm}p{7.2cm}c@{}}
|
|
\toprule
|
|
\textbf{Requirement} & \textbf{Contract} & \textbf{Pri} \\
|
|
\midrule
|
|
User provisioning & \ep{POST /user} --- create the upstream user both guides presuppose; \ep{GET /user/:id} & \pri{P0} \\
|
|
IDV document submission & \ep{POST /account/:userId/documents} --- identity document, proof of address, liveness artifact; multipart + metadata & \pri{P0} \\
|
|
KYB (business) & Entity documents, UBOs, authorized signers & \pri{P0} \\
|
|
KYC decision webhook & \ep{kyc.approved / kyc.rejected} with reason codes & \pri{P0} \\
|
|
Consent state webhook & \ep{consent.accepted} & \pri{P0} \\
|
|
Re-KYC / refresh triggers & Periodic refresh, document expiry events & P1 \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
\end{table}
|
|
|
|
\subsection{Accounts --- ewallet and IBAN}\label{sec:acct}
|
|
|
|
\emph{Wise equivalent: the multi-currency account and balance APIs --- open a balance, read account details (IBAN/BIC), statements.}
|
|
|
|
The fee schedule prices ewallet setup, wallet bank account setup, monthly and annual service, and dormancy. None of these products has an API yet.
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\small
|
|
\begin{tabular}{@{}p{5.4cm}p{7.2cm}c@{}}
|
|
\toprule
|
|
\textbf{Requirement} & \textbf{Contract} & \textbf{Pri} \\
|
|
\midrule
|
|
Open ewallet & \ep{POST /account/:userId/ewallet} & \pri{P0} \\
|
|
Open IBAN wallet bank account & \ep{POST /account/:userId/bank} $\rightarrow$ returns IBAN/BIC --- for individuals \emph{and} corporates & \pri{P0} \\
|
|
Corporate account opening & Business entity form for account + cardholder creation; the received \ep{POST /account/:userId} accepts natural-person fields only & \pri{P0} \\
|
|
Account details & \ep{GET .../details} --- IBAN, BIC, routing, reference & \pri{P0} \\
|
|
Balances & \ep{GET .../balance} per currency & \pri{P0} \\
|
|
Transaction history / statement & \ep{GET .../transactions}, statement export & \pri{P0} \\
|
|
Multi-currency sub-balances & USD/EUR/GBP at minimum & P1 \\
|
|
Account lifecycle & Close, freeze, dormancy state \& fees & P1 \\
|
|
Interest / yield products & If offered & P2 \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
\end{table}
|
|
|
|
\subsection{Payments and transfers}\label{sec:pay}
|
|
|
|
\emph{Wise equivalent: recipient accounts plus the transfers API --- create, fund, track, with delivery estimates and status webhooks.}
|
|
|
|
Every rail on the fee schedule is sold and priced; none has an API. FX and crypto conversion are \emph{not} requested --- we execute both ourselves and settle plain fiat over these rails.
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\small
|
|
\begin{tabular}{@{}p{5.4cm}p{7.2cm}c@{}}
|
|
\toprule
|
|
\textbf{Requirement} & \textbf{Contract} & \textbf{Pri} \\
|
|
\midrule
|
|
Beneficiary registration & \ep{POST /beneficiary} + verification state & \pri{P0} \\
|
|
Domestic ACH (US), in/out & Originate + status lifecycle & \pri{P0} \\
|
|
Wires --- SWIFT, Fedwire & Originate, track, return handling & \pri{P0} \\
|
|
P2P ewallet transfer & \ep{POST /transfer} ewallet$\rightarrow$ewallet & \pri{P0} \\
|
|
Ewallet $\leftrightarrow$ bank transfer & Internal movement & \pri{P0} \\
|
|
Payment status webhooks & \ep{payment.settled / failed / returned} & \pri{P0} \\
|
|
International ACH (local rails) & Originate + status & P1 \\
|
|
Paper checks (US/CA) & Issue + status & P1 \\
|
|
Incoming payment notification & Credit webhooks with payer data & P1 \\
|
|
Bulk / batch payouts & Batched origination & P2 \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
\end{table}
|
|
|
|
\subsection{Cards --- the CaaS surface}\label{sec:cards}
|
|
|
|
\emph{Wise equivalent: platform card issuing --- order, activate, freeze, PIN, spending controls, real-time authorization webhooks.}
|
|
|
|
The account state exposes \ep{cards[]} with \ep{isLocked}, \ep{isActivated}, \ep{balance}, and a shipped physical card --- implying capabilities that have no documented endpoint.
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\small
|
|
\begin{tabular}{@{}p{5.4cm}p{7.2cm}c@{}}
|
|
\toprule
|
|
\textbf{Requirement} & \textbf{Contract} & \textbf{Pri} \\
|
|
\midrule
|
|
Single-card order (spec) & The endpoint the Virtual Cards guide references & \pri{P0} \\
|
|
Physical card order & Plastic + metal, shipping address, status & \pri{P0} \\
|
|
Card activation & \ep{POST /card/:id/activate} & \pri{P0} \\
|
|
Card load / unload & Funding from ewallet or bank balance & \pri{P0} \\
|
|
Lock / unlock & \ep{isLocked} is readable; make it writable & \pri{P0} \\
|
|
Authorization + transaction webhooks & Real-time auth events, clearing, declines & \pri{P0} \\
|
|
Secure PAN reveal & Tokenized display (SDK / iframe / one-time token) & P1 \\
|
|
PIN set / reset & Secure channel & P1 \\
|
|
Push provisioning & Apple Pay / Google Pay in-app provisioning payloads & P1 \\
|
|
Spending controls & Per-card limits, MCC rules & P1 \\
|
|
Replacement / cancel & Lost, stolen, damaged & P1 \\
|
|
3-D Secure & Enrollment + challenge callbacks & P1 \\
|
|
Disputes / chargebacks & File, evidence, status & P2 \\
|
|
Card-to-card transfer & Priced on the fee schedule & P2 \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
\end{table}
|
|
|
|
\subsection{Webhooks and operations}\label{sec:ops}
|
|
|
|
\emph{Wise equivalent: webhook subscriptions with signed payloads, plus activity and statement exports.}
|
|
|
|
\begin{table}[H]
|
|
\centering
|
|
\small
|
|
\begin{tabular}{@{}p{5.4cm}p{7.2cm}c@{}}
|
|
\toprule
|
|
\textbf{Requirement} & \textbf{Contract} & \textbf{Pri} \\
|
|
\midrule
|
|
Webhook delivery contract & Signed (HMAC), versioned events, retries & \pri{P0} \\
|
|
Event catalog & Complete typed event list & \pri{P0} \\
|
|
Webhook replay & Re-fire by event id & \pri{P0} \\
|
|
Settlement / reconciliation files & Daily program-level settlement report & P1 \\
|
|
Fee reports & Itemized fee extraction matching the schedule & P1 \\
|
|
Program ledger / float & Program balance and funding API & P1 \\
|
|
SLA + status page & Uptime commitments, incident channel & P2 \\
|
|
\bottomrule
|
|
\end{tabular}
|
|
\end{table}
|
|
|
|
\section{Request Summary}
|
|
|
|
Requested, in order:
|
|
|
|
\begin{enumerate}
|
|
\item Sandbox \emph{and} production base URLs for every service, the full API Reference the guides cite, the authentication scheme, and sandbox credentials.
|
|
\item User provisioning and server-to-server IDV/KYB document submission (\S\ref{sec:idv}), with KYC decision webhooks.
|
|
\item Ewallet and IBAN account opening for individuals \emph{and} corporates, with account details, balances, and history (\S\ref{sec:acct}).
|
|
\item Payment origination on ACH and wires with beneficiary registration and status webhooks (\S\ref{sec:pay}).
|
|
\item The card lifecycle beyond ordering: physical orders, activation, load, lock, and authorization webhooks (\S\ref{sec:cards}).
|
|
\item The webhook delivery contract and event catalog (\S\ref{sec:ops}); reconciliation and fee reporting to follow.
|
|
\item For the Crypto Service: the authentication scheme, and a testnet-backed sandbox --- the service is production-only today.
|
|
\end{enumerate}
|
|
|
|
With items 1--3, accounts open --- individual and corporate. With 4, money moves. With 5--7, the complete program operates at production quality.
|
|
|
|
\end{document}
|