{ "openapi": "3.1.0", "info": { "title": "Nexa endpoints exposed to Tesser", "version": "v1", "description": "Endpoints **Banco Nexa hosts** and **Tesser calls**, for the Tesser x Banco Nexa USDC-to-GTQ offramp POC.\n\n**Scope of this integration.** Nexa always pays **one fixed beneficiary**, agreed out-of-band and never present in an API payload: the payout partner that performs the last-mile payout to the individual remittance receivers. Nexa is not involved in the last mile in this phase, so there are no per-recipient beneficiary details anywhere in this contract. Nexa taking on last-mile remittance payouts is a later stage of the programme and out of scope here. The GTQ payout itself is **synchronous**: `POST /v1/payments` performs it and returns the outcome.\n\nAuth on every call: Tesser presents its client certificate (mTLS) **and** `Authorization: Bearer `. The certificate identifies Tesser as the orchestrator, the key identifies the customer context, and the `customer` field cross-checks it.\n\nMoney amounts are JSON strings, decimal, no exponent notation (`^[0-9]+(\\.[0-9]+)?$`): GTQ at most 2 decimal places, USDC at most 6, `usdc_gtq_price` at most 6. Never JSON numbers. Nexa computes and returns every derived amount; Tesser never derives an amount from the price locally. Timestamps are RFC 3339 UTC. Every POST is idempotent on its natural key: a retry returns the resource's current state, a conflicting body returns 409.\n\nThe stub server returns these documents' own canonical examples. An id ending `dead` (for example `9b2f6c1e-0000-4000-8000-00000000dead`) makes a stub return that operation's primary error instead." }, "servers": [ { "url": "https://nexa-poc-main-c82e5ac.zuplo.app/nexa", "description": "Tesser-hosted stub of this API (POC)." } ], "tags": [ { "name": "Quotes", "description": "Lock a GTQ-per-USDC price, accept it, and read the merged quote state." }, { "name": "Deposits", "description": "Report USDC Tesser observed arriving in Nexa's custody wallet. Reports, not requests." }, { "name": "Payments", "description": "Pay credited GTQ out to the fixed beneficiary." }, { "name": "Webhooks", "description": "Nexa's receiver for Tesser's outbound webhooks." } ], "paths": { "/v1/quotes": { "post": { "operationId": "createQuote", "tags": [ "Quotes" ], "summary": "Create quote (op 1)", "description": "Ask Nexa to quote GTQ against USDC (§6.1). Nexa computes every derived amount, notably `usdc_amount`, rounded UP at 6dp so delivering exactly it always covers `quoted_gtq`. Idempotent on `tesser_quote_id`: a retry returns the quote's current state, a conflicting body returns 409.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateQuoteRequest" }, "examples": { "default": { "summary": "Quote 250,000.00 GTQ for Felix", "value": { "tesser_quote_id": "9b2f6c1e-0000-4000-8000-000000000001", "customer": "FELIX", "desired_gtq": "250000.00" } } } } } }, "responses": { "201": { "description": "Quote created, or, on an idempotent retry, the current state of the existing quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" }, "examples": { "default": { "summary": "Full fill at 7.745100 GTQ/USDC", "value": { "tesser_quote_id": "9b2f6c1e-0000-4000-8000-000000000001", "nexa_quote_id": "NXQ-2026-000481", "quote_status": "CREATED", "usdc_gtq_price": "7.745100", "quoted_gtq": "250000.00", "usdc_amount": "32278.472841", "expires_at": "2026-10-14T15:05:00Z", "created_at": "2026-10-14T15:00:00Z" } } } } } }, "400": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "VALIDATION_ERROR", "value": { "errors": [ { "error_code": "VALIDATION_ERROR", "error_message": "desired_gtq must be a decimal string with at most 2 decimal places." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "401": { "description": "Unauthenticated. See the Authentication page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "UNAUTHENTICATED", "value": { "errors": [ { "error_code": "UNAUTHENTICATED", "error_message": "Client certificate not recognised, or the Authorization bearer token is missing or invalid." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "QUOTE_CONFLICT", "value": { "errors": [ { "error_code": "QUOTE_CONFLICT", "error_message": "A quote already exists with this tesser_quote_id and a different request body." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "422": { "description": "Nexa cannot quote right now.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "NO_LIQUIDITY", "value": { "errors": [ { "error_code": "NO_LIQUIDITY", "error_message": "Nexa cannot quote any GTQ amount at this time." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "500": { "description": "Unexpected error on Nexa's side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "INTERNAL_ERROR", "value": { "errors": [ { "error_code": "INTERNAL_ERROR", "error_message": "Unexpected error. Retry with the same idempotency key; quote the request_id to Nexa support if it persists." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } } } } }, "/v1/quotes/{tesser_quote_id}/accept": { "post": { "operationId": "acceptQuote", "tags": [ "Quotes" ], "summary": "Accept quote (op 2)", "description": "Accept the quote identified by the path (§6.2). The body is an empty object: acceptance is of `quoted_gtq` by definition. Idempotent: re-accepting an already-accepted (or later-state) quote returns 200 with the current object.", "parameters": [ { "name": "tesser_quote_id", "in": "path", "required": true, "description": "The UUIDv4 Tesser minted for this quote.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "description": "Empty object; the path identifies the quote.", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "default": { "summary": "Empty body", "value": {} } } } } }, "responses": { "200": { "description": "Quote accepted (or already accepted).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptQuoteResponse" }, "examples": { "default": { "summary": "Accepted, deposit due by 17:00Z", "value": { "tesser_quote_id": "9b2f6c1e-0000-4000-8000-000000000001", "quote_status": "ACCEPTED", "deposit_deadline": "2026-10-14T17:00:00Z", "accepted_at": "2026-10-14T15:01:12Z" } } } } } }, "400": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "VALIDATION_ERROR", "value": { "errors": [ { "error_code": "VALIDATION_ERROR", "error_message": "tesser_quote_id must be a UUID." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "401": { "description": "Unauthenticated. See the Authentication page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "UNAUTHENTICATED", "value": { "errors": [ { "error_code": "UNAUTHENTICATED", "error_message": "Client certificate not recognised, or the Authorization bearer token is missing or invalid." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "404": { "description": "No such quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "QUOTE_NOT_FOUND", "value": { "errors": [ { "error_code": "QUOTE_NOT_FOUND", "error_message": "No quote exists for the supplied tesser_quote_id." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "409": { "description": "The quote can no longer be accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "QUOTE_EXPIRED", "value": { "errors": [ { "error_code": "QUOTE_EXPIRED", "error_message": "The quote expired at expires_at before it was accepted." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "500": { "description": "Unexpected error on Nexa's side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "INTERNAL_ERROR", "value": { "errors": [ { "error_code": "INTERNAL_ERROR", "error_message": "Unexpected error. Retry with the same idempotency key; quote the request_id to Nexa support if it persists." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } } } } }, "/v1/quotes/{tesser_quote_id}/deposits": { "post": { "operationId": "reportDeposit", "tags": [ "Deposits" ], "summary": "Report USDC deposit (op 3)", "description": "Report a USDC delivery Tesser observed in Nexa's custody wallet (§6.3). This is a report, not a request: a 2xx means 'report recorded', nothing more. There are no synchronous risk or amount errors, and Nexa's credit / additional-funds / reject decision arrives asynchronously by webhook. Repeatable: each report is a new sub-resource, so the additional-funds flow and late reports both work. Idempotent per `tesser_deposit_id`.", "parameters": [ { "name": "tesser_quote_id", "in": "path", "required": true, "description": "The UUIDv4 Tesser minted for this quote.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDepositRequest" }, "examples": { "default": { "summary": "Deposit covering the quote, risk-approved", "value": { "tesser_deposit_id": "4e1a77c0-0000-4000-8000-000000000001", "usdc_amount": "32278.480000", "risk_status": "automatically_approved", "risk_status_reasons": [], "transaction_hashes": [ "0x8c4a1f2e3d4c5b6a7980f1e2d3c4b5a69780f1e2d3c4b5a68c4a1f2e3d4c5b6a" ] } } } } } }, "responses": { "200": { "description": "Report recorded. Also the response for a late report (quote already credited or paying out), recorded with no state change and flagged for ops review on both sides.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportDepositResponse" }, "examples": { "default": { "summary": "First report on the quote", "value": { "tesser_quote_id": "9b2f6c1e-0000-4000-8000-000000000001", "tesser_deposit_id": "4e1a77c0-0000-4000-8000-000000000001", "quote_status": "DEPOSIT_REPORTED", "usdc_total_reported": "32278.480000", "reported_at": "2026-10-14T15:24:40Z" } } } } } }, "400": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "VALIDATION_ERROR", "value": { "errors": [ { "error_code": "VALIDATION_ERROR", "error_message": "usdc_amount must be a decimal string with at most 6 decimal places." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "401": { "description": "Unauthenticated. See the Authentication page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "UNAUTHENTICATED", "value": { "errors": [ { "error_code": "UNAUTHENTICATED", "error_message": "Client certificate not recognised, or the Authorization bearer token is missing or invalid." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "404": { "description": "No such quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "QUOTE_NOT_FOUND", "value": { "errors": [ { "error_code": "QUOTE_NOT_FOUND", "error_message": "No quote exists for the supplied tesser_quote_id." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "409": { "description": "The quote is in a state that cannot take deposit reports, or this report conflicts with an existing one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "QUOTE_REJECTED: quote is in REJECTED", "value": { "errors": [ { "error_code": "QUOTE_REJECTED", "error_message": "Nexa rejected this quote; a new quote is the recovery path." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } }, "quote_not_accepted": { "summary": "QUOTE_NOT_ACCEPTED: quote is still CREATED", "value": { "errors": [ { "error_code": "QUOTE_NOT_ACCEPTED", "error_message": "The quote is still CREATED; accept it before reporting a deposit." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } }, "quote_expired": { "summary": "QUOTE_EXPIRED: quote is in EXPIRED", "value": { "errors": [ { "error_code": "QUOTE_EXPIRED", "error_message": "The quote expired at deposit_deadline before any deposit was reported." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } }, "deposit_conflict": { "summary": "DEPOSIT_CONFLICT: same deposit id, different body", "value": { "errors": [ { "error_code": "DEPOSIT_CONFLICT", "error_message": "A report already exists with this tesser_deposit_id and a different request body." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "500": { "description": "Unexpected error on Nexa's side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "INTERNAL_ERROR", "value": { "errors": [ { "error_code": "INTERNAL_ERROR", "error_message": "Unexpected error. Retry with the same idempotency key; quote the request_id to Nexa support if it persists." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } } } } }, "/v1/payments": { "post": { "operationId": "createPayment", "tags": [ "Payments" ], "summary": "Create payment (op 5)", "description": "Instruct Nexa to send credited GTQ from the customer Nexa account to the fixed beneficiary configured out-of-band (the payout partner that performs the last-mile payout; Nexa is not involved in the last mile in this phase). **The payout is synchronous:** this call performs it and returns the outcome, so there is no pending state to poll and no success webhook. One payment per quote in the MVP. A decline or execution failure discovered during the call comes back on the same `201` as `payment_status: \"FAILED\"`; the single `payment.status.changed` event is reserved for a failure or return that surfaces on the rail after a `COMPLETED` response. **Timeout or retry during execution (§6.4):** a retry carrying the same `tesser_quote_id` **joins the in-flight execution** and returns its final outcome. It never starts a second payout and never errors because one is already running. There is no *payment* read during execution, since op 9 is keyed on `nexa_payment_id`, which only arrives in the response. The op 8 quote read is reachable mid-execution but not informative: no in-progress state is representable, so it still shows `CREDIT_CONFIRMED`. If a retry times out again, recovery is another retry or the optional quote read once an outcome exists. Whether Nexa can implement the join is §11 Q5.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentRequest" }, "examples": { "default": { "summary": "Pay out the credited 250,000.00 GTQ", "value": { "tesser_quote_id": "9b2f6c1e-0000-4000-8000-000000000001", "gtq_amount": "250000.00" } } } } } }, "responses": { "201": { "description": "Payout executed. Normally `payment_status: \"COMPLETED\"` with `quote_status: \"PAYMENT_COMPLETED\"`; if Nexa declines or cannot execute the payout during the call it answers `FAILED`/`PAYMENT_FAILED` on this same 201 rather than by webhook. On an idempotent retry, the current state of the existing payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "examples": { "default": { "summary": "Payout executed, COMPLETED in the response", "value": { "nexa_payment_id": "NXP-2026-000112", "tesser_quote_id": "9b2f6c1e-0000-4000-8000-000000000001", "quote_status": "PAYMENT_COMPLETED", "payment_status": "COMPLETED", "gtq_amount": "250000.00", "created_at": "2026-10-14T16:02:00Z", "completed_at": "2026-10-14T16:02:00Z" } }, "declined": { "summary": "Payout declined during execution, FAILED in the same response", "value": { "nexa_payment_id": "NXP-2026-000113", "tesser_quote_id": "9b2f6c1e-0000-4000-8000-000000000002", "quote_status": "PAYMENT_FAILED", "payment_status": "FAILED", "gtq_amount": "250000.00", "created_at": "2026-10-14T16:02:00Z", "status_metadata": { "failure_reason": "Beneficiary account rejected the credit." } } } } } } }, "400": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "VALIDATION_ERROR", "value": { "errors": [ { "error_code": "VALIDATION_ERROR", "error_message": "gtq_amount must be a decimal string with at most 2 decimal places." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "401": { "description": "Unauthenticated. See the Authentication page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "UNAUTHENTICATED", "value": { "errors": [ { "error_code": "UNAUTHENTICATED", "error_message": "Client certificate not recognised, or the Authorization bearer token is missing or invalid." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "404": { "description": "No such quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "QUOTE_NOT_FOUND", "value": { "errors": [ { "error_code": "QUOTE_NOT_FOUND", "error_message": "No quote exists for the supplied tesser_quote_id." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "409": { "description": "The quote cannot be paid out yet, or it already has a different payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "QUOTE_NOT_CREDITED: credit not yet confirmed", "value": { "errors": [ { "error_code": "QUOTE_NOT_CREDITED", "error_message": "The quote has not reached CREDIT_CONFIRMED, so there is no credited GTQ to pay out." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } }, "payment_conflict": { "summary": "PAYMENT_CONFLICT: one payment per quote (MVP)", "value": { "errors": [ { "error_code": "PAYMENT_CONFLICT", "error_message": "This quote already has a payment with a different gtq_amount." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } }, "quote_rejected": { "summary": "QUOTE_REJECTED: quote is in REJECTED", "value": { "errors": [ { "error_code": "QUOTE_REJECTED", "error_message": "Nexa rejected this quote; no payment can be made against it." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "422": { "description": "The instructed amount does not match the credit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "AMOUNT_MISMATCH", "value": { "errors": [ { "error_code": "AMOUNT_MISMATCH", "error_message": "gtq_amount does not equal the amount Nexa credited for this quote (see the quote.credit.confirmed event)." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "500": { "description": "Unexpected error on Nexa's side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "INTERNAL_ERROR", "value": { "errors": [ { "error_code": "INTERNAL_ERROR", "error_message": "Unexpected error. Retry with the same idempotency key; quote the request_id to Nexa support if it persists." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } } } } }, "/v1/quotes/{tesser_quote_id}": { "get": { "operationId": "getQuote", "tags": [ "Quotes" ], "summary": "Get quote (optional op 8)", "description": "Read the merged quote state (§6.5). *Optional op 8*: Nexa may defer it without breaking the core flow, with the honest caveat that deferral degrades the missed-webhook recovery path from a one-curl check to ops channels. Webhooks are the push channel, but the first cross-company debugging question is always 'what state do you think it's in?'. After rejection this returns `quote_status: \"REJECTED\"`.", "parameters": [ { "name": "tesser_quote_id", "in": "path", "required": true, "description": "The UUIDv4 Tesser minted for this quote.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The merged quote object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteDetail" }, "examples": { "default": { "summary": "Credited quote with one deposit and a completed payment", "value": { "tesser_quote_id": "9b2f6c1e-0000-4000-8000-000000000001", "nexa_quote_id": "NXQ-2026-000481", "quote_status": "PAYMENT_COMPLETED", "usdc_gtq_price": "7.745100", "quoted_gtq": "250000.00", "usdc_amount": "32278.472841", "expires_at": "2026-10-14T15:05:00Z", "created_at": "2026-10-14T15:00:00Z", "deposit_deadline": "2026-10-14T17:00:00Z", "accepted_at": "2026-10-14T15:01:12Z", "usdc_total_reported": "32278.480000", "credited_gtq": "250000.00", "credited_at": "2026-10-14T15:30:02Z", "deposits": [ { "tesser_deposit_id": "4e1a77c0-0000-4000-8000-000000000001", "usdc_amount": "32278.480000", "risk_status": "automatically_approved", "risk_status_reasons": [], "transaction_hashes": [ "0x8c4a1f2e3d4c5b6a7980f1e2d3c4b5a69780f1e2d3c4b5a68c4a1f2e3d4c5b6a" ], "reported_at": "2026-10-14T15:24:40Z" } ], "payment": { "nexa_payment_id": "NXP-2026-000112", "payment_status": "COMPLETED", "gtq_amount": "250000.00", "created_at": "2026-10-14T16:02:00Z" } } } } } } }, "400": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "VALIDATION_ERROR", "value": { "errors": [ { "error_code": "VALIDATION_ERROR", "error_message": "tesser_quote_id must be a UUID." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "401": { "description": "Unauthenticated. See the Authentication page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "UNAUTHENTICATED", "value": { "errors": [ { "error_code": "UNAUTHENTICATED", "error_message": "Client certificate not recognised, or the Authorization bearer token is missing or invalid." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "404": { "description": "No such quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "QUOTE_NOT_FOUND", "value": { "errors": [ { "error_code": "QUOTE_NOT_FOUND", "error_message": "No quote exists for the supplied tesser_quote_id." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "500": { "description": "Unexpected error on Nexa's side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "INTERNAL_ERROR", "value": { "errors": [ { "error_code": "INTERNAL_ERROR", "error_message": "Unexpected error. Retry with the same idempotency key; quote the request_id to Nexa support if it persists." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } } } } }, "/v1/payments/{nexa_payment_id}": { "get": { "operationId": "getPayment", "tags": [ "Payments" ], "summary": "Get payment (optional op 9)", "description": "Read the current payout state (§6.6). *Optional op 9*, same rationale and same deferral caveat as op 8.", "parameters": [ { "name": "nexa_payment_id", "in": "path", "required": true, "description": "Nexa's payment reference, as returned by createPayment.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The payment object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentDetail" }, "examples": { "default": { "summary": "Completed payout, read back for reconciliation", "value": { "nexa_payment_id": "NXP-2026-000112", "tesser_quote_id": "9b2f6c1e-0000-4000-8000-000000000001", "quote_status": "PAYMENT_COMPLETED", "payment_status": "COMPLETED", "gtq_amount": "250000.00", "status_metadata": { "rail_reference": "NXR-2026-884412" }, "created_at": "2026-10-14T16:02:00Z", "updated_at": "2026-10-14T16:05:31Z", "completed_at": "2026-10-14T16:02:00Z" } } } } } }, "400": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "VALIDATION_ERROR", "value": { "errors": [ { "error_code": "VALIDATION_ERROR", "error_message": "nexa_payment_id is missing or malformed." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "401": { "description": "Unauthenticated. See the Authentication page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "UNAUTHENTICATED", "value": { "errors": [ { "error_code": "UNAUTHENTICATED", "error_message": "Client certificate not recognised, or the Authorization bearer token is missing or invalid." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "404": { "description": "No such payment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "PAYMENT_NOT_FOUND", "value": { "errors": [ { "error_code": "PAYMENT_NOT_FOUND", "error_message": "No payment exists for the supplied nexa_payment_id." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "500": { "description": "Unexpected error on Nexa's side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "INTERNAL_ERROR", "value": { "errors": [ { "error_code": "INTERNAL_ERROR", "error_message": "Unexpected error. Retry with the same idempotency key; quote the request_id to Nexa support if it persists." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } } } } }, "/v1/webhooks/tesser": { "post": { "operationId": "receiveTesserWebhook", "tags": [ "Webhooks" ], "summary": "Receive Tesser webhook (Nexa implements this)", "description": "Nexa-hosted receiver for Tesser's standard outbound webhooks (§6.7). The subscription Nexa needs is the withdrawal events behind the treasury withdrawals of §9.2. Envelope and event types are Tesser's existing ones; https://docs.tesser.xyz is the normative definition and this document does not re-specify them; the schema below is orientation only. Delivery auth: see the Authentication & environments page (mTLS, plus Tesser's Ed25519 `X-Tesser-Signature` header).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TesserWebhookEnvelope" }, "examples": { "default": { "summary": "withdrawal.updated", "value": { "id": "a7d2e5b1-0000-4000-8000-000000000001", "type": "withdrawal.updated", "created_at": "2026-10-14T17:45:09.045Z", "data": { "object": { "id": "7c1d0b44-0000-4000-8000-000000000001", "organization_reference_id": "nexa-withdrawal-0001" } } } } } } } }, "responses": { "200": { "description": "Delivery accepted. Tesser treats any 2xx as success; a production receiver may return a truly empty body, and the empty object below is the explicit contract this document specifies so every operation has a schema and an example.", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "default": { "summary": "Empty acknowledgement", "value": {} } } } } }, "400": { "description": "Request failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "VALIDATION_ERROR", "value": { "errors": [ { "error_code": "VALIDATION_ERROR", "error_message": "Webhook envelope is missing required fields." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "401": { "description": "Unauthenticated. See the Authentication page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "UNAUTHENTICATED", "value": { "errors": [ { "error_code": "UNAUTHENTICATED", "error_message": "Client certificate not recognised, or the Authorization bearer token is missing or invalid." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } }, "500": { "description": "Unexpected error on Nexa's side.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "examples": { "default": { "summary": "INTERNAL_ERROR", "value": { "errors": [ { "error_code": "INTERNAL_ERROR", "error_message": "Unexpected error. Retry with the same idempotency key; quote the request_id to Nexa support if it persists." } ], "request_id": "req_01JA7Q2W3E4R5T6Y7U8I9O0P" } } } } } } } } } }, "components": { "schemas": { "Money": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)?$" }, "QuoteStatus": { "type": "string", "enum": [ "CREATED", "ACCEPTED", "DEPOSIT_REPORTED", "CREDIT_SENT", "CREDIT_CONFIRMED", "PAYMENT_COMPLETED", "PAYMENT_FAILED", "PAYMENT_RETURNED", "EXPIRED", "REJECTED" ] }, "PaymentStatus": { "type": "string", "enum": [ "COMPLETED", "FAILED", "RETURNED" ], "description": "Outcome of the payout. The call performs the payout and answers with the outcome, so `COMPLETED` or `FAILED` can both come back synchronously. `RETURNED`, and a `FAILED` that only surfaces on the rail after a `COMPLETED` response, arrive later via the failure webhook." }, "RiskStatus": { "type": "string", "enum": [ "unchecked", "awaiting_decision", "automatically_approved", "manually_approved", "automatically_rejected", "manually_rejected" ] }, "RiskStatusReason": { "type": "object", "properties": { "risk_status_reason_type": { "type": "string", "enum": [ "ENTITY", "ACCOUNT", "OWNERSHIP", "COUNTERPARTY", "INDIRECT", "BEHAVIORAL", "ERROR" ] }, "risk_status_reason_category": { "type": "string" }, "risk_status_reason_message": { "type": "string" } }, "required": [ "risk_status_reason_type" ] }, "ErrorEnvelope": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "error_code": { "type": "string" }, "error_message": { "type": "string" } }, "required": [ "error_code", "error_message" ] } }, "request_id": { "type": "string" } }, "required": [ "errors", "request_id" ] }, "WebhookEnvelope": { "type": "object", "properties": { "event_id": { "type": "string", "format": "uuid" }, "event_type": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "data": { "type": "object" } }, "required": [ "event_id", "event_type", "occurred_at", "data" ] }, "CreateQuoteRequest": { "type": "object", "description": "Quote request (§6.1).", "properties": { "tesser_quote_id": { "type": "string", "format": "uuid", "description": "UUIDv4 minted by Tesser before the call; doubles as the idempotency key." }, "customer": { "type": "string", "enum": [ "FELIX" ], "description": "Closed enum at launch. Cross-checks the customer context carried by the API key." }, "desired_gtq": { "$ref": "#/components/schemas/Money", "description": "GTQ the customer wants to end up with. Max 2 decimal places." } }, "required": [ "tesser_quote_id", "customer", "desired_gtq" ] }, "Quote": { "type": "object", "description": "A quote as returned by create (§6.1).", "properties": { "tesser_quote_id": { "type": "string", "format": "uuid" }, "nexa_quote_id": { "type": "string", "description": "Nexa's own reference, for support and reconciliation." }, "quote_status": { "$ref": "#/components/schemas/QuoteStatus" }, "usdc_gtq_price": { "$ref": "#/components/schemas/Money", "description": "GTQ per 1 USDC. Max 6 decimal places." }, "quoted_gtq": { "$ref": "#/components/schemas/Money", "description": "GTQ Nexa will deliver. May be less than desired_gtq, which is a partial fill, and the remainder is a new quote." }, "usdc_amount": { "$ref": "#/components/schemas/Money", "description": "USDC Tesser must deliver = quoted_gtq / usdc_gtq_price, rounded UP at 6dp. Nexa is the single calculator; Tesser echoes this value and never re-derives it." }, "expires_at": { "type": "string", "format": "date-time", "description": "Acceptance deadline. Unaccepted quotes expire silently; there is no expiry webhook." }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "tesser_quote_id", "nexa_quote_id", "quote_status", "usdc_gtq_price", "quoted_gtq", "usdc_amount", "expires_at", "created_at" ] }, "AcceptQuoteResponse": { "type": "object", "description": "Acceptance acknowledgement (§6.2).", "properties": { "tesser_quote_id": { "type": "string", "format": "uuid" }, "quote_status": { "$ref": "#/components/schemas/QuoteStatus" }, "deposit_deadline": { "type": "string", "format": "date-time", "description": "How long Nexa holds the locked rate waiting for the first deposit report. Past it with no deposit reported, the quote is EXPIRED (window length: §11 Q2)." }, "accepted_at": { "type": "string", "format": "date-time" } }, "required": [ "tesser_quote_id", "quote_status", "deposit_deadline", "accepted_at" ] }, "ReportDepositRequest": { "type": "object", "description": "A report, not a request (§6.3): Tesser attests what it observed on-chain. Tesser always reports a deposit it observes, including when risk screening rejects. Nexa alone decides what to do with the report, asynchronously, by webhook.", "properties": { "tesser_deposit_id": { "type": "string", "format": "uuid", "description": "UUIDv4 minted by Tesser; the idempotency key for this individual report." }, "usdc_amount": { "$ref": "#/components/schemas/Money", "description": "USDC that actually arrived in this report. Max 6 decimal places." }, "risk_status": { "$ref": "#/components/schemas/RiskStatus" }, "risk_status_reasons": { "type": "array", "items": { "$ref": "#/components/schemas/RiskStatusReason" }, "description": "Tesser core-API RiskStatusReason objects, verbatim." }, "transaction_hashes": { "type": "array", "items": { "type": "string" }, "description": "On-chain transaction hash(es) carrying this deposit, the anchor both ops teams reconcile against the chain with." } }, "required": [ "tesser_deposit_id", "usdc_amount", "risk_status", "risk_status_reasons", "transaction_hashes" ] }, "ReportDepositResponse": { "type": "object", "description": "Acknowledgement that the report was recorded (§6.3). It carries no risk or amount verdict; Nexa's decision arrives later by webhook.", "properties": { "tesser_quote_id": { "type": "string", "format": "uuid" }, "tesser_deposit_id": { "type": "string", "format": "uuid" }, "quote_status": { "$ref": "#/components/schemas/QuoteStatus" }, "usdc_total_reported": { "$ref": "#/components/schemas/Money", "description": "Sum across all reports on this quote." }, "reported_at": { "type": "string", "format": "date-time" } }, "required": [ "tesser_quote_id", "tesser_deposit_id", "quote_status", "usdc_total_reported", "reported_at" ] }, "DepositReport": { "type": "object", "description": "One recorded deposit report, as echoed in the quote GET.", "properties": { "tesser_deposit_id": { "type": "string", "format": "uuid" }, "usdc_amount": { "$ref": "#/components/schemas/Money" }, "risk_status": { "$ref": "#/components/schemas/RiskStatus" }, "risk_status_reasons": { "type": "array", "items": { "$ref": "#/components/schemas/RiskStatusReason" } }, "transaction_hashes": { "type": "array", "items": { "type": "string" } }, "reported_at": { "type": "string", "format": "date-time" } }, "required": [ "tesser_deposit_id", "usdc_amount", "risk_status", "risk_status_reasons", "transaction_hashes", "reported_at" ] }, "CreatePaymentRequest": { "type": "object", "description": "Payout instruction (§6.4).", "properties": { "tesser_quote_id": { "type": "string", "format": "uuid" }, "gtq_amount": { "$ref": "#/components/schemas/Money", "description": "Must equal the amount Nexa reported in its own quote.credit.confirmed event. Deliberately redundant: cheap insurance against wrong-quote-ID bugs in a money-moving instruction." } }, "required": [ "tesser_quote_id", "gtq_amount" ] }, "Payment": { "type": "object", "description": "A payment as returned by create (§6.4).", "properties": { "nexa_payment_id": { "type": "string" }, "tesser_quote_id": { "type": "string", "format": "uuid" }, "quote_status": { "$ref": "#/components/schemas/QuoteStatus" }, "payment_status": { "$ref": "#/components/schemas/PaymentStatus", "description": "Outcome of the payout for this payment." }, "gtq_amount": { "$ref": "#/components/schemas/Money" }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "description": "When Nexa completed the payout. Present only when `payment_status` is `COMPLETED`." }, "status_metadata": { "type": "object", "description": "Free-form: rail references, failure reasons. Shape varies by rail, so it is deliberately untyped. Carries the decline reason when a synchronous decline returns `payment_status: \"FAILED\"` on this call." } }, "required": [ "nexa_payment_id", "tesser_quote_id", "quote_status", "payment_status", "gtq_amount", "created_at" ] }, "QuotePaymentSummary": { "type": "object", "description": "The payment sub-object embedded in the quote GET, when one exists.", "properties": { "nexa_payment_id": { "type": "string" }, "payment_status": { "$ref": "#/components/schemas/PaymentStatus" }, "gtq_amount": { "$ref": "#/components/schemas/Money" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "nexa_payment_id", "payment_status", "gtq_amount", "created_at" ] }, "QuoteDetail": { "description": "The merged quote view (§6.5): the §6.1–6.3 fields, every deposit report, the credit-decision fields once Nexa has decided, and a payment sub-object when one exists.", "allOf": [ { "$ref": "#/components/schemas/Quote" }, { "type": "object", "properties": { "deposit_deadline": { "type": "string", "format": "date-time" }, "accepted_at": { "type": "string", "format": "date-time" }, "usdc_total_reported": { "$ref": "#/components/schemas/Money" }, "credited_gtq": { "$ref": "#/components/schemas/Money", "description": "Authoritative credited amount; present once Nexa has decided to credit. May deviate from quoted_gtq." }, "credited_at": { "type": "string", "format": "date-time" }, "deposits": { "type": "array", "items": { "$ref": "#/components/schemas/DepositReport" }, "description": "All reports on this quote, including late ones." }, "payment": { "$ref": "#/components/schemas/QuotePaymentSummary" } }, "required": [ "deposits" ] } ] }, "PaymentDetail": { "description": "The payment view (§6.6): the §6.4 fields plus the current status, rail metadata and timestamps.", "allOf": [ { "$ref": "#/components/schemas/Payment" }, { "type": "object", "properties": { "updated_at": { "type": "string", "format": "date-time" } } } ] }, "TesserWebhookEnvelope": { "type": "object", "description": "Tesser's standard outbound webhook envelope, reproduced here for orientation only. https://docs.tesser.xyz is the normative definition (spec §6.7 documents the subscription Nexa needs rather than re-specifying Tesser's existing envelope). Note this is NOT the Nexa-to-Tesser WebhookEnvelope of §7; the two directions use each sender's own existing format.", "properties": { "id": { "type": "string", "description": "Event identifier (UUID), the dedupe key." }, "type": { "type": "string", "description": "Event type in scope.action form. The subscription Nexa needs is the withdrawal events behind §9.2: withdrawal.quote_created, withdrawal.steps_created, withdrawal.balance_updated, withdrawal.updated." }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "description": "Event payload wrapper.", "properties": { "object": { "type": "object", "description": "The event-specific object. For withdrawal events, the withdrawal (see WithdrawalResponse in the Tesser-side document, and docs.tesser.xyz)." } }, "required": [ "object" ] } }, "required": [ "id", "type", "created_at", "data" ] } } } }