Tesser endpoints exposed to Nexa
Endpoints Tesser hosts and Banco Nexa calls, for the Tesser x Banco Nexa USDC-to-GTQ offramp POC.
Two groups:
- The webhook receiver
POST/HEAD /v1/webhooks/nexa/{organizationId}, bespoke for this integration, and the channel for every Nexa decision: credit sent/confirmed, additional funds requested, rejection, and payout failures. - Two existing Tesser core-API operations Nexa already needs for treasury: read the USDC balance and withdraw USDC. These are vendored verbatim from the live Tesser core API definition so this reference is complete in one place; https://docs.tesser.xyz stays normative, and
bun scripts/vendor-core.ts --checkkeeps the copies honest in CI.
Auth (both groups): Nexa presents its client certificate (mTLS). The certificate's SHA-256 fingerprint is registered against Nexa's Tesser API key during onboarding, and Tesser resolves Nexa's identity from it. This is the platform's existing banking-partner mTLS design, nothing new to build. The webhook receiver additionally requires the resolved identity to match the {organizationId} in the path; a mismatch is a 401. Nexa's webhook deliveries are expected to present the same client certificate.
Webhook delivery is at-least-once and unordered: Tesser dedupes on event_id, and applies the quote state machine's reachability rule to the quote_status an event carries: forward-reachable states are applied, the current state or an ancestor changes nothing, and a conflicting branch or terminal is acked and raises an ops alert rather than being silently dropped. Any 2xx is success; anything else is retried.
Money amounts are JSON strings, decimal, no exponent notation (^[0-9]+(\.[0-9]+)?$): GTQ at most 2 decimal places, USDC at most 6. Never JSON numbers. Timestamps are RFC 3339 UTC.
The stub server returns this document's own canonical examples.
/v1/webhooks/circle/{organizationId}, /v1/webhooks/openfx/{workspaceId}, and so on, all POST plus HEAD.assets[] entries on the account, and the wallet's account ID is shared during onboarding (single-wallet MVP). The example below is the core API's own, a fiat bank account; a wallet account additionally carries crypto_wallet_address and the assets[] array with the USDC available_balance.