{"openapi":"3.1.0","info":{"title":"DePix API","version":"0.18.0","description":"Public API of DePix — PIX ⇄ DePix (Liquid) payments for merchants, integrators and AI agents.\n\n**Authentication**: Bearer API key (`sk_live_` production / `sk_test_` sandbox) created in the dashboard. Every operation lists its required key scope in `x-required-scope` (`merchant_read`, `merchant_write`, `wallet_read` or `wallet_write`); there is no scope hierarchy. The same endpoints also accept the first-party dashboard JWT.\n\n**Sandbox**: `sk_test_` keys exercise the full surface synthetically — deposits/withdrawals return `sandbox: true` payloads with nothing to pay and create no rows; checkouts/products are created in sandbox mode and completed via the simulate endpoints. Sandbox operations never fire deposit.*/withdraw.* webhooks.\n\n**Conventions**: all amounts are integer cents (BRL); every response carries an `X-Request-Id` header; errors use a dual envelope with a machine-readable `error.code` from a closed catalog; money-moving POSTs accept an optional `Idempotency-Key` header; 429/503 responses carry `Retry-After`. Status polling: 5–15 s intervals are recommended, stopping on the enum values marked `x-terminal: true`.\n\n**Fees**: charged by DePix and DEDUCTED from the amount — a deposit credits less DePix than the PIX paid, and a withdrawal pays out less BRL than the DePix sent. Deposit: 2% + R$ 0.99 (a R$ 100.00 PIX credits R$ 97.01 in DePix). Withdrawal: 1% + R$ 1.00 up to R$ 100.00, 2% above R$ 100.00 (a R$ 100.00 withdrawal pays R$ 98.00 to the PIX key). On the API-key withdrawal path a platform fee is charged in addition and paid by the caller as a separate DePix output (`fee_cents`/`fee_address`). Canonical, always-current rates: https://depixapp.com/en/#landing-fees\n\n**DePix asset**: DePix is an issued asset on Liquid mainnet, asset id `02f22f8d9c76ab41661a2729e4752e2c5d1a263012141b86ea98af5472df5189` — 8 decimals, 1 DePix = R$ 1.00, so 1 cent = 1,000,000 base units. You need it whenever you build the Liquid transaction yourself instead of using the SDK, in particular for the mandatory explicit fee output on the API-key withdrawal path.\n\n**Scope of this document**: only the agent/integrator surface. JWT-only dashboard routes (auth/*, merchant create/get + rotate-webhook-secret, api-keys management, reports, uploads, webhook-logs, status, contact, …) are internal SPA contract and intentionally undocumented here. The merchant light-profile PATCH (`PATCH /api/merchants/me`, scope `merchant_write`) is the one merchant route that IS part of the agent surface.","contact":{"name":"DePix","url":"https://depixapp.com"}},"servers":[{"url":"https://api.depixapp.com","description":"Canonical API base URL"},{"url":"https://depix-backend.vercel.app","description":"legacy alias"}],"security":[{"apiKey":[]}],"tags":[{"name":"pay","description":"Deposits and withdrawals by API key (scopes `wallet_write` for money movement, `wallet_read` for status)."},{"name":"checkouts","description":"Charging via checkouts (scopes `merchant_write`/`merchant_read`)."},{"name":"products","description":"Reusable products (scopes `merchant_write`/`merchant_read`)."},{"name":"merchant","description":"Merchant profile self-service — edit the light fields (scope `merchant_write`); read via GET /api/me (`merchant_read`)."},{"name":"public","description":"Unauthenticated payer-side endpoints."},{"name":"agents","description":"Agent self-onboarding (keypair-signed). Registration requires an operator token (anti-farm anchor)."},{"name":"meta","description":"Service metadata."}],"paths":{"/api/deposit":{"post":{"tags":["pay"],"operationId":"createDeposit","summary":"Create a personal deposit (PIX → DePix)","description":"Generates a PIX QR; when the owner pays it, DePix is delivered to `depixAddress`. Requires scope `wallet_write` on the API-key path. A provider business rejection returns HTTP 400 `validation_error` (the provider message is preserved in `response.errorMessage`) — not a 200. With a sk_test_ key the response is synthetic (`sandbox: true`, no provider call, no row). Track settlement by polling GET /api/deposits/{id} (5–15 s interval) and/or via the deposit.* webhooks. Supports Idempotency-Key. **Fee**: 2% + R$ 0.99, DEDUCTED from the amount — `amountInCents` is what the payer pays by PIX, and the DePix credited to `depixAddress` is that minus the fee (a R$ 100.00 / 10000 deposit credits R$ 97.01 / 9701 in DePix). Current rates: https://depixapp.com/en/#landing-fees.","x-required-scope":"wallet_write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositCreateRequest"},"examples":{"live":{"value":{"amountInCents":5000,"depixAddress":"lq1qqw508d6qejxtdg4y5r3zarvary0c5xw7k…","payer_tax_number":"52998224725"}}}}}},"responses":{"200":{"description":"QR issued.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositCreateResponse"},"examples":{"live":{"summary":"Live QR issued","value":{"async":false,"response":{"qrCopyPaste":"00020126580014br.gov.bcb.pix0136…","qrImageUrl":"https://depix.eulen.app/qr/qr-id-456.png","id":"qr-id-456"}}},"sandbox":{"summary":"Sandbox (sk_test_) — synthetic QR, nothing to pay","value":{"async":false,"response":{"qrCopyPaste":"SANDBOX-DEPIX-TEST-MODE-DO-NOT-PAY-a1b2c3d4e5f60708","qrImageUrl":null,"id":"sandbox_a1b2c3d4e5f60708","sandbox":true}}}}}}},"400":{"description":"Invalid input, amount outside 500–300000, account limit, per-key spending limit, missing payer tax number, or upstream rejection (provider refused the request — passed through as validation_error, with the provider message in response.errorMessage).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"amount_out_of_range":{"value":{"response":{"errorMessage":"Valor deve ser entre R$ 5.00 e R$ 3000.00"},"error":{"code":"amount_out_of_range","message":"Amount outside the accepted range for this endpoint.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"min_cents":500,"max_cents":300000}}}},"key_limit_exceeded":{"value":{"response":{"errorMessage":"Esta operação excede o limite por transação desta API key (R$ 100,00)."},"error":{"code":"key_limit_exceeded","message":"This operation exceeds a spending limit set on this API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"limit":"per_tx","limit_cents":10000,"used_cents":0}}}},"upstream_rejected":{"value":{"response":{"errorMessage":"Valor não permitido para este usuário."},"error":{"code":"validation_error","message":"Invalid request. Check the fields and try again.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"The API key lacks the `wallet_write` scope required by this operation. May also be `account_blocked`, or an operation-specific 403 — see the error catalog.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"response":{"errorMessage":"Esta API key não tem permissão para esta operação."},"error":{"code":"insufficient_scope","message":"This session does not have the scope required for this operation.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"required_scope":"wallet_write"}}}}}}}},"409":{"description":"A request with the same Idempotency-Key is still in flight — retry after `retry_after` seconds.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"idempotency_in_flight":{"value":{"response":{"errorMessage":"Uma requisição com esta Idempotency-Key ainda está em processamento."},"error":{"code":"idempotency_in_flight","message":"A request with this Idempotency-Key is still being processed. Retry shortly.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":5,"docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"422":{"description":"The Idempotency-Key was already used with a different request body (strict byte-level comparison of the parsed body).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"idempotency_key_reuse":{"value":{"response":{"errorMessage":"Esta Idempotency-Key já foi usada com um corpo diferente."},"error":{"code":"idempotency_key_reuse","message":"This Idempotency-Key was already used with a different request body.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited, or too many QRs for the same payer CPF/CNPJ (`payer_velocity_limit`: max 2 per sliding 30-minute window, deposits + checkouts combined). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"payer_velocity_limit":{"value":{"response":{"errorMessage":"Muitas transações para este CPF/CNPJ em pouco tempo. Aguarde 18 minutos e tente novamente."},"error":{"code":"payer_velocity_limit","message":"Too many deposits for this payer CPF/CNPJ in a short period. Wait and try again.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":1080,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"window_minutes":30,"max_per_window":2}}}},"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}}}}},"/api/deposits/{id}":{"get":{"tags":["pay"],"operationId":"getDeposit","summary":"Read deposit status","description":"Pay-side status read (ownership enforced — foreign ids are 404). Poll every 5–15 s until a terminal status; `depix_sent` is terminal success. With sk_test_, sandbox_* ids return a fixed synthetic terminal state; any other id is 404 (test keys never read live rows).","x-required-scope":"wallet_read","parameters":[{"name":"id","in":"path","required":true,"description":"Deposit id returned by POST /api/deposit (sandbox_* in test mode).","schema":{"type":"string"}}],"responses":{"200":{"description":"Deposit status.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositStatusResponse"},"examples":{"live":{"summary":"Live row","value":{"id":"qr-id-456","type":"deposit","amount_cents":5000,"status":"depix_sent","created_at":"2026-07-01 12:00:00","updated_at":"2026-07-01 12:34:56","rejection_reasons":[]}},"sandbox":{"summary":"Sandbox synthetic (fixed)","value":{"id":"sandbox_3uw_a1b2c3d4e5f60708","type":"deposit","amount_cents":5000,"status":"depix_sent","created_at":"2026-01-01 00:00:00","updated_at":"2026-01-01 00:00:00","sandbox":true,"rejection_reasons":[]}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"The API key lacks the `wallet_read` scope required by this operation. May also be `account_blocked`, or an operation-specific 403 — see the error catalog.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"response":{"errorMessage":"Esta API key não tem permissão para esta operação."},"error":{"code":"insufficient_scope","message":"This session does not have the scope required for this operation.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"required_scope":"wallet_read"}}}}}}}},"404":{"description":"Deposit not found — includes rows owned by another account (ownership is never disclosed).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"value":{"response":{"errorMessage":"Deposit não encontrado."},"error":{"code":"not_found","message":"Resource not found.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}}}}},"/api/withdraw":{"post":{"tags":["pay"],"operationId":"createWithdrawal","summary":"Create a withdrawal (DePix → PIX)","description":"Quotes a withdrawal: the response contains the Liquid address to send DePix to. After broadcasting, track via GET /api/withdrawals/{id} and/or withdraw.* webhooks. Requires scope `wallet_write` on the API-key path. **Platform fee (API-key path)**: the response includes `fee_cents` + `fee_address` — the transaction MUST also pay `fee_cents` to `fee_address` as an explicit (unblinded) DePix output in the SAME transaction as the provider output. The fee is verified server-side against the provider-reported settlement transaction; sending the withdrawal without it results in a failed withdrawal and lost funds. sk_test_ returns a synthetic quote (`sandbox: true`, fixed 2% rate, deterministic fee fields, no provider call, no row). Supports Idempotency-Key. **Fee**: 1% + R$ 1.00 up to R$ 100.00 and 2% above R$ 100.00, DEDUCTED from the amount — a R$ 100.00 (10000) withdrawal pays R$ 98.00 (9800) to the PIX key. The quoted `depositAmountInCents`/`payoutAmountInCents` pair is authoritative for a given request; do not recompute it client-side. Current rates: https://depixapp.com/en/#landing-fees. On the API-key path the platform fee (`fee_cents`) is charged IN ADDITION and paid by you as a second output, so the gross wallet outflow is `totalDepositAmountInCents`.","x-required-scope":"wallet_write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawCreateRequest"},"examples":{"you_send":{"summary":"\"You send\" mode","value":{"pixKey":"someone@example.com","depositAmountInCents":10000,"taxNumber":"52998224725"}},"you_receive":{"summary":"\"You receive\" mode","value":{"pixKey":"someone@example.com","payoutAmountInCents":9800,"taxNumber":"52998224725"}}}}}},"responses":{"200":{"description":"Withdrawal quote.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawCreateResponse"},"examples":{"live":{"summary":"Live quote (JWT — no platform fee fields)","value":{"response":{"withdrawalId":"wd-123","depositAddress":"lq1qq2v9wxkyz…","depositAmountInCents":10000,"payoutAmountInCents":9800}}},"api_key_fee":{"summary":"API key — mandatory platform fee (fee_cents/fee_address)","value":{"response":{"withdrawalId":"wd-124","depositAddress":"lq1qq2v9wxkyz…","depositAmountInCents":9900,"payoutAmountInCents":9700,"totalDepositAmountInCents":10000,"split":{"address":"ex1qfee…","amountCentavos":100},"fee_cents":100,"fee_address":"ex1qfee…"}}},"split":{"summary":"Integrated wallet with split fee (JWT)","value":{"response":{"withdrawalId":"wd-125","depositAddress":"lq1qq2v9wxkyz…","depositAmountInCents":9900,"payoutAmountInCents":9700,"totalDepositAmountInCents":10000,"split":{"address":"lq1qqfee…","amountCentavos":100}}}},"sandbox":{"summary":"Sandbox (sk_test_) — synthetic quote, do not pay","value":{"response":{"withdrawalId":"sandbox_0011223344556677","depositAddress":"SANDBOX-LIQUID-ADDRESS-DO-NOT-PAY","depositAmountInCents":10000,"payoutAmountInCents":9800,"fee_cents":100,"fee_address":"SANDBOX-LIQUID-FEE-ADDRESS-DO-NOT-PAY","sandbox":true}}}}}}},"400":{"description":"Invalid input, amount outside the mode's bounds, per-key spending limit, missing tax number, or upstream rejection (invalid PIX key etc. — passed through as validation_error).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"amount_out_of_range":{"value":{"response":{"errorMessage":"Valor deve ser entre R$ 5.00 e R$ 6000.00"},"error":{"code":"amount_out_of_range","message":"Amount outside the accepted range for this endpoint.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"min_cents":500,"max_cents":600000}}}},"tax_number_required":{"value":{"response":{"errorMessage":"Informe o CPF ou CNPJ do titular da chave PIX."},"error":{"code":"tax_number_required","message":"The payer's CPF/CNPJ (payer_tax_number) is required.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"Missing `wallet_write` scope, withdrawals disabled (kill switch), external wallets disabled, blocked account, or missing WhatsApp verification.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"response":{"errorMessage":"Esta API key não tem permissão para esta operação."},"error":{"code":"insufficient_scope","message":"This session does not have the scope required for this operation.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"required_scope":"wallet_write"}}}},"withdraw_disabled":{"value":{"response":{"errorMessage":"O saque está temporariamente indisponível. Tente novamente mais tarde."},"error":{"code":"withdraw_disabled","message":"Withdrawals are temporarily disabled.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"409":{"description":"A request with the same Idempotency-Key is still in flight — retry after `retry_after` seconds.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"idempotency_in_flight":{"value":{"response":{"errorMessage":"Uma requisição com esta Idempotency-Key ainda está em processamento."},"error":{"code":"idempotency_in_flight","message":"A request with this Idempotency-Key is still being processed. Retry shortly.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":5,"docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"422":{"description":"The Idempotency-Key was already used with a different request body (strict byte-level comparison of the parsed body).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"idempotency_key_reuse":{"value":{"response":{"errorMessage":"Esta Idempotency-Key já foi usada com um corpo diferente."},"error":{"code":"idempotency_key_reuse","message":"This Idempotency-Key was already used with a different request body.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}}}}},"/api/withdrawals/{id}":{"get":{"tags":["pay"],"operationId":"getWithdrawal","summary":"Read withdrawal status","description":"Pay-side status read (ownership enforced — foreign ids are 404). Poll every 5–15 s until a terminal status; `sent` is terminal success. With sk_test_, sandbox_* ids return the fixed synthetic sandbox-only state `confirmed`; any other id is 404.","x-required-scope":"wallet_read","parameters":[{"name":"id","in":"path","required":true,"description":"Withdrawal id returned by POST /api/withdraw (sandbox_* in test mode).","schema":{"type":"string"}}],"responses":{"200":{"description":"Withdrawal status.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawalStatusResponse"},"examples":{"live":{"summary":"Live row","value":{"id":"wd-123","type":"withdraw","amount_cents":10000,"status":"sent","created_at":"2026-07-01 10:00:00","updated_at":"2026-07-01 10:00:00","liquid_txid":"abababababababababababababababababababababababababababababababab"}},"sandbox":{"summary":"Sandbox synthetic (fixed)","value":{"id":"sandbox_7ps_0011223344556677","type":"withdraw","amount_cents":10000,"status":"confirmed","created_at":"2026-01-01 00:00:00","updated_at":"2026-01-01 00:00:00","sandbox":true}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"The API key lacks the `wallet_read` scope required by this operation. May also be `account_blocked`, or an operation-specific 403 — see the error catalog.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"response":{"errorMessage":"Esta API key não tem permissão para esta operação."},"error":{"code":"insufficient_scope","message":"This session does not have the scope required for this operation.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"required_scope":"wallet_read"}}}}}}}},"404":{"description":"Withdrawal not found — includes rows owned by another account (ownership is never disclosed).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"value":{"response":{"errorMessage":"Withdrawal não encontrado."},"error":{"code":"not_found","message":"Resource not found.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}}}}},"/api/checkouts":{"post":{"tags":["checkouts"],"operationId":"createCheckout","summary":"Create a checkout","description":"Creates a charge with a PIX QR and hosted payment page. Requires scope `merchant_write` on the API-key path; a merchant profile is required. sk_test_ creates a sandbox checkout (non-payable placeholder QR — complete it via simulate-payment). Track via GET /api/checkouts/{id} polling or checkout.* webhooks. Supports Idempotency-Key.","x-required-scope":"merchant_write","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutCreateRequest"},"examples":{"minimal":{"value":{"amount":1500,"payer_tax_number":"52998224725"}},"full":{"value":{"amount":1500,"description":"Pedido #123","callback_url":"https://store.example.com/webhooks/depix","redirect_url":"https://store.example.com/obrigado","metadata":{"order_id":"123"},"expires_in":900,"payer_tax_number":"52998224725"}}}}}},"responses":{"201":{"description":"Checkout created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Idempotency-Replayed":{"$ref":"#/components/headers/IdempotencyReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutCreateResponse"},"examples":{"created":{"value":{"id":"chk_abc123","status":"pending","amount":1500,"description":"Pedido #123","image_url":null,"expires_at":"2026-07-01 12:20:00","is_live":true,"payment_url":"https://pay.depixapp.com/chk_abc123","pix":{"qr_code":"00020126580014br.gov.bcb.pix…"}}}}}}},"400":{"description":"Validation failure — the legacy per-field `response.errors[]` sibling is preserved.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"validation_error":{"value":{"response":{"errorMessage":"Dados inválidos.","errors":[{"field":"amount","message":"Obrigatório. Valor em centavos (integer)."}]},"error":{"code":"validation_error","message":"Invalid request. Check the fields and try again.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"field":"amount"}}}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"The authenticated account has no active merchant profile.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"merchant_required":{"value":{"response":{"errorMessage":"Você não possui conta de lojista."},"error":{"code":"merchant_required","message":"A merchant profile is required for this operation.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"409":{"description":"A request with the same Idempotency-Key is still in flight — retry after `retry_after` seconds.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"idempotency_in_flight":{"value":{"response":{"errorMessage":"Uma requisição com esta Idempotency-Key ainda está em processamento."},"error":{"code":"idempotency_in_flight","message":"A request with this Idempotency-Key is still being processed. Retry shortly.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":5,"docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"422":{"description":"The Idempotency-Key was already used with a different request body (strict byte-level comparison of the parsed body).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"idempotency_key_reuse":{"value":{"response":{"errorMessage":"Esta Idempotency-Key já foi usada com um corpo diferente."},"error":{"code":"idempotency_key_reuse","message":"This Idempotency-Key was already used with a different request body.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited, or too many QRs for the same payer CPF/CNPJ (`payer_velocity_limit`: max 2 per sliding 30-minute window, deposits + checkouts combined). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"payer_velocity_limit":{"value":{"response":{"errorMessage":"Muitas transações para este CPF/CNPJ em pouco tempo. Aguarde 18 minutos e tente novamente."},"error":{"code":"payer_velocity_limit","message":"Too many deposits for this payer CPF/CNPJ in a short period. Wait and try again.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":1080,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"window_minutes":30,"max_per_window":2}}}},"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}}}},"get":{"tags":["checkouts"],"operationId":"listCheckouts","summary":"List checkouts","description":"Paginated checkout list for the authenticated merchant, filtered to the key's mode (sk_test_ sees only sandbox checkouts). Requires scope `merchant_read` on the API-key path.","x-required-scope":"merchant_read","parameters":[{"name":"status","in":"query","required":false,"description":"Filter by status.","schema":{"$ref":"#/components/schemas/CheckoutStatus"}},{"name":"product_id","in":"query","required":false,"description":"Filter by originating product id.","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"Filter: created_at >= this timestamp (UTC).","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"Filter: created_at <= this timestamp (UTC).","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Substring search over id and description.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size (1–100, default 50).","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","required":false,"description":"Pagination offset (default 0).","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Checkout list.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutListResponse"},"examples":{"list":{"value":{"checkouts":[{"id":"chk_abc123","status":"completed","amount":1500,"description":"Pedido #123","created_at":"2026-07-01 12:00:00","expires_at":"2026-07-01 12:20:00","is_live":1,"processing_at":"2026-07-01 12:01:00","approved_at":null,"metadata":"{\"order_id\":\"123\"}","product_name":null,"rejection_reasons":[]}],"stats":{"total":1,"pending":0,"completed":1,"completed_amount":1500},"limit":50,"offset":0}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"The API key lacks the `merchant_read` scope required by this operation. May also be `account_blocked`, or an operation-specific 403 — see the error catalog.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"response":{"errorMessage":"Esta API key não tem permissão para esta operação."},"error":{"code":"insufficient_scope","message":"This session does not have the scope required for this operation.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"required_scope":"merchant_read"}}}}}}}},"429":{"description":"Rate limited. Beyond the endpoint's own limit when set (`rate_limited`), API-key calls are also bounded by the shared per-merchant budget (`merchant_rate_limited`, default 30 req/min across all endpoints) and by the key's own rate limit when configured (`rate_limited`). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"merchant_rate_limited":{"value":{"response":{"errorMessage":"Rate limit do merchant excedido."},"error":{"code":"merchant_rate_limited","message":"Merchant rate limit exceeded.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":22,"docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}}}}},"/api/checkouts/{id}":{"get":{"tags":["checkouts"],"operationId":"getCheckout","summary":"Get a checkout","description":"Full checkout detail (owner view). `pix_payload` is present only while pending. Poll until a terminal status (see the status enum) or subscribe to checkout.* webhooks. Requires scope `merchant_read` on the API-key path.","x-required-scope":"merchant_read","parameters":[{"name":"id","in":"path","required":true,"description":"Checkout id (chk_*).","schema":{"type":"string"}}],"responses":{"200":{"description":"Checkout detail.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutGetResponse"},"examples":{"completed":{"value":{"checkout":{"id":"chk_abc123","status":"completed","amount":1500,"description":"Pedido #123","image_url":null,"callback_url":"https://store.example.com/webhooks/depix","redirect_url":null,"metadata":{"order_id":"123"},"expires_at":"2026-07-01 12:20:00","is_live":1,"created_at":"2026-07-01 12:00:00","processing_at":"2026-07-01 12:01:00","approved_at":null,"completed_at":"2026-07-01 12:02:00","cancelled_at":null,"blockchain_tx_id":"cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd","rejection_reasons":[]}}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"The API key lacks the `merchant_read` scope required by this operation. May also be `account_blocked`, or an operation-specific 403 — see the error catalog.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"response":{"errorMessage":"Esta API key não tem permissão para esta operação."},"error":{"code":"insufficient_scope","message":"This session does not have the scope required for this operation.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"required_scope":"merchant_read"}}}}}}}},"404":{"description":"Checkout not found — includes rows owned by another account (ownership is never disclosed).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"value":{"response":{"errorMessage":"Checkout não encontrado."},"error":{"code":"not_found","message":"Resource not found.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited. Beyond the endpoint's own limit when set (`rate_limited`), API-key calls are also bounded by the shared per-merchant budget (`merchant_rate_limited`, default 30 req/min across all endpoints) and by the key's own rate limit when configured (`rate_limited`). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"merchant_rate_limited":{"value":{"response":{"errorMessage":"Rate limit do merchant excedido."},"error":{"code":"merchant_rate_limited","message":"Merchant rate limit exceeded.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":22,"docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}}}}},"/api/checkouts/{id}/simulate-payment":{"post":{"tags":["checkouts"],"operationId":"simulateCheckoutPayment","summary":"Simulate payment (sandbox only)","description":"Completes a SANDBOX checkout as if it were paid (fires checkout.completed when a callback URL is set). Live checkouts are 403 sandbox_only. Requires scope `merchant_write` on the API-key path.","x-required-scope":"merchant_write","parameters":[{"name":"id","in":"path","required":true,"description":"Sandbox checkout id (chk_*).","schema":{"type":"string"}}],"responses":{"200":{"description":"Simulated as paid.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"},"examples":{"ok":{"value":{"success":true}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"Live checkout (sandbox_only), missing scope, or no merchant profile.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"sandbox_only":{"value":{"response":{"errorMessage":"Simulação disponível apenas para checkouts de teste."},"error":{"code":"sandbox_only","message":"This operation is only available on sandbox (test mode) resources.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"404":{"description":"Checkout not found — includes rows owned by another account (ownership is never disclosed).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"value":{"response":{"errorMessage":"Checkout não encontrado."},"error":{"code":"not_found","message":"Resource not found.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"409":{"description":"The checkout cannot transition to completed from its current status.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"conflict":{"value":{"response":{"errorMessage":"Checkout não pode ser concluído no status atual."},"error":{"code":"conflict","message":"The request conflicts with the current state of the resource.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited. Beyond the endpoint's own limit when set (`rate_limited`), API-key calls are also bounded by the shared per-merchant budget (`merchant_rate_limited`, default 30 req/min across all endpoints) and by the key's own rate limit when configured (`rate_limited`). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"merchant_rate_limited":{"value":{"response":{"errorMessage":"Rate limit do merchant excedido."},"error":{"code":"merchant_rate_limited","message":"Merchant rate limit exceeded.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":22,"docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}}}}},"/api/me":{"get":{"tags":["checkouts"],"operationId":"getMe","summary":"Identify the authenticated merchant","description":"Probe endpoint: returns the merchant behind the credentials. 404 (not 403) when the account has no merchant profile — integrators use that to tell \"valid key, no merchant yet\" apart. Requires scope `merchant_read` on the API-key path.","x-required-scope":"merchant_read","responses":{"200":{"description":"Merchant identity.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"},"examples":{"me":{"value":{"merchant_id":"mrc_1","name":"Loja Teste","username":"owner","merchant_slug":"loja-teste","is_live":false,"created_at":"2026-01-01 00:00:00"}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"The API key lacks the `merchant_read` scope required by this operation. May also be `account_blocked`, or an operation-specific 403 — see the error catalog.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"response":{"errorMessage":"Esta API key não tem permissão para esta operação."},"error":{"code":"insufficient_scope","message":"This session does not have the scope required for this operation.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"required_scope":"merchant_read"}}}}}}}},"404":{"description":"Valid credentials but no merchant profile yet.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"value":{"response":{"errorMessage":"Conta de lojista não encontrada."},"error":{"code":"not_found","message":"Resource not found.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited. Beyond the endpoint's own limit when set (`rate_limited`), API-key calls are also bounded by the shared per-merchant budget (`merchant_rate_limited`, default 30 req/min across all endpoints) and by the key's own rate limit when configured (`rate_limited`). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"merchant_rate_limited":{"value":{"response":{"errorMessage":"Rate limit do merchant excedido."},"error":{"code":"merchant_rate_limited","message":"Merchant rate limit exceeded.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":22,"docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}}}}},"/api/tickets":{"post":{"tags":["support"],"operationId":"createTicket","summary":"Open a support ticket","description":"Opens a support ticket (human or agent — one channel). Send a Bearer JWT or an sk_ API key; NO scope is required. The body becomes the first message. Up to 5 open tickets per account (1 for suspended accounts). Poll GET /api/tickets/{id} for the reply (support answers within 1 business day — check in minutes, not seconds). For API questions, the docs/llms.txt usually answer instantly.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketCreateRequest"},"examples":{"minimal":{"value":{"subject":"Não recebi meu depósito","body":"Paguei o PIX há 1h e o DePix não chegou."}},"full":{"value":{"subject":"Erro 500 no checkout","body":"POST /api/checkouts retorna 500 com este corpo…","category":"bug"}}}}}},"responses":{"201":{"description":"Ticket created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketResponse"},"examples":{"created":{"value":{"ticket":{"id":"tkt_ab12cd34ef","opener_type":"human","status":"awaiting_reply","subject":"Não recebi meu depósito","category":"other","created_at":"2026-07-22 12:00:00","last_activity_at":"2026-07-22 12:00:00","closed_reason":null,"closed_at":null}}}}}}},"400":{"description":"Validation failure — the legacy per-field `response.errors[]` sibling is preserved.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"validation_error":{"value":{"response":{"errorMessage":"Dados inválidos.","errors":[{"field":"subject","message":"subject must be 4–120 characters"}]},"error":{"code":"validation_error","message":"Invalid request. Check the fields and try again.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"field":"subject"}}}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited, or the open-ticket cap was reached (`ticket_open_cap`: max 5 open tickets, 1 for suspended accounts).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"ticket_open_cap":{"value":{"response":{"errorMessage":"Você atingiu o limite de tickets abertos. Feche um antes de abrir outro."},"error":{"code":"ticket_open_cap","message":"You have reached the maximum number of open tickets. Close one before opening another.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"max_open":5}}}},"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":30,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"tickets-create"}}}}}}}}}},"get":{"tags":["support"],"operationId":"listTickets","summary":"List your tickets","description":"Lists the tickets created by THIS principal (this session/key) — a session never sees tickets opened by another session or key. NO scope required.","security":[],"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1–100, default 50).","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","required":false,"description":"Pagination offset (default 0).","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Ticket list.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketListResponse"},"examples":{"list":{"value":{"tickets":[{"id":"tkt_ab12cd34ef","opener_type":"human","status":"answered","subject":"Não recebi meu depósito","category":"other","created_at":"2026-07-22 12:00:00","last_activity_at":"2026-07-22 13:00:00","closed_reason":null,"closed_at":null}],"total":1,"limit":50,"offset":0}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}}}}},"/api/tickets/{id}":{"get":{"tags":["support"],"operationId":"getTicket","summary":"Get a ticket + messages","description":"Full ticket detail with its message thread. 404 also covers a ticket owned by another principal (ownership is never disclosed). NO scope required.","security":[],"parameters":[{"name":"id","in":"path","required":true,"description":"Ticket id (tkt_*).","schema":{"type":"string"}}],"responses":{"200":{"description":"Ticket detail.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketGetResponse"},"examples":{"detail":{"value":{"ticket":{"id":"tkt_ab12cd34ef","opener_type":"human","status":"answered","subject":"Não recebi meu depósito","category":"other","created_at":"2026-07-22 12:00:00","last_activity_at":"2026-07-22 13:00:00","closed_reason":null,"closed_at":null},"messages":[{"id":"tmsg_1","sender":"user","body":"Paguei o PIX há 1h e o DePix não chegou.","created_at":"2026-07-22 12:00:00"},{"id":"tmsg_2","sender":"admin","body":"Olá! Já localizamos seu depósito, será creditado em instantes.","created_at":"2026-07-22 13:00:00"}]}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"404":{"description":"Ticket not found — includes rows owned by another account (ownership is never disclosed).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"value":{"response":{"errorMessage":"Ticket não encontrado."},"error":{"code":"not_found","message":"Resource not found.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}}}}},"/api/tickets/{id}/messages":{"post":{"tags":["support"],"operationId":"replyTicket","summary":"Reply to a ticket","description":"Posts a user reply. On an answered ticket it moves back to awaiting_reply; on an AUTO-closed ticket within 7 days it reopens it. user/admin-closed tickets are terminal (409 ticket_closed — open a new one). NO scope required.","security":[],"parameters":[{"name":"id","in":"path","required":true,"description":"Ticket id (tkt_*).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketMessageRequest"},"examples":{"reply":{"value":{"body":"Obrigado! Confirmo que o valor chegou."}}}}}},"responses":{"201":{"description":"Reply posted.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketMessageResponse"},"examples":{"posted":{"value":{"message":{"id":"tmsg_3","sender":"user","body":"Obrigado! Confirmo que o valor chegou.","created_at":"2026-07-22 14:00:00"},"ticket":{"id":"tkt_ab12cd34ef","opener_type":"human","status":"awaiting_reply","subject":"Não recebi meu depósito","category":"other","created_at":"2026-07-22 12:00:00","last_activity_at":"2026-07-22 14:00:00","closed_reason":null,"closed_at":null}}}}}}},"400":{"description":"Validation failure — the legacy per-field `response.errors[]` sibling is preserved.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"validation_error":{"value":{"response":{"errorMessage":"Mensagem inválida.","errors":[{"field":"body","message":"body must be 1–4000 characters"}]},"error":{"code":"validation_error","message":"Invalid request. Check the fields and try again.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"field":"body"}}}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"404":{"description":"Ticket not found — includes rows owned by another account (ownership is never disclosed).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"value":{"response":{"errorMessage":"Ticket não encontrado."},"error":{"code":"not_found","message":"Resource not found.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"409":{"description":"The ticket is closed (user/admin close, or an auto-close past its 7-day reopen window). Open a new ticket.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"ticket_closed":{"value":{"response":{"errorMessage":"Este ticket está fechado. Abra um novo ticket para continuar."},"error":{"code":"ticket_closed","message":"This ticket is closed. Open a new ticket to continue.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}}}}},"/api/tickets/{id}/attachments":{"post":{"tags":["support"],"operationId":"attachToTicket","summary":"Attach a file to a ticket","description":"Uploads ONE file (base64 in file_b64, max ~3 MB) and forwards it to the support team — use it to send a screenshot or an app diagnostics/log file when reporting a bug. Same principal + state machine as a reply: an answered ticket returns to awaiting_reply; an auto-closed ticket within 7 days reopens. The file is forwarded to support, NOT stored or served back — the response records only its name/type. Returns 503 attachment_unavailable when the ticket has no support channel yet (retry shortly, or continue with a text reply). NO scope required.","security":[],"parameters":[{"name":"id","in":"path","required":true,"description":"Ticket id (tkt_*).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketAttachmentRequest"},"examples":{"screenshot":{"value":{"filename":"erro-checkout.png","content_type":"image/png","file_b64":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==","caption":"Tela quando o pagamento falha"}},"logs":{"value":{"filename":"depix-diagnostics.json","content_type":"application/json","file_b64":"eyJzY2hlbWEiOiJkZXBpeC1kaWFnbm9zdGljcy12MSJ9"}}}}}},"responses":{"201":{"description":"Attachment forwarded to support and recorded on the thread.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketMessageResponse"},"examples":{"attached":{"value":{"message":{"id":"tmsg_5","sender":"user","body":"erro-checkout.png","created_at":"2026-07-22 14:05:00","attachment":{"name":"erro-checkout.png","mime":"image/png"}},"ticket":{"id":"tkt_ab12cd34ef","opener_type":"human","status":"awaiting_reply","subject":"Não recebi meu depósito","category":"other","created_at":"2026-07-22 12:00:00","last_activity_at":"2026-07-22 14:05:00","closed_reason":null,"closed_at":null}}}}}}},"400":{"description":"Validation failure — missing/invalid content_type or file_b64.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"validation_error":{"value":{"response":{"errorMessage":"Anexo inválido.","errors":[{"field":"content_type","message":"content_type must be one of: image/png, image/jpeg, image/webp, application/pdf, text/plain, application/json"}]},"error":{"code":"validation_error","message":"Invalid request. Check the fields and try again.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"field":"content_type"}}}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"404":{"description":"Ticket not found — includes rows owned by another account (ownership is never disclosed).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"value":{"response":{"errorMessage":"Ticket não encontrado."},"error":{"code":"not_found","message":"Resource not found.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"409":{"description":"The ticket is closed (user/admin close, or an auto-close past its 7-day reopen window). Open a new ticket.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"ticket_closed":{"value":{"response":{"errorMessage":"Este ticket está fechado. Abra um novo ticket para continuar."},"error":{"code":"ticket_closed","message":"This ticket is closed. Open a new ticket to continue.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"413":{"description":"The attachment exceeds the maximum size (~3 MB).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"attachment_too_large":{"value":{"response":{"errorMessage":"Arquivo muito grande."},"error":{"code":"attachment_too_large","message":"The attachment exceeds the maximum allowed size.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}},"503":{"description":"Attachments are temporarily unavailable for this ticket (no support channel yet, or the forward failed). Retry shortly or continue with a text reply.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"attachment_unavailable":{"value":{"response":{"errorMessage":"Anexos indisponíveis para este ticket no momento. Você pode continuar por mensagem de texto."},"error":{"code":"attachment_unavailable","message":"Attachments are temporarily unavailable for this ticket. Try again shortly, or continue with a text message.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}}}}},"/api/tickets/{id}/close":{"post":{"tags":["support"],"operationId":"closeTicket","summary":"Close a ticket","description":"Closes the ticket (closed_reason='user'). Idempotent-ish: a second close returns 409 ticket_closed. NO scope required.","security":[],"parameters":[{"name":"id","in":"path","required":true,"description":"Ticket id (tkt_*).","schema":{"type":"string"}}],"responses":{"200":{"description":"Ticket closed.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketResponse"},"examples":{"closed":{"value":{"ticket":{"id":"tkt_ab12cd34ef","opener_type":"human","status":"closed","subject":"Não recebi meu depósito","category":"other","created_at":"2026-07-22 12:00:00","last_activity_at":"2026-07-22 13:00:00","closed_reason":"user","closed_at":"2026-07-22 15:00:00"}}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"404":{"description":"Ticket not found — includes rows owned by another account (ownership is never disclosed).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"value":{"response":{"errorMessage":"Ticket não encontrado."},"error":{"code":"not_found","message":"Resource not found.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"409":{"description":"The ticket is already closed.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"ticket_closed":{"value":{"response":{"errorMessage":"Este ticket já está fechado."},"error":{"code":"ticket_closed","message":"This ticket is closed. Open a new ticket to continue.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}}}}},"/api/merchants/me":{"patch":{"tags":["merchant"],"operationId":"updateMerchantProfile","summary":"Update the merchant's light profile fields","description":"Partial update of the authenticated merchant's LIGHT profile fields: business_name, website, logo_url, default_callback_url, default_redirect_url. Requires scope `merchant_write` on the API-key path. liquid_address, cnpj and password are owner-only and rejected with 400 validation_error (details.field names the offending field); split_address is never editable here. Read the current profile via GET /api/me. Every PATCH authenticated by an API key emails the account owner naming the changed fields and the key id, so a key-driven change is never silent.","x-required-scope":"merchant_write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantUpdateRequest"},"examples":{"redirect":{"value":{"default_redirect_url":"https://shop.example.com/thanks"}},"rename":{"value":{"business_name":"Nova Loja"}}}}}},"responses":{"200":{"description":"Updated.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantUpdateResponse"},"examples":{"ok":{"value":{"success":true,"merchant_slug":"nova-loja"}}}}}},"400":{"description":"Invalid field value, empty update, or an owner-only field (liquid_address/cnpj/password) sent on the API-key path — `details.field` names it.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"owner_only":{"value":{"response":{"errorMessage":"Este campo só pode ser alterado pelo dono da conta no painel web."},"error":{"code":"validation_error","message":"Invalid request. Check the fields and try again.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"field":"liquid_address"}}}},"empty":{"value":{"response":{"errorMessage":"Nenhum campo para atualizar."},"error":{"code":"validation_error","message":"Invalid request. Check the fields and try again.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"The API key lacks the `merchant_write` scope required by this operation. May also be `account_blocked`, or an operation-specific 403 — see the error catalog.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"response":{"errorMessage":"Esta API key não tem permissão para esta operação."},"error":{"code":"insufficient_scope","message":"This session does not have the scope required for this operation.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"required_scope":"merchant_write"}}}}}}}},"429":{"description":"Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}}}}},"/api/products":{"post":{"tags":["products"],"operationId":"createProduct","summary":"Create a product","description":"Creates a reusable product (fixed-price checkout template with a public page). Requires scope `merchant_write` on the API-key path. sk_test_ creates sandbox products.","x-required-scope":"merchant_write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductCreateRequest"},"examples":{"minimal":{"value":{"name":"Ebook DePix","amount":700}}}}}},"responses":{"201":{"description":"Product created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductCreateResponse"},"examples":{"created":{"value":{"product":{"id":"prd_abc123","slug":"ebook-depix","name":"Ebook DePix","amount":700,"description":null,"image_url":null,"callback_url":null,"redirect_url":null,"metadata":null,"expires_in":1200,"active":true,"is_live":true,"payment_url":"https://pay.depixapp.com/loja-teste/ebook-depix","created_at":"2026-07-01T12:00:00.000Z"}}}}}}},"400":{"description":"Invalid name/slug/amount/urls/metadata/expires_in.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"validation_error":{"value":{"response":{"errorMessage":"Nome é obrigatório."},"error":{"code":"validation_error","message":"Invalid request. Check the fields and try again.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"field":"name"}}}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"The authenticated account has no active merchant profile.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"merchant_required":{"value":{"response":{"errorMessage":"Você não possui conta de lojista."},"error":{"code":"merchant_required","message":"A merchant profile is required for this operation.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"409":{"description":"Slug already used by another product of this merchant (same mode).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"conflict":{"value":{"response":{"errorMessage":"Já existe um produto com este slug."},"error":{"code":"conflict","message":"The request conflicts with the current state of the resource.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited. Beyond the endpoint's own limit when set (`rate_limited`), API-key calls are also bounded by the shared per-merchant budget (`merchant_rate_limited`, default 30 req/min across all endpoints) and by the key's own rate limit when configured (`rate_limited`). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"merchant_rate_limited":{"value":{"response":{"errorMessage":"Rate limit do merchant excedido."},"error":{"code":"merchant_rate_limited","message":"Merchant rate limit exceeded.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":22,"docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}}}},"get":{"tags":["products"],"operationId":"listProducts","summary":"List products","description":"Paginated product list with checkout aggregates, filtered to the key's mode. Requires scope `merchant_read` on the API-key path.","x-required-scope":"merchant_read","parameters":[{"name":"active","in":"query","required":false,"description":"Filter by active flag (\"1\"/\"true\" or \"0\"/\"false\").","schema":{"type":"string","enum":["1","0","true","false"]}},{"name":"q","in":"query","required":false,"description":"Substring search over slug, name and description.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size (1–100, default 50).","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","required":false,"description":"Pagination offset (default 0).","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Product list.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductListResponse"},"examples":{"list":{"value":{"products":[{"id":"prd_abc123","slug":"ebook-depix","name":"Ebook DePix","amount":700,"description":null,"image_url":null,"active":1,"is_live":1,"expires_in":1200,"created_at":"2026-07-01 12:00:00","position":null,"total_checkouts":3,"completed_checkouts":2,"completed_amount":1400}],"limit":50,"offset":0}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"The API key lacks the `merchant_read` scope required by this operation. May also be `account_blocked`, or an operation-specific 403 — see the error catalog.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"response":{"errorMessage":"Esta API key não tem permissão para esta operação."},"error":{"code":"insufficient_scope","message":"This session does not have the scope required for this operation.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"required_scope":"merchant_read"}}}}}}}},"429":{"description":"Rate limited. Beyond the endpoint's own limit when set (`rate_limited`), API-key calls are also bounded by the shared per-merchant budget (`merchant_rate_limited`, default 30 req/min across all endpoints) and by the key's own rate limit when configured (`rate_limited`). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"merchant_rate_limited":{"value":{"response":{"errorMessage":"Rate limit do merchant excedido."},"error":{"code":"merchant_rate_limited","message":"Merchant rate limit exceeded.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":22,"docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}}}}},"/api/products/featured":{"post":{"tags":["products"],"operationId":"setFeaturedProducts","summary":"Set the pinned product order","description":"Reconciles the whole pinned set of the merchant's public page in one call: products in `productIds` are pinned in that order; every other product is unpinned. An empty array clears all pins. Requires scope `merchant_write` on the API-key path.","x-required-scope":"merchant_write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"The ordered pinned set.","required":["productIds"],"properties":{"productIds":{"type":"array","description":"Ordered product ids to pin (max 50, no duplicates). Empty array clears all pins.","items":{"type":"string","description":"Product id (prd_*)."},"maxItems":50}}},"examples":{"pin_two":{"value":{"productIds":["prd_abc123","prd_def456"]}}}}}},"responses":{"200":{"description":"Pinned set reconciled.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeaturedResponse"},"examples":{"ok":{"value":{"success":true,"featured":["prd_abc123","prd_def456"]}}}}}},"400":{"description":"productIds is not a valid list (type, duplicates, >50 items).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"validation_error":{"value":{"response":{"errorMessage":"productIds deve ser uma lista."},"error":{"code":"validation_error","message":"Invalid request. Check the fields and try again.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"field":"productIds"}}}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"The API key lacks the `merchant_write` scope required by this operation. May also be `account_blocked`, or an operation-specific 403 — see the error catalog.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"response":{"errorMessage":"Esta API key não tem permissão para esta operação."},"error":{"code":"insufficient_scope","message":"This session does not have the scope required for this operation.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"required_scope":"merchant_write"}}}}}}}},"404":{"description":"One or more ids do not belong to this merchant (in the current mode).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"value":{"response":{"errorMessage":"Um ou mais produtos não foram encontrados."},"error":{"code":"not_found","message":"Resource not found.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited. Beyond the endpoint's own limit when set (`rate_limited`), API-key calls are also bounded by the shared per-merchant budget (`merchant_rate_limited`, default 30 req/min across all endpoints) and by the key's own rate limit when configured (`rate_limited`). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"merchant_rate_limited":{"value":{"response":{"errorMessage":"Rate limit do merchant excedido."},"error":{"code":"merchant_rate_limited","message":"Merchant rate limit exceeded.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":22,"docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}}}}},"/api/products/{id}":{"get":{"tags":["products"],"operationId":"getProduct","summary":"Get a product","description":"Full product row with checkout aggregates. Requires scope `merchant_read` on the API-key path.","x-required-scope":"merchant_read","parameters":[{"name":"id","in":"path","required":true,"description":"Product id (prd_*).","schema":{"type":"string"}}],"responses":{"200":{"description":"Product detail.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductGetResponse"},"examples":{"detail":{"value":{"product":{"id":"prd_abc123","merchant_id":"mrc_1","slug":"ebook-depix","name":"Ebook DePix","amount":700,"description":null,"image_url":null,"callback_url":null,"redirect_url":null,"metadata":null,"expires_in":1200,"active":1,"is_live":1,"position":null,"created_at":"2026-07-01 12:00:00","updated_at":"2026-07-01 12:00:00"},"stats":{"total":3,"completed":2,"pending":1,"completed_amount":1400}}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"The API key lacks the `merchant_read` scope required by this operation. May also be `account_blocked`, or an operation-specific 403 — see the error catalog.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"response":{"errorMessage":"Esta API key não tem permissão para esta operação."},"error":{"code":"insufficient_scope","message":"This session does not have the scope required for this operation.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"required_scope":"merchant_read"}}}}}}}},"404":{"description":"Product not found — includes rows owned by another account (ownership is never disclosed).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"value":{"response":{"errorMessage":"Product não encontrado."},"error":{"code":"not_found","message":"Resource not found.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited. Beyond the endpoint's own limit when set (`rate_limited`), API-key calls are also bounded by the shared per-merchant budget (`merchant_rate_limited`, default 30 req/min across all endpoints) and by the key's own rate limit when configured (`rate_limited`). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"merchant_rate_limited":{"value":{"response":{"errorMessage":"Rate limit do merchant excedido."},"error":{"code":"merchant_rate_limited","message":"Merchant rate limit exceeded.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":22,"docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}}}},"patch":{"tags":["products"],"operationId":"updateProduct","summary":"Update a product","description":"Partial update — only provided fields change. Requires scope `merchant_write` on the API-key path.","x-required-scope":"merchant_write","parameters":[{"name":"id","in":"path","required":true,"description":"Product id (prd_*).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductUpdateRequest"},"examples":{"price_change":{"value":{"amount":900}}}}}},"responses":{"200":{"description":"Updated.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"},"examples":{"ok":{"value":{"success":true}}}}}},"400":{"description":"Invalid field value or empty update.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"validation_error":{"value":{"response":{"errorMessage":"Nenhum campo para atualizar."},"error":{"code":"validation_error","message":"Invalid request. Check the fields and try again.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"The API key lacks the `merchant_write` scope required by this operation. May also be `account_blocked`, or an operation-specific 403 — see the error catalog.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"response":{"errorMessage":"Esta API key não tem permissão para esta operação."},"error":{"code":"insufficient_scope","message":"This session does not have the scope required for this operation.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"required_scope":"merchant_write"}}}}}}}},"404":{"description":"Product not found — includes rows owned by another account (ownership is never disclosed).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"value":{"response":{"errorMessage":"Product não encontrado."},"error":{"code":"not_found","message":"Resource not found.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"409":{"description":"New slug already used by another product.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"conflict":{"value":{"response":{"errorMessage":"Já existe um produto com este slug."},"error":{"code":"conflict","message":"The request conflicts with the current state of the resource.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited. Beyond the endpoint's own limit when set (`rate_limited`), API-key calls are also bounded by the shared per-merchant budget (`merchant_rate_limited`, default 30 req/min across all endpoints) and by the key's own rate limit when configured (`rate_limited`). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"merchant_rate_limited":{"value":{"response":{"errorMessage":"Rate limit do merchant excedido."},"error":{"code":"merchant_rate_limited","message":"Merchant rate limit exceeded.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":22,"docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}}}}},"/api/products/{id}/deactivate":{"post":{"tags":["products"],"operationId":"deactivateProduct","summary":"Deactivate a product","description":"Hides the product from the public page and blocks new checkouts. Requires scope `merchant_write` on the API-key path.","x-required-scope":"merchant_write","parameters":[{"name":"id","in":"path","required":true,"description":"Product id (prd_*).","schema":{"type":"string"}}],"responses":{"200":{"description":"Deactivated.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"},"examples":{"ok":{"value":{"success":true}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"The API key lacks the `merchant_write` scope required by this operation. May also be `account_blocked`, or an operation-specific 403 — see the error catalog.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"response":{"errorMessage":"Esta API key não tem permissão para esta operação."},"error":{"code":"insufficient_scope","message":"This session does not have the scope required for this operation.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"required_scope":"merchant_write"}}}}}}}},"404":{"description":"Product not found — includes rows owned by another account (ownership is never disclosed).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"value":{"response":{"errorMessage":"Product não encontrado."},"error":{"code":"not_found","message":"Resource not found.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited. Beyond the endpoint's own limit when set (`rate_limited`), API-key calls are also bounded by the shared per-merchant budget (`merchant_rate_limited`, default 30 req/min across all endpoints) and by the key's own rate limit when configured (`rate_limited`). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"merchant_rate_limited":{"value":{"response":{"errorMessage":"Rate limit do merchant excedido."},"error":{"code":"merchant_rate_limited","message":"Merchant rate limit exceeded.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":22,"docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}}}}},"/api/products/{id}/activate":{"post":{"tags":["products"],"operationId":"activateProduct","summary":"Reactivate a product","description":"Makes the product purchasable again. Requires scope `merchant_write` on the API-key path.","x-required-scope":"merchant_write","parameters":[{"name":"id","in":"path","required":true,"description":"Product id (prd_*).","schema":{"type":"string"}}],"responses":{"200":{"description":"Activated.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"},"examples":{"ok":{"value":{"success":true}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"The API key lacks the `merchant_write` scope required by this operation. May also be `account_blocked`, or an operation-specific 403 — see the error catalog.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"response":{"errorMessage":"Esta API key não tem permissão para esta operação."},"error":{"code":"insufficient_scope","message":"This session does not have the scope required for this operation.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"required_scope":"merchant_write"}}}}}}}},"404":{"description":"Product not found — includes rows owned by another account (ownership is never disclosed).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"value":{"response":{"errorMessage":"Product não encontrado."},"error":{"code":"not_found","message":"Resource not found.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited. Beyond the endpoint's own limit when set (`rate_limited`), API-key calls are also bounded by the shared per-merchant budget (`merchant_rate_limited`, default 30 req/min across all endpoints) and by the key's own rate limit when configured (`rate_limited`). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"merchant_rate_limited":{"value":{"response":{"errorMessage":"Rate limit do merchant excedido."},"error":{"code":"merchant_rate_limited","message":"Merchant rate limit exceeded.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":22,"docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}}}}},"/api/products/{id}/checkouts":{"get":{"tags":["products"],"operationId":"listProductCheckouts","summary":"List a product's checkouts","description":"Paginated checkouts created from one product. Requires scope `merchant_read` on the API-key path.","x-required-scope":"merchant_read","parameters":[{"name":"id","in":"path","required":true,"description":"Product id (prd_*).","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by status.","schema":{"$ref":"#/components/schemas/CheckoutStatus"}},{"name":"limit","in":"query","required":false,"description":"Page size (1–100, default 50).","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","required":false,"description":"Pagination offset (default 0).","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Product checkouts.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductCheckoutsResponse"},"examples":{"list":{"value":{"checkouts":[{"id":"chk_abc123","status":"completed","amount":700,"description":"Ebook DePix","created_at":"2026-07-01 12:00:00","expires_at":"2026-07-01 12:20:00","processing_at":"2026-07-01 12:01:00","completed_at":"2026-07-01 12:02:00"}],"stats":{"total":1,"completed":1,"completed_amount":700},"limit":50,"offset":0}}}}}},"400":{"description":"Invalid status filter.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"validation_error":{"value":{"response":{"errorMessage":"Status inválido."},"error":{"code":"validation_error","message":"Invalid request. Check the fields and try again.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"field":"status"}}}}}}}},"401":{"description":"Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid_api_key":{"value":{"response":{"errorMessage":"API key inválida, revogada ou expirada."},"error":{"code":"invalid_api_key","message":"Invalid, revoked or expired API key.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"invalid_token":{"value":{"response":{"errorMessage":"Token inválido ou ausente. Faça login para continuar."},"error":{"code":"invalid_token","message":"Invalid or expired token, or missing Authorization header.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"The API key lacks the `merchant_read` scope required by this operation. May also be `account_blocked`, or an operation-specific 403 — see the error catalog.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"insufficient_scope":{"value":{"response":{"errorMessage":"Esta API key não tem permissão para esta operação."},"error":{"code":"insufficient_scope","message":"This session does not have the scope required for this operation.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"required_scope":"merchant_read"}}}}}}}},"404":{"description":"Product not found — includes rows owned by another account (ownership is never disclosed).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"value":{"response":{"errorMessage":"Product não encontrado."},"error":{"code":"not_found","message":"Resource not found.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited. Beyond the endpoint's own limit when set (`rate_limited`), API-key calls are also bounded by the shared per-merchant budget (`merchant_rate_limited`, default 30 req/min across all endpoints) and by the key's own rate limit when configured (`rate_limited`). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"merchant_rate_limited":{"value":{"response":{"errorMessage":"Rate limit do merchant excedido."},"error":{"code":"merchant_rate_limited","message":"Merchant rate limit exceeded.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":22,"docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}}}}},"/api/products/{id}/public":{"get":{"tags":["public"],"operationId":"getPublicProduct","summary":"Public product data","description":"Public (unauthenticated) product read — only live, active products of active merchants.","security":[],"parameters":[{"name":"id","in":"path","required":true,"description":"Product id (prd_*).","schema":{"type":"string"}}],"responses":{"200":{"description":"Public product.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductPublicResponse"},"examples":{"product":{"value":{"id":"prd_abc123","slug":"ebook-depix","amount":700,"description":null,"image_url":null,"merchant_name":"Loja Teste","merchant_logo":null,"username":"loja-teste","merchant_slug":"loja-teste","is_test":false}}}}}},"404":{"description":"Product not found — includes rows owned by another account (ownership is never disclosed).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"value":{"response":{"errorMessage":"Product não encontrado."},"error":{"code":"not_found","message":"Resource not found.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}}}}},"/api/products/{id}/checkout":{"post":{"tags":["public"],"operationId":"createProductCheckout","summary":"Create a checkout from a product (public)","description":"Public (unauthenticated) checkout creation from a live, active product — the flow behind the \"buy\" button of product pages. Optional body: payer metadata and payer_tax_number.","security":[],"parameters":[{"name":"id","in":"path","required":true,"description":"Product id (prd_*).","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","description":"Optional payer-provided fields merged into the checkout.","properties":{"metadata":{"type":"object","description":"Extra metadata merged over the product's metadata (max 4KB combined)."},"payer_tax_number":{"type":"string","description":"CPF/CNPJ of the payer. Required — omitting it returns 400 `tax_number_required`."}}},"examples":{"with_tax":{"value":{"payer_tax_number":"52998224725"}}}}}},"responses":{"201":{"description":"Checkout created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicProductCheckoutResponse"},"examples":{"created":{"value":{"id":"chk_pub123","status":"pending","amount":700,"description":null,"expires_at":"2026-07-01 12:20:00","is_live":true,"payment_url":"https://pay.depixapp.com/chk_pub123","pix":{"qr_code":"00020126580014br.gov.bcb.pix…"}}}}}}},"400":{"description":"Invalid metadata or missing payer tax number.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"tax_number_required":{"value":{"response":{"errorMessage":"Informe o CPF ou CNPJ do pagador."},"error":{"code":"tax_number_required","message":"The payer's CPF/CNPJ (payer_tax_number) is required.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"404":{"description":"Product not found — includes rows owned by another account (ownership is never disclosed).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"value":{"response":{"errorMessage":"Product não encontrado."},"error":{"code":"not_found","message":"Resource not found.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited, or too many QRs for the same payer CPF/CNPJ (`payer_velocity_limit`: max 2 per sliding 30-minute window, deposits + checkouts combined). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"payer_velocity_limit":{"value":{"response":{"errorMessage":"Muitas transações para este CPF/CNPJ em pouco tempo. Aguarde 18 minutos e tente novamente."},"error":{"code":"payer_velocity_limit","message":"Too many deposits for this payer CPF/CNPJ in a short period. Wait and try again.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":1080,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"window_minutes":30,"max_per_window":2}}}},"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}},"503":{"description":"Merchant temporarily unavailable to receive payments, or platform maintenance.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"service_unavailable":{"value":{"response":{"errorMessage":"Este lojista está temporariamente indisponível para receber pagamentos."},"error":{"code":"service_unavailable","message":"A dependency is unavailable. Try again shortly.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":30,"docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}}}}},"/api/merchants/{username}/public":{"get":{"tags":["public"],"operationId":"getPublicMerchant","summary":"Public merchant data","description":"Public (unauthenticated) merchant read — the storefront identity behind pay.depixapp.com/{merchant_slug}. Only active merchants are served; an unknown or deactivated slug is a 404. Rate limit: 30 requests/minute per IP. NOTE: the 404 body carries only the legacy `response.errorMessage` envelope (no machine-readable `error` object) — branch on the HTTP status code.","security":[],"parameters":[{"name":"username","in":"path","required":true,"description":"The merchant's public URL slug (`merchant_slug`). The path parameter is still named `username` for backwards compatibility.","schema":{"type":"string"}}],"responses":{"200":{"description":"Public merchant.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantPublicResponse"},"examples":{"merchant":{"value":{"business_name":"Loja Teste","logo_url":null,"username":"loja-teste","merchant_slug":"loja-teste"}}}}}},"404":{"description":"Unknown or inactive merchant. Legacy envelope only — no `error` object.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorEnvelope"},"examples":{"not_found":{"value":{"response":{"errorMessage":"Lojista não encontrado."}}}}}}},"429":{"description":"Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}}}}},"/api/merchants/{username}/checkout":{"post":{"tags":["public"],"operationId":"createMerchantCheckout","summary":"Create a checkout on a merchant storefront (public)","description":"Public (unauthenticated) checkout creation with a payer-chosen amount — the flow behind the \"pay\" button of a merchant's public page. Optionally carries a cart (`items`): every line is rebuilt from the merchant's catalog server-side and the request is rejected when the rebuilt total does not match `amount`. `callback_url`/`redirect_url` always come from the merchant's saved defaults and cannot be set here; the checkout is always live (never sandbox). Rate limit: 10 requests/minute per IP plus 60 checkouts/minute per merchant. NOTE: the 400/404/503-merchant bodies carry only the legacy `response.errorMessage` envelope (no machine-readable `error` object).","security":[],"parameters":[{"name":"username","in":"path","required":true,"description":"The merchant's public URL slug (`merchant_slug`). The path parameter is still named `username` for backwards compatibility.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantCheckoutRequest"},"examples":{"amount_only":{"summary":"Plain amount","value":{"amount":1500,"payer_tax_number":"52998224725"}},"cart":{"summary":"Cart of catalog products (amount must match the catalog total)","value":{"amount":2100,"payer_tax_number":"52998224725","items":[{"slug":"ebook-depix","qty":3}]}}}}}},"responses":{"201":{"description":"Checkout created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantCheckoutResponse"},"examples":{"created":{"value":{"id":"chk_mrc123","status":"pending","amount":1500,"description":null,"expires_at":"2026-07-01 12:20:00","is_live":true,"payment_url":"https://pay.depixapp.com/chk_mrc123","pix":{"qr_code":"00020126580014br.gov.bcb.pix…"}}}}}}},"400":{"description":"Validation failure (per-field details in `response.errors[]`), an invalid cart, or a cart whose rebuilt catalog total no longer matches `amount` (stale prices on an open page — reload and retry).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorEnvelope"},"examples":{"validation_error":{"value":{"response":{"errorMessage":"Dados inválidos.","errors":[{"field":"amount","message":"Obrigatório. Valor em centavos (integer)."}]}}},"stale_cart":{"value":{"response":{"errorMessage":"Os preços dos produtos foram atualizados. Atualize a página e tente novamente."}}},"unavailable_product":{"value":{"response":{"errorMessage":"Um dos produtos do carrinho não está mais disponível. Atualize a página e tente novamente."}}}}}}},"403":{"description":"The merchant is an agent account that cannot yet be paid by third parties — it has not graduated to full production (`graduation_pending`) or has no verified domain (`domain_required`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"graduation_pending":{"value":{"response":{"errorMessage":"This capability unlocks after the account graduates (settled deposits matured + clean gate)."},"error":{"code":"graduation_pending","message":"This capability unlocks after the account graduates (settled deposits matured + clean gate).","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"domain_required":{"value":{"response":{"errorMessage":"Receiving from third parties requires a verified domain. Prove one via POST /api/agents/verify-domain."},"error":{"code":"domain_required","message":"Receiving from third parties requires a verified domain. Prove one via POST /api/agents/verify-domain.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"404":{"description":"Unknown or unavailable merchant. Legacy envelope only — no `error` object.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyErrorEnvelope"},"examples":{"not_found":{"value":{"response":{"errorMessage":"Lojista não encontrado ou indisponível."}}}}}}},"429":{"description":"Rate limited — the per-IP window (10/min) or the per-merchant anonymous-creation cap (60/min, `details.scope` = \"anon-checkout\") — or too many QRs for the same payer CPF/CNPJ (`payer_velocity_limit`: max 2 per sliding 30-minute window, deposits + checkouts combined). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas cobranças criadas para este lojista agora há pouco. Tente novamente em instantes."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":24,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"anon-checkout"}}}},"payer_velocity_limit":{"value":{"response":{"errorMessage":"Muitas transações para este CPF/CNPJ em pouco tempo. Aguarde 18 minutos e tente novamente."},"error":{"code":"payer_velocity_limit","message":"Too many deposits for this payer CPF/CNPJ in a short period. Wait and try again.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":1080,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"window_minutes":30,"max_per_window":2}}}}}}}},"503":{"description":"The merchant is temporarily unable to receive payments (legacy envelope, no `error` object — the reason is deliberately generic to the paying customer), or the platform is in maintenance (`platform_shutdown`, dual envelope).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"description":"Either the dual envelope (platform maintenance) or the legacy-only envelope (merchant temporarily unavailable).","oneOf":[{"$ref":"#/components/schemas/ErrorEnvelope"},{"$ref":"#/components/schemas/LegacyErrorEnvelope"}]},"examples":{"merchant_unavailable":{"value":{"response":{"errorMessage":"Este lojista está temporariamente indisponível para receber pagamentos."}}},"platform_shutdown":{"value":{"response":{"errorMessage":"Plataforma em manutenção. Tente novamente em breve."},"error":{"code":"platform_shutdown","message":"Platform under maintenance. Try again soon.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":300,"docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}}}}},"/api/pay/{id}":{"get":{"tags":["public"],"operationId":"getPublicCheckout","summary":"Public checkout data","description":"Public (unauthenticated) checkout read — what the hosted checkout page polls. Terminal statuses are cached for 60 s. `pix` is present only while pending.","security":[],"parameters":[{"name":"id","in":"path","required":true,"description":"Checkout id (chk_*).","schema":{"type":"string"}}],"responses":{"200":{"description":"Public checkout state.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayCheckoutResponse"},"examples":{"pending":{"value":{"id":"chk_pub123","status":"pending","amount":700,"currency":"BRL","description":null,"image_url":null,"merchant_name":"Loja Teste","merchant_username":"loja-teste","merchant_slug":"loja-teste","remaining_seconds":583,"expires_at":"2026-07-01 12:20:00","redirect_url":null,"is_test":false,"pix":{"qr_code":"00020126580014br.gov.bcb.pix…"}}}}}}},"404":{"description":"Checkout not found — includes rows owned by another account (ownership is never disclosed).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"value":{"response":{"errorMessage":"Checkout não encontrado."},"error":{"code":"not_found","message":"Resource not found.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}}}}},"/api/pay/{id}/simulate":{"post":{"tags":["public"],"operationId":"simulatePublicCheckoutPayment","summary":"Simulate payment on a sandbox checkout (public)","description":"Public simulate used by the hosted sandbox checkout page. Only sandbox (is_live=0) checkouts in pending status; live checkouts are 403 sandbox_only.","security":[],"parameters":[{"name":"id","in":"path","required":true,"description":"Sandbox checkout id (chk_*).","schema":{"type":"string"}}],"responses":{"200":{"description":"Simulated as paid.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"},"examples":{"ok":{"value":{"success":true}}}}}},"403":{"description":"Live checkout — simulation is sandbox-only.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"sandbox_only":{"value":{"response":{"errorMessage":"Simulação disponível apenas em modo teste."},"error":{"code":"sandbox_only","message":"This operation is only available on sandbox (test mode) resources.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"404":{"description":"Checkout not found — includes rows owned by another account (ownership is never disclosed).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"value":{"response":{"errorMessage":"Checkout não encontrado."},"error":{"code":"not_found","message":"Resource not found.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"409":{"description":"The checkout is not pending / cannot transition.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"conflict":{"value":{"response":{"errorMessage":"Este checkout não está pendente."},"error":{"code":"conflict","message":"The request conflicts with the current state of the resource.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}}}}},"/api/agents/register":{"post":{"tags":["agents"],"operationId":"registerAgent","summary":"Agent self-onboarding (atomic)","description":"Creates an agent account + merchant + sandbox key + starter live key in one atomic transaction. Authentication is the agent keypair scheme via signed headers (X-Agent-Public-Key / X-Agent-Timestamp / X-Agent-Nonce / X-Agent-Signature — Ed25519 over the canonical string `depix-agent-auth:v1\\napi.depixapp.com\\n{METHOD}\\n{PATH}\\n{timestamp}\\n{nonce}\\n{sha256hex(canonical-json-body)}` — the body hash is over the compact JSON serialization), NOT a Bearer key — plus the REQUIRED operator_token anti-farm anchor. Key plaintexts and the webhook secret are returned ONLY here.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRegisterRequest"},"examples":{"register":{"value":{"name":"Acme Butler","operator_token":"op_kJ9…","operator_email":"ops@acme.com","liquid_address":"lq1qqw508d6qejxtdg4y5r3zarvary0c5xw7k…","default_callback_url":"https://hooks.acme.com/depix"}}}}}},"responses":{"201":{"description":"Agent created — store the key plaintexts and webhook secret now; they are never shown again.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRegisterResponse"},"examples":{"created":{"value":{"response":{"agent":{"username":"acme_butler","public_key":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","account_type":"agent"},"merchant":{"id":"mrc_x1","merchant_slug":"acme_butler","liquid_address":"lq1qq…","webhook_secret":"whsec_…"},"keys":{"test":{"id":"k1","key":"sk_test_…","scopes":"merchant_read merchant_write wallet_read wallet_write"},"live_starter":{"id":"k2","key":"sk_live_…","scopes":"wallet_read wallet_write","per_tx_limit_cents":10000,"daily_limit_cents":50000,"starter":true}},"graduation":{"required_settled_deposits":5,"maturation_days":15},"pacing":{"first_deposit_max_cents":2000,"unverified_per_tx_max_cents":10000,"unverified_lifetime_max_cents":50000,"inter_deposit_delay_hours":24,"payer_velocity":{"max_per_window":2,"window_minutes":30},"verified_per_tx_deposit_max_cents":300000,"verified_per_tx_withdraw_max_cents":600000}}}}}}}},"400":{"description":"Invalid field (validation_error with details.field).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"bad_name":{"value":{"response":{"errorMessage":"name deve ter entre 2 e 100 caracteres."},"error":{"code":"validation_error","message":"Invalid request. Check the fields and try again.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"field":"name"}}}}}}}},"401":{"description":"Signature chain failed (agent_invalid_signature / agent_signature_expired with details.server_time / agent_replay_detected) or unknown operator token (invalid_operator_token).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"expired":{"value":{"response":{"errorMessage":"Agent request timestamp is outside the allowed window. Re-sync your clock and retry."},"error":{"code":"agent_signature_expired","message":"Agent request timestamp is outside the allowed window. Re-sync your clock and retry.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"server_time":1784232266}}}},"bad_operator":{"value":{"response":{"errorMessage":"Operator token is missing, malformed or unknown. Connect an operator to obtain one."},"error":{"code":"invalid_operator_token","message":"Operator token is missing, malformed or unknown. Connect an operator to obtain one.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"Revoked operator token (operator_token_revoked) or a blocked public key (registration_blocked).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"revoked":{"value":{"response":{"errorMessage":"This operator token has been revoked. Connect the operator again to obtain a new one."},"error":{"code":"operator_token_revoked","message":"This operator token has been revoked. Connect the operator again to obtain a new one.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"409":{"description":"Public key already registered (agent_pubkey_exists) or explicit username in use (username_taken).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"pubkey":{"value":{"response":{"errorMessage":"This public key is already registered to an agent account."},"error":{"code":"agent_pubkey_exists","message":"This public key is already registered to an agent account.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}},"503":{"description":"Nonce anti-replay store unavailable — the signature guard fails CLOSED; retry.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"replay_store_down":{"value":{"response":{"errorMessage":"A dependency is unavailable. Try again shortly."},"error":{"code":"service_unavailable","message":"A dependency is unavailable. Try again shortly.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":5,"docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}}}}},"/api/agents/domain-tlds":{"get":{"tags":["agents"],"operationId":"listAgentDomainTlds","summary":"TLD allowlist for domain verification","description":"Public discovery of the TLDs POST /api/agents/verify-domain accepts — avoids trial-and-error 422s.","security":[],"responses":{"200":{"description":"The current allowlist.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainTldsResponse"},"examples":{"list":{"value":{"allowed_tlds":[".com",".net",".io",".com.br"]}}}}}},"429":{"description":"Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}}}}},"/api/agents/verify-domain":{"post":{"tags":["agents"],"operationId":"verifyAgentDomain","summary":"Prove domain control (two-phase DNS TXT)","description":"Unlocks receiving from third parties. Authentication is the agent keypair scheme (signed X-Agent-* headers), not a Bearer key. Phase 1 ({domain}) returns the TXT challenge to publish at _depix-verify.<domain>; phase 2 ({domain, confirm: true}) resolves it and records agents.verified_domain (the registrable eTLD+1). The challenge value is stable — re-fetch it any time.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyDomainRequest"},"examples":{"phase1":{"value":{"domain":"acme.com"}},"phase2":{"value":{"domain":"acme.com","confirm":true}}}}}},"responses":{"200":{"description":"Phase-1 challenge or phase-2 confirmation.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyDomainResponse"},"examples":{"challenge":{"value":{"record_name":"_depix-verify.acme.com","record_value":"depix-verify=3f9a…"}},"confirmed":{"value":{"verified_domain":"acme.com"}}}}}},"400":{"description":"Malformed domain.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"bad_domain":{"value":{"response":{"errorMessage":"domain inválido."},"error":{"code":"validation_error","message":"Invalid request. Check the fields and try again.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"field":"domain"}}}}}}}},"401":{"description":"Signature chain failed or the public key is not a registered agent (agent_unknown_key).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unknown":{"value":{"response":{"errorMessage":"Agent public key is not registered."},"error":{"code":"agent_unknown_key","message":"Agent public key is not registered.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"Account blocked.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"blocked":{"value":{"response":{"errorMessage":"Conta suspensa."},"error":{"code":"account_blocked","message":"This account is suspended.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"422":{"description":"TLD outside the allowlist (domain_tld_not_allowed with details.allowed_tlds), free-subdomain host (domain_free_host), or the TXT record is missing/mismatched (domain_txt_not_found).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"tld":{"value":{"response":{"errorMessage":"This domain's TLD is not on the accepted list. See details.allowed_tlds or GET /api/agents/domain-tlds."},"error":{"code":"domain_tld_not_allowed","message":"This domain's TLD is not on the accepted list. See details.allowed_tlds or GET /api/agents/domain-tlds.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"txt":{"value":{"response":{"errorMessage":"The DNS TXT challenge was not found or does not match. Create the record and retry after propagation."},"error":{"code":"domain_txt_not_found","message":"The DNS TXT challenge was not found or does not match. Create the record and retry after propagation.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}},"503":{"description":"Nonce anti-replay store unavailable — the signature guard fails CLOSED; retry.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"replay_store_down":{"value":{"response":{"errorMessage":"A dependency is unavailable. Try again shortly."},"error":{"code":"service_unavailable","message":"A dependency is unavailable. Try again shortly.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":5,"docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}}}}},"/api/agents/keys":{"post":{"tags":["agents"],"operationId":"createAgentKey","summary":"Mint an agent API key","description":"Mints an API key for the agent's own merchant. Auth is the agent keypair signature — the per-request proof-of-possession IS the step-up (no password). A LIVE key requires graduation (403 graduation_pending); a merchant_* scope requires a verified domain (403 domain_required); wallet_write keys get mandatory limits. Rejected when the merchant is suspended (403 account_suspended). Plaintext is returned ONCE.","security":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentKeyCreateRequest"},"examples":{"live_wallet":{"value":{"live":true,"scopes":["wallet_read","wallet_write"],"label":"prod payouts"}}}}}},"responses":{"201":{"description":"Key minted — store the plaintext now; it is never shown again.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentKeyCreateResponse"},"examples":{"created":{"value":{"response":{"id":"k_1","key":"sk_live_…","prefix":"sk_live_","is_live":true,"scopes":"wallet_read wallet_write","per_tx_limit_cents":10000,"daily_limit_cents":50000}}}}}}},"400":{"description":"Invalid scopes/label/limits, or the 5-key cap for this kind was reached.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"bad_scopes":{"value":{"response":{"errorMessage":"Campo \"scopes\" inválido."},"error":{"code":"validation_error","message":"Invalid request. Check the fields and try again.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"field":"scopes"}}}}}}}},"401":{"description":"Signature chain failed or unknown agent key.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unknown":{"value":{"response":{"errorMessage":"Agent public key is not registered."},"error":{"code":"agent_unknown_key","message":"Agent public key is not registered.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"Blocked (account_blocked), suspended (account_suspended), not graduated for a live key (graduation_pending), or missing a verified domain for a merchant_* scope (domain_required).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"graduation":{"value":{"response":{"errorMessage":"This capability unlocks after the account graduates (settled deposits matured + clean gate)."},"error":{"code":"graduation_pending","message":"This capability unlocks after the account graduates (settled deposits matured + clean gate).","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"domain":{"value":{"response":{"errorMessage":"Receiving from third parties requires a verified domain. Prove one via POST /api/agents/verify-domain."},"error":{"code":"domain_required","message":"Receiving from third parties requires a verified domain. Prove one via POST /api/agents/verify-domain.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}},"503":{"description":"Nonce anti-replay store unavailable (fail-CLOSED) OR the agent program is globally disabled (agents_disabled) — retry later.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"replay_store_down":{"value":{"response":{"errorMessage":"A dependency is unavailable. Try again shortly."},"error":{"code":"service_unavailable","message":"A dependency is unavailable. Try again shortly.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":5,"docs_url":"https://depixapp.com/docs/en/#errors"}}},"agents_frozen":{"value":{"response":{"errorMessage":"The agent program is temporarily disabled. Try again later."},"error":{"code":"agents_disabled","message":"The agent program is temporarily disabled. Try again later.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}}}}},"/api/agents/keys/revoke":{"post":{"tags":["agents"],"operationId":"revokeAgentKey","summary":"Revoke an agent API key","description":"Revokes one of the agent's own keys. Auth: agent keypair signature. Rejected when the merchant is suspended.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentKeyRevokeRequest"},"examples":{"revoke":{"value":{"id":"k_1"}}}}}},"responses":{"200":{"description":"Revoked (idempotent).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentKeyRevokeResponse"},"examples":{"done":{"value":{"response":{"id":"k_1","revoked":true}}}}}}},"400":{"description":"Missing key id.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"bad":{"value":{"response":{"errorMessage":"id da chave obrigatório."},"error":{"code":"validation_error","message":"Invalid request. Check the fields and try again.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"field":"id"}}}}}}}},"401":{"description":"Signature chain failed or unknown agent key.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unknown":{"value":{"response":{"errorMessage":"Agent public key is not registered."},"error":{"code":"agent_unknown_key","message":"Agent public key is not registered.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"Blocked or suspended.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"suspended":{"value":{"response":{"errorMessage":"This agent account is currently paused."},"error":{"code":"account_suspended","message":"This agent account is currently paused.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"404":{"description":"Key not found for this agent.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"nf":{"value":{"response":{"errorMessage":"Chave não encontrada."},"error":{"code":"not_found","message":"Resource not found.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}},"503":{"description":"Nonce store unavailable (fail-CLOSED) OR the agent program is globally disabled (agents_disabled).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"down":{"value":{"response":{"errorMessage":"A dependency is unavailable. Try again shortly."},"error":{"code":"service_unavailable","message":"A dependency is unavailable. Try again shortly.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":5,"docs_url":"https://depixapp.com/docs/en/#errors"}}},"agents_frozen":{"value":{"response":{"errorMessage":"The agent program is temporarily disabled. Try again later."},"error":{"code":"agents_disabled","message":"The agent program is temporarily disabled. Try again later.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}}}}},"/api/agents/webhook-secret":{"post":{"tags":["agents"],"operationId":"rotateAgentWebhookSecret","summary":"Rotate the agent merchant webhook secret","description":"Rotates the merchant webhook signing secret and returns the new one ONCE. The previous secret is invalidated immediately. Auth: agent keypair signature; rejected when suspended.","security":[],"responses":{"200":{"description":"New secret — store it now; it is never shown again.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentWebhookSecretResponse"},"examples":{"rotated":{"value":{"response":{"webhook_secret":"whsec_…"}}}}}}},"401":{"description":"Signature chain failed or unknown agent key.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unknown":{"value":{"response":{"errorMessage":"Agent public key is not registered."},"error":{"code":"agent_unknown_key","message":"Agent public key is not registered.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"Blocked or suspended.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"suspended":{"value":{"response":{"errorMessage":"This agent account is currently paused."},"error":{"code":"account_suspended","message":"This agent account is currently paused.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}},"503":{"description":"Nonce store unavailable (fail-CLOSED) OR the agent program is globally disabled (agents_disabled).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"down":{"value":{"response":{"errorMessage":"A dependency is unavailable. Try again shortly."},"error":{"code":"service_unavailable","message":"A dependency is unavailable. Try again shortly.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":5,"docs_url":"https://depixapp.com/docs/en/#errors"}}},"agents_frozen":{"value":{"response":{"errorMessage":"The agent program is temporarily disabled. Try again later."},"error":{"code":"agents_disabled","message":"The agent program is temporarily disabled. Try again later.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}}}}},"/api/agents/status":{"get":{"tags":["agents"],"operationId":"getAgentStatus","summary":"Agent account status + progress","description":"Minimal consumable progress: account_status, settled deposit count, graduation state, and the account's keys. Auth: agent keypair signature. OPEN even when suspended (so the agent can read the reason). Never exposes maturation dates or review specifics.","security":[],"responses":{"200":{"description":"Current status.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentStatusResponse"},"examples":{"active":{"value":{"response":{"account_status":"active","settled_personal_deposits":3,"graduated":false,"graduation":{"blocked_on":null},"keys":[{"id":"k_1","prefix":"sk_live_","is_live":true,"starter":true,"scopes":"wallet_read wallet_write","revoked_at":null}]}}}}}}},"401":{"description":"Signature chain failed or unknown agent key.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unknown":{"value":{"response":{"errorMessage":"Agent public key is not registered."},"error":{"code":"agent_unknown_key","message":"Agent public key is not registered.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"Blocked (a suspended account still gets 200 with account_status \"suspended\").","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"blocked":{"value":{"response":{"errorMessage":"Conta suspensa."},"error":{"code":"account_blocked","message":"This account is suspended.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}},"503":{"description":"Nonce store unavailable (fail-CLOSED) OR the agent program is globally disabled (agents_disabled).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"down":{"value":{"response":{"errorMessage":"A dependency is unavailable. Try again shortly."},"error":{"code":"service_unavailable","message":"A dependency is unavailable. Try again shortly.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":5,"docs_url":"https://depixapp.com/docs/en/#errors"}}},"agents_frozen":{"value":{"response":{"errorMessage":"The agent program is temporarily disabled. Try again later."},"error":{"code":"agents_disabled","message":"The agent program is temporarily disabled. Try again later.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}}}}},"/api/agents/webhook-logs":{"get":{"tags":["agents"],"operationId":"listAgentWebhookLogs","summary":"List webhook delivery logs","description":"The 50 most recent delivery attempts of checkout.*, deposit.* and withdraw.* events to this account's callback URLs, newest first — the agent-side audit of what was delivered, retried or failed. Bodies are omitted in the list; fetch one log by id for the payloads. Auth: agent keypair signature. Requires an ACTIVE merchant profile (a suspended account gets 403).","security":[],"responses":{"200":{"description":"Delivery attempts, newest first.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookLogListResponse"},"examples":{"logs":{"value":{"logs":[{"id":"wlog_1","checkout_id":"chk_abc123","event":"checkout.completed","url":"https://agent.example.com/hook","status_code":200,"error":null,"attempt":1,"sent_at":"2026-07-22 12:00:00"},{"id":"wlog_2","checkout_id":null,"event":"deposit.depix_sent","url":"https://agent.example.com/hook","status_code":null,"error":"fetch timeout","attempt":2,"sent_at":"2026-07-22 11:58:00"}]}},"empty":{"value":{"logs":[]}}}}}},"401":{"description":"Signature chain failed or unknown agent key.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unknown":{"value":{"response":{"errorMessage":"Agent public key is not registered."},"error":{"code":"agent_unknown_key","message":"Agent public key is not registered.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"Blocked, or the account has no ACTIVE merchant profile.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"no_merchant":{"value":{"response":{"errorMessage":"Você não possui conta de lojista."},"error":{"code":"merchant_required","message":"A merchant profile is required for this operation.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"blocked":{"value":{"response":{"errorMessage":"Conta suspensa."},"error":{"code":"account_blocked","message":"This account is suspended.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}},"503":{"description":"Nonce store unavailable (fail-CLOSED) OR the agent program is globally disabled (agents_disabled).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"down":{"value":{"response":{"errorMessage":"A dependency is unavailable. Try again shortly."},"error":{"code":"service_unavailable","message":"A dependency is unavailable. Try again shortly.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":5,"docs_url":"https://depixapp.com/docs/en/#errors"}}},"agents_frozen":{"value":{"response":{"errorMessage":"The agent program is temporarily disabled. Try again later."},"error":{"code":"agents_disabled","message":"The agent program is temporarily disabled. Try again later.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}}}}},"/api/agents/webhook-logs/{id}":{"get":{"tags":["agents"],"operationId":"getAgentWebhookLog","summary":"Get one webhook delivery log","description":"Full detail of one delivery attempt, including the signed request payload sent and the response body received — enough to replay signature verification on the receiver side. Ownership enforced: another account's log answers 404. Auth: agent keypair signature.","security":[],"parameters":[{"name":"id","in":"path","required":true,"description":"Delivery log id (from the list endpoint).","schema":{"type":"string"}}],"responses":{"200":{"description":"Full delivery detail.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookLogDetailResponse"},"examples":{"delivered":{"value":{"log":{"id":"wlog_1","checkout_id":null,"merchant_id":"mrc_1","url":"https://agent.example.com/hook","event":"deposit.depix_sent","status_code":200,"request_body":"{\"event\":\"deposit.depix_sent\",\"data\":{\"id\":\"qr-id-456\",\"type\":\"deposit\",\"amount_cents\":5000,\"status\":\"depix_sent\",\"created_at\":\"2026-07-22 11:00:00\",\"updated_at\":\"2026-07-22 12:00:00\",\"rejection_reasons\":[],\"event_id\":\"evt_1\"}}","response_body":"{\"ok\":true}","error":null,"attempt":1,"next_retry_at":null,"sent_at":"2026-07-22 12:00:00"}}}}}}},"401":{"description":"Signature chain failed or unknown agent key.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unknown":{"value":{"response":{"errorMessage":"Agent public key is not registered."},"error":{"code":"agent_unknown_key","message":"Agent public key is not registered.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"403":{"description":"Blocked, or the account has no ACTIVE merchant profile.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"no_merchant":{"value":{"response":{"errorMessage":"Você não possui conta de lojista."},"error":{"code":"merchant_required","message":"A merchant profile is required for this operation.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"blocked":{"value":{"response":{"errorMessage":"Conta suspensa."},"error":{"code":"account_blocked","message":"This account is suspended.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"404":{"description":"Log not found — includes rows owned by another account (ownership is never disclosed).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"not_found":{"value":{"response":{"errorMessage":"Log não encontrado."},"error":{"code":"not_found","message":"Resource not found.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"429":{"description":"Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}},"503":{"description":"Nonce store unavailable (fail-CLOSED) OR the agent program is globally disabled (agents_disabled).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"down":{"value":{"response":{"errorMessage":"A dependency is unavailable. Try again shortly."},"error":{"code":"service_unavailable","message":"A dependency is unavailable. Try again shortly.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":5,"docs_url":"https://depixapp.com/docs/en/#errors"}}},"agents_frozen":{"value":{"response":{"errorMessage":"The agent program is temporarily disabled. Try again later."},"error":{"code":"agents_disabled","message":"The agent program is temporarily disabled. Try again later.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}}}}},"/api/health":{"get":{"tags":["meta"],"operationId":"getHealth","summary":"Health check","description":"Dependency health. Contract: HTTP 200 = healthy, HTTP 503 = degraded (branch on the status code).","security":[],"responses":{"200":{"description":"Healthy.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"},"examples":{"ok":{"value":{"status":"ok","turso":true,"redis":true,"schema":true,"timestamp":"2026-07-01T12:00:00.000Z"}}}}}},"503":{"description":"Degraded — the body says which dependency failed.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"},"examples":{"degraded":{"value":{"status":"degraded","turso":true,"redis":false,"schema":true,"timestamp":"2026-07-01T12:00:00.000Z"}}}}}}}}},"/openapi.json":{"get":{"tags":["meta"],"operationId":"getOpenapiDocument","summary":"This OpenAPI document","description":"Serves this OpenAPI 3.1 document (Cache-Control: public, max-age=300).","security":[],"responses":{"200":{"description":"The OpenAPI 3.1 document.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"type":"object","description":"This OpenAPI 3.1 document."},"examples":{"document":{"summary":"Truncated illustration","value":{"openapi":"3.1.0","info":{"title":"DePix API","version":"0.1.0"}}}}}}},"429":{"description":"Rate limited (per-IP, per-key or per-merchant window). Retry after `retry_after` seconds (also in the Retry-After header).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"rate_limited":{"value":{"response":{"errorMessage":"Muitas requisições. Tente novamente em 1 minuto."},"error":{"code":"rate_limited","message":"Too many requests for this scope.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":37,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"deposit"}}}}}}}}}}}},"webhooks":{"deposit.pending":{"post":{"summary":"Deposit transitioned to pending","description":"Deposit awaiting Pix payment (initial state). Creation does not emit a webhook; this event fires only on a reversal back to this state. Fires ONLY for operations attributed to an API key (human/SPA operations never dispatch) and only when the merchant has a default callback URL configured. Sandbox (sk_test_) operations create no rows, so they never fire webhooks. Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the deposit.pending event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["deposit.pending"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/DepositWebhookData"}}},"examples":{"deposit_pending":{"value":{"event":"deposit.pending","data":{"id":"qr-id-456","type":"deposit","amount_cents":5000,"status":"pending","created_at":"2026-07-01 12:00:00","updated_at":"2026-07-01 12:00:00","rejection_reasons":[],"event_id":"evt_9f8e7d6c5b4a"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"deposit.under_review":{"post":{"summary":"Deposit transitioned to under_review","description":"Sent when a deposit created via API key transitions to `under_review` (one event per real status transition, 1:1 with the raw status). Fires ONLY for operations attributed to an API key (human/SPA operations never dispatch) and only when the merchant has a default callback URL configured. Sandbox (sk_test_) operations create no rows, so they never fire webhooks. Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the deposit.under_review event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["deposit.under_review"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/DepositWebhookData"}}},"examples":{"deposit_under_review":{"value":{"event":"deposit.under_review","data":{"id":"qr-id-456","type":"deposit","amount_cents":5000,"status":"under_review","created_at":"2026-07-01 12:00:00","updated_at":"2026-07-01 12:00:00","rejection_reasons":[],"event_id":"evt_9f8e7d6c5b4a"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"deposit.pending_pix2fa":{"post":{"summary":"Deposit transitioned to pending_pix2fa","description":"Sent when a deposit created via API key transitions to `pending_pix2fa` (one event per real status transition, 1:1 with the raw status). Fires ONLY for operations attributed to an API key (human/SPA operations never dispatch) and only when the merchant has a default callback URL configured. Sandbox (sk_test_) operations create no rows, so they never fire webhooks. Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the deposit.pending_pix2fa event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["deposit.pending_pix2fa"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/DepositWebhookData"}}},"examples":{"deposit_pending_pix2fa":{"value":{"event":"deposit.pending_pix2fa","data":{"id":"qr-id-456","type":"deposit","amount_cents":5000,"status":"pending_pix2fa","created_at":"2026-07-01 12:00:00","updated_at":"2026-07-01 12:00:00","rejection_reasons":[],"event_id":"evt_9f8e7d6c5b4a"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"deposit.approved":{"post":{"summary":"Deposit transitioned to approved","description":"Sent when a deposit created via API key transitions to `approved` (one event per real status transition, 1:1 with the raw status). Fires ONLY for operations attributed to an API key (human/SPA operations never dispatch) and only when the merchant has a default callback URL configured. Sandbox (sk_test_) operations create no rows, so they never fire webhooks. Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the deposit.approved event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["deposit.approved"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/DepositWebhookData"}}},"examples":{"deposit_approved":{"value":{"event":"deposit.approved","data":{"id":"qr-id-456","type":"deposit","amount_cents":5000,"status":"approved","created_at":"2026-07-01 12:00:00","updated_at":"2026-07-01 12:00:00","rejection_reasons":[],"event_id":"evt_9f8e7d6c5b4a"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"deposit.delayed":{"post":{"summary":"Deposit transitioned to delayed","description":"Sent when a deposit created via API key transitions to `delayed` (one event per real status transition, 1:1 with the raw status). Fires ONLY for operations attributed to an API key (human/SPA operations never dispatch) and only when the merchant has a default callback URL configured. Sandbox (sk_test_) operations create no rows, so they never fire webhooks. Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the deposit.delayed event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["deposit.delayed"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/DepositWebhookData"}}},"examples":{"deposit_delayed":{"value":{"event":"deposit.delayed","data":{"id":"qr-id-456","type":"deposit","amount_cents":5000,"status":"delayed","created_at":"2026-07-01 12:00:00","updated_at":"2026-07-01 12:00:00","rejection_reasons":[],"event_id":"evt_9f8e7d6c5b4a"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"deposit.will_refund":{"post":{"summary":"Deposit transitioned to will_refund","description":"Sent when a deposit created via API key transitions to `will_refund` (one event per real status transition, 1:1 with the raw status). Fires ONLY for operations attributed to an API key (human/SPA operations never dispatch) and only when the merchant has a default callback URL configured. Sandbox (sk_test_) operations create no rows, so they never fire webhooks. Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the deposit.will_refund event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["deposit.will_refund"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/DepositWebhookData"}}},"examples":{"deposit_will_refund":{"value":{"event":"deposit.will_refund","data":{"id":"qr-id-456","type":"deposit","amount_cents":5000,"status":"will_refund","created_at":"2026-07-01 12:00:00","updated_at":"2026-07-01 12:00:00","rejection_reasons":["PAYER_MISMATCH"],"event_id":"evt_9f8e7d6c5b4a"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"deposit.depix_sent":{"post":{"summary":"Deposit transitioned to depix_sent","description":"Sent when a deposit created via API key transitions to `depix_sent` (one event per real status transition, 1:1 with the raw status). Fires ONLY for operations attributed to an API key (human/SPA operations never dispatch) and only when the merchant has a default callback URL configured. Sandbox (sk_test_) operations create no rows, so they never fire webhooks. Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the deposit.depix_sent event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["deposit.depix_sent"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/DepositWebhookData"}}},"examples":{"deposit_depix_sent":{"value":{"event":"deposit.depix_sent","data":{"id":"qr-id-456","type":"deposit","amount_cents":5000,"status":"depix_sent","created_at":"2026-07-01 12:00:00","updated_at":"2026-07-01 12:34:56","rejection_reasons":[],"event_id":"evt_9f8e7d6c5b4a"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"deposit.refunded":{"post":{"summary":"Deposit transitioned to refunded","description":"Sent when a deposit created via API key transitions to `refunded` (one event per real status transition, 1:1 with the raw status). Fires ONLY for operations attributed to an API key (human/SPA operations never dispatch) and only when the merchant has a default callback URL configured. Sandbox (sk_test_) operations create no rows, so they never fire webhooks. Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the deposit.refunded event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["deposit.refunded"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/DepositWebhookData"}}},"examples":{"deposit_refunded":{"value":{"event":"deposit.refunded","data":{"id":"qr-id-456","type":"deposit","amount_cents":5000,"status":"refunded","created_at":"2026-07-01 12:00:00","updated_at":"2026-07-01 12:00:00","rejection_reasons":["PAYER_MISMATCH"],"event_id":"evt_9f8e7d6c5b4a"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"deposit.canceled":{"post":{"summary":"Deposit transitioned to canceled","description":"Sent when a deposit created via API key transitions to `canceled` (one event per real status transition, 1:1 with the raw status). Fires ONLY for operations attributed to an API key (human/SPA operations never dispatch) and only when the merchant has a default callback URL configured. Sandbox (sk_test_) operations create no rows, so they never fire webhooks. Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the deposit.canceled event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["deposit.canceled"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/DepositWebhookData"}}},"examples":{"deposit_canceled":{"value":{"event":"deposit.canceled","data":{"id":"qr-id-456","type":"deposit","amount_cents":5000,"status":"canceled","created_at":"2026-07-01 12:00:00","updated_at":"2026-07-01 12:00:00","rejection_reasons":[],"event_id":"evt_9f8e7d6c5b4a"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"deposit.error":{"post":{"summary":"Deposit transitioned to error","description":"Sent when a deposit created via API key transitions to `error` (one event per real status transition, 1:1 with the raw status). Fires ONLY for operations attributed to an API key (human/SPA operations never dispatch) and only when the merchant has a default callback URL configured. Sandbox (sk_test_) operations create no rows, so they never fire webhooks. Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the deposit.error event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["deposit.error"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/DepositWebhookData"}}},"examples":{"deposit_error":{"value":{"event":"deposit.error","data":{"id":"qr-id-456","type":"deposit","amount_cents":5000,"status":"error","created_at":"2026-07-01 12:00:00","updated_at":"2026-07-01 12:00:00","rejection_reasons":["PAYER_MISMATCH"],"event_id":"evt_9f8e7d6c5b4a"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"deposit.expired":{"post":{"summary":"Deposit transitioned to expired","description":"Sent when a deposit created via API key transitions to `expired` (one event per real status transition, 1:1 with the raw status). Fires ONLY for operations attributed to an API key (human/SPA operations never dispatch) and only when the merchant has a default callback URL configured. Sandbox (sk_test_) operations create no rows, so they never fire webhooks. Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the deposit.expired event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["deposit.expired"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/DepositWebhookData"}}},"examples":{"deposit_expired":{"value":{"event":"deposit.expired","data":{"id":"qr-id-456","type":"deposit","amount_cents":5000,"status":"expired","created_at":"2026-07-01 12:00:00","updated_at":"2026-07-01 12:00:00","rejection_reasons":[],"event_id":"evt_9f8e7d6c5b4a"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"withdraw.unsent":{"post":{"summary":"Withdrawal transitioned to unsent","description":"Withdrawal awaiting the DePix transfer (initial state). Creation does not emit a webhook; this event fires only on a reversal back to this state. Fires ONLY for operations attributed to an API key (human/SPA operations never dispatch) and only when the merchant has a default callback URL configured. Sandbox (sk_test_) operations create no rows, so they never fire webhooks. Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the withdraw.unsent event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["withdraw.unsent"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/WithdrawalWebhookData"}}},"examples":{"withdraw_unsent":{"value":{"event":"withdraw.unsent","data":{"id":"wd-123","type":"withdraw","amount_cents":10000,"status":"unsent","created_at":"2026-07-01 10:00:00","updated_at":"2026-07-01 10:00:00","event_id":"evt_1a2b3c4d5e6f"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"withdraw.sending":{"post":{"summary":"Withdrawal transitioned to sending","description":"Sent when a withdrawal created via API key transitions to `sending` (one event per real status transition, 1:1 with the raw status). Fires ONLY for operations attributed to an API key (human/SPA operations never dispatch) and only when the merchant has a default callback URL configured. Sandbox (sk_test_) operations create no rows, so they never fire webhooks. Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the withdraw.sending event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["withdraw.sending"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/WithdrawalWebhookData"}}},"examples":{"withdraw_sending":{"value":{"event":"withdraw.sending","data":{"id":"wd-123","type":"withdraw","amount_cents":10000,"status":"sending","created_at":"2026-07-01 10:00:00","updated_at":"2026-07-01 10:00:00","event_id":"evt_1a2b3c4d5e6f"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"withdraw.sent":{"post":{"summary":"Withdrawal transitioned to sent","description":"Sent when a withdrawal created via API key transitions to `sent` (one event per real status transition, 1:1 with the raw status). Fires ONLY for operations attributed to an API key (human/SPA operations never dispatch) and only when the merchant has a default callback URL configured. Sandbox (sk_test_) operations create no rows, so they never fire webhooks. Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the withdraw.sent event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["withdraw.sent"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/WithdrawalWebhookData"}}},"examples":{"withdraw_sent":{"value":{"event":"withdraw.sent","data":{"id":"wd-123","type":"withdraw","amount_cents":10000,"status":"sent","created_at":"2026-07-01 10:00:00","updated_at":"2026-07-01 10:00:00","liquid_txid":"abababababababababababababababababababababababababababababababab","event_id":"evt_1a2b3c4d5e6f"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"withdraw.refunded":{"post":{"summary":"Withdrawal transitioned to refunded","description":"Sent when a withdrawal created via API key transitions to `refunded` (one event per real status transition, 1:1 with the raw status). Fires ONLY for operations attributed to an API key (human/SPA operations never dispatch) and only when the merchant has a default callback URL configured. Sandbox (sk_test_) operations create no rows, so they never fire webhooks. Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the withdraw.refunded event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["withdraw.refunded"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/WithdrawalWebhookData"}}},"examples":{"withdraw_refunded":{"value":{"event":"withdraw.refunded","data":{"id":"wd-123","type":"withdraw","amount_cents":10000,"status":"refunded","created_at":"2026-07-01 10:00:00","updated_at":"2026-07-01 10:00:00","event_id":"evt_1a2b3c4d5e6f"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"withdraw.cancelled":{"post":{"summary":"Withdrawal transitioned to cancelled","description":"Sent when a withdrawal created via API key transitions to `cancelled` (one event per real status transition, 1:1 with the raw status). Fires ONLY for operations attributed to an API key (human/SPA operations never dispatch) and only when the merchant has a default callback URL configured. Sandbox (sk_test_) operations create no rows, so they never fire webhooks. Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the withdraw.cancelled event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["withdraw.cancelled"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/WithdrawalWebhookData"}}},"examples":{"withdraw_cancelled":{"value":{"event":"withdraw.cancelled","data":{"id":"wd-123","type":"withdraw","amount_cents":10000,"status":"cancelled","created_at":"2026-07-01 10:00:00","updated_at":"2026-07-01 10:00:00","event_id":"evt_1a2b3c4d5e6f"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"withdraw.error":{"post":{"summary":"Withdrawal transitioned to error","description":"Sent when a withdrawal created via API key transitions to `error` (one event per real status transition, 1:1 with the raw status). Fires ONLY for operations attributed to an API key (human/SPA operations never dispatch) and only when the merchant has a default callback URL configured. Sandbox (sk_test_) operations create no rows, so they never fire webhooks. Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the withdraw.error event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["withdraw.error"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/WithdrawalWebhookData"}}},"examples":{"withdraw_error":{"value":{"event":"withdraw.error","data":{"id":"wd-123","type":"withdraw","amount_cents":10000,"status":"error","created_at":"2026-07-01 10:00:00","updated_at":"2026-07-01 10:00:00","event_id":"evt_1a2b3c4d5e6f"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"withdraw.expired":{"post":{"summary":"Withdrawal transitioned to expired","description":"Sent when a withdrawal created via API key transitions to `expired` (one event per real status transition, 1:1 with the raw status). Fires ONLY for operations attributed to an API key (human/SPA operations never dispatch) and only when the merchant has a default callback URL configured. Sandbox (sk_test_) operations create no rows, so they never fire webhooks. Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the withdraw.expired event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["withdraw.expired"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/WithdrawalWebhookData"}}},"examples":{"withdraw_expired":{"value":{"event":"withdraw.expired","data":{"id":"wd-123","type":"withdraw","amount_cents":10000,"status":"expired","created_at":"2026-07-01 10:00:00","updated_at":"2026-07-01 10:00:00","event_id":"evt_1a2b3c4d5e6f"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"checkout.processing":{"post":{"summary":"Checkout PIX paid","description":"Sent when the payer's PIX is confirmed and settlement starts. Sent to the checkout's callback_url (checkout-level, falling back to product/merchant defaults at creation time). Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the checkout.processing event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["checkout.processing"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/CheckoutWebhookData"}}},"examples":{"checkout_processing":{"value":{"event":"checkout.processing","data":{"id":"chk_abc","status":"processing","amount":1500,"processing_at":"2026-07-01T12:01:00.000Z","event_id":"evt_c1d2e3f4a5b6"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"checkout.approved":{"post":{"summary":"Checkout approved","description":"Sent when the provider approves the payment (DePix on the way to the merchant). Sent to the checkout's callback_url (checkout-level, falling back to product/merchant defaults at creation time). Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the checkout.approved event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["checkout.approved"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/CheckoutWebhookData"}}},"examples":{"checkout_approved":{"value":{"event":"checkout.approved","data":{"id":"chk_abc","status":"approved","amount":1500,"approved_at":"2026-07-01T12:01:30.000Z","event_id":"evt_c1d2e3f4a5b7"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"checkout.completed":{"post":{"summary":"Checkout completed","description":"Sent when the DePix settles to the merchant wallet (terminal success). Sent to the checkout's callback_url (checkout-level, falling back to product/merchant defaults at creation time). Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the checkout.completed event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["checkout.completed"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/CheckoutWebhookData"}}},"examples":{"checkout_completed":{"value":{"event":"checkout.completed","data":{"id":"chk_abc","status":"completed","amount":1500,"completed_at":"2026-07-01T12:02:00.000Z","blockchain_tx_id":"cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd","event_id":"evt_c1d2e3f4a5b8"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"checkout.cancelled":{"post":{"summary":"Checkout cancelled","description":"Sent when the provider cancels the checkout upstream (refund/error). Sent to the checkout's callback_url (checkout-level, falling back to product/merchant defaults at creation time). Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the checkout.cancelled event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["checkout.cancelled"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/CheckoutWebhookData"}}},"examples":{"checkout_cancelled":{"value":{"event":"checkout.cancelled","data":{"id":"chk_abc","status":"cancelled","amount":1500,"cancelled_at":"2026-07-01T12:05:00.000Z","event_id":"evt_c1d2e3f4a5b9"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"checkout.expired":{"post":{"summary":"Checkout expired","description":"Sent when a pending checkout's QR expires unpaid (cron sweep). Sent to the checkout's callback_url (checkout-level, falling back to product/merchant defaults at creation time). Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the checkout.expired event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["checkout.expired"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/CheckoutWebhookData"}}},"examples":{"checkout_expired":{"value":{"event":"checkout.expired","data":{"id":"chk_abc","status":"expired","amount":1500,"event_id":"evt_c1d2e3f4a5c0"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"agent.graduated":{"post":{"summary":"Agent account graduated to production","description":"Sent once when an agent account is promoted to full production (5 settled personal deposits, matured ≥15d, clean fraud gate). After this, the agent may mint a full `sk_live_` key. Delivered to the agent's `default_callback_url`. Outbound POST to the merchant's callback URL, signed with `X-DePix-Signature: t=<unix ts>,v1=<hex hmac-sha256>` where the HMAC is computed over `\"${t}.${raw body}\"` with the merchant webhook secret. Verify the signature and reject stale timestamps. Delivery is retried on failure: immediate → 1m → 10m → 1h → 4h → 12h (max 6 attempts); use `data.event_id` to deduplicate. Respond with any 2xx quickly to acknowledge.","parameters":[{"name":"X-DePix-Signature","in":"header","required":true,"description":"`t=<unix ts>,v1=<hex hmac-sha256>` — HMAC-SHA256 over `\"${t}.${raw request body}\"` keyed with the merchant webhook secret.","schema":{"type":"string"}},{"name":"X-DePix-Event-Id","in":"header","required":true,"description":"The delivery's stable event id (evt_*) — same value as `data.event_id`.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Envelope of the agent.graduated event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["agent.graduated"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/AgentGraduatedWebhookData"}}},"examples":{"agent_graduated":{"value":{"event":"agent.graduated","data":{"username":"acme-butler","graduated_at":"2026-07-16 12:34:56","event_id":"evt_a9b8c7d6e5f4"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key in the Authorization header: `Authorization: Bearer sk_live_…` (production) or `Bearer sk_test_…` (sandbox). Keys are created per merchant in the dashboard with explicit scopes (merchant_read/merchant_write/wallet_read/wallet_write) and, for wallet_write keys, mandatory spending limits. First-party dashboard JWTs are also accepted on the same endpoints."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional idempotency key (1–255 visible ASCII chars). Retrying with the same key and the SAME body replays the stored response (marked with the Idempotency-Replayed: true header) with zero new side effects; the same key with a DIFFERENT body is rejected with 422 idempotency_key_reuse; a concurrent duplicate gets 409 idempotency_in_flight. Keys expire after 24 h. Responses with status 5xx/429 are never stored, so those retries re-execute.","schema":{"type":"string","minLength":1,"maxLength":255}}},"headers":{"XRequestId":{"description":"Request correlation id — present on EVERY response (success and error). Matches error.request_id in error bodies.","schema":{"type":"string"}},"RetryAfter":{"description":"Seconds to wait before retrying (mirrors error.retry_after).","schema":{"type":"integer"}},"IdempotencyReplayed":{"description":"Present with value \"true\" when this response was replayed from a stored Idempotency-Key result instead of re-executing the operation.","schema":{"type":"string","enum":["true"]}}},"schemas":{"ErrorEnvelope":{"type":"object","description":"Dual error envelope. `response.errorMessage` is the legacy human-readable Portuguese contract; `error` is the additive machine-readable contract for agents (English). Some legacy sibling fields survive for backwards compatibility (`response.errors`, top-level `blocked`).","required":["response","error"],"additionalProperties":false,"properties":{"response":{"type":"object","description":"Legacy envelope — Portuguese message, first in the body (SPA/integrator contract).","required":["errorMessage"],"additionalProperties":false,"properties":{"errorMessage":{"type":"string","description":"Human-readable error message in Portuguese (legacy contract)."},"errors":{"type":"array","description":"Per-field validation errors — legacy sibling emitted by POST /api/checkouts on validation_error.","items":{"type":"object","description":"One field-level validation failure.","required":["field","message"],"additionalProperties":false,"properties":{"field":{"type":"string","description":"Name of the offending request field."},"message":{"type":"string","description":"Portuguese validation message for the field."}}}}}},"blocked":{"type":"boolean","description":"Legacy sibling present only on 403 `account_blocked` responses (always true when present)."},"error":{"type":"object","description":"Machine-readable error object (agent contract, English messages).","required":["code","message","request_id","docs_url"],"additionalProperties":false,"properties":{"code":{"type":"string","description":"Stable machine-readable error code. The enum below is the complete closed catalog — branch on this value, never on messages.","enum":["unauthorized","invalid_api_key","invalid_token","agent_invalid_signature","agent_signature_expired","agent_replay_detected","agent_unknown_key","invalid_operator_token","invalid_password","insufficient_scope","oauth_account_not_linked","account_already_linked","workos_identity_in_use","account_blocked","account_suspended","operator_token_revoked","agent_account_no_password","registration_blocked","domain_required","graduation_pending","merchant_required","live_access_required","whatsapp_verification_required","withdraw_disabled","external_wallet_disabled","sandbox_only","validation_error","password_required","tax_number_required","amount_out_of_range","account_limit_exceeded","key_limit_exceeded","attachment_too_large","not_found","conflict","agent_pubkey_exists","ticket_closed","username_taken","idempotency_in_flight","idempotency_key_reuse","domain_tld_not_allowed","domain_free_host","domain_txt_not_found","rate_limited","merchant_rate_limited","ticket_open_cap","payer_velocity_limit","platform_shutdown","service_unavailable","attachment_unavailable","agents_disabled","upstream_error","operator_oauth_failed","internal_error"]},"message":{"type":"string","description":"Human-readable English message for the code."},"request_id":{"type":"string","description":"Request correlation id — also returned on EVERY response (success included) as the X-Request-Id header. Quote it in support requests."},"retry_after":{"type":"integer","description":"Seconds to wait before retrying. Present on every 429, 503 and 409 idempotency_in_flight; mirrored in the Retry-After HTTP header."},"docs_url":{"type":"string","description":"Link to the error documentation."},"details":{"type":"object","description":"Optional machine-readable extras, normative per code: validation_error → {field}; insufficient_scope → {required_scope}; rate_limited → {scope}; amount_out_of_range → {min_cents, max_cents} (bounds of THIS endpoint/mode); account_limit_exceeded → {limit, limit_cents, used_cents?}; key_limit_exceeded → {limit, limit_cents, used_cents}; payer_velocity_limit → {window_minutes, max_per_window}; ticket_open_cap → {max_open}; agent_signature_expired → {server_time}.","additionalProperties":false,"properties":{"server_time":{"type":"integer","description":"Server unix time in seconds (agent_signature_expired) — re-sync the client clock and retry."},"field":{"type":"string","description":"Offending request field (validation_error)."},"max_open":{"type":"integer","description":"Maximum open tickets allowed for this account (ticket_open_cap)."},"required_scope":{"type":"string","description":"Scope the API key is missing (insufficient_scope)."},"scope":{"type":"string","description":"Rate-limit scope that tripped (rate_limited)."},"window_minutes":{"type":"integer","description":"Sliding-window length in minutes (payer_velocity_limit)."},"max_per_window":{"type":"integer","description":"Maximum QRs per payer CPF/CNPJ inside the window (payer_velocity_limit)."},"limit":{"type":"string","description":"Which limit tripped: \"first_deposit\" | \"per_tx\" | \"cumulative\" (account_limit_exceeded) or \"per_tx\" | \"daily\" (key_limit_exceeded)."},"limit_cents":{"type":"integer","description":"The limit value in cents."},"used_cents":{"type":"integer","description":"Amount already consumed against the limit, in cents (cumulative/daily limits only)."},"min_cents":{"type":"integer","description":"Minimum accepted amount in cents for this endpoint/mode."},"max_cents":{"type":"integer","description":"Maximum accepted amount in cents for this endpoint/mode."}}}}}}},"LegacyErrorEnvelope":{"type":"object","description":"Legacy-only error envelope: a human-readable Portuguese message with NO machine-readable `error` object. Emitted by the public storefront endpoints — branch on the HTTP status code there, not on an error code.","required":["response"],"additionalProperties":false,"properties":{"response":{"type":"object","description":"Legacy envelope — Portuguese message.","required":["errorMessage"],"additionalProperties":false,"properties":{"errorMessage":{"type":"string","description":"Human-readable error message in Portuguese."},"errors":{"type":"array","description":"Per-field validation errors — present on validation failures.","items":{"type":"object","description":"One field-level validation failure.","required":["field","message"],"additionalProperties":false,"properties":{"field":{"type":"string","description":"Name of the offending request field."},"message":{"type":"string","description":"Portuguese validation message for the field."}}}}}}}},"DepositStatus":{"type":"string","description":"Deposit lifecycle status — the enum below is the complete, closed set. `depix_sent` is the terminal SUCCESS state. Terminal states (safe to stop polling): depix_sent, refunded, canceled, error, expired.","enum":["pending","under_review","pending_pix2fa","approved","delayed","will_refund","depix_sent","refunded","canceled","error","expired"],"oneOf":[{"const":"pending","description":"QR code generated; PIX not paid yet."},{"const":"under_review","description":"PIX paid; payment in pre-settlement review."},{"const":"pending_pix2fa","description":"PIX paid; waiting for the payer to complete PIX 2FA."},{"const":"approved","description":"PIX approved by the provider; DePix not yet sent."},{"const":"delayed","description":"Settlement held by the delay policy (new/high-value accounts)."},{"const":"will_refund","description":"Refund flow started; the deposit will be refunded."},{"const":"depix_sent","description":"TERMINAL — success: DePix delivered to the target Liquid address.","x-terminal":true},{"const":"refunded","description":"TERMINAL — deposit refunded to the payer.","x-terminal":true},{"const":"canceled","description":"TERMINAL — canceled upstream.","x-terminal":true},{"const":"error","description":"TERMINAL — upstream processing error.","x-terminal":true},{"const":"expired","description":"TERMINAL — QR expired unpaid.","x-terminal":true}]},"WithdrawalStatus":{"type":"string","description":"Withdrawal lifecycle status — the enum below is the complete, closed set. `sent` is the terminal SUCCESS state. Sandbox status reads return the sandbox-only synthetic value `confirmed` instead (see the sandbox response variant). Terminal states (safe to stop polling): sent, refunded, cancelled, error, expired.","enum":["unsent","sending","sent","refunded","cancelled","error","expired"],"oneOf":[{"const":"unsent","description":"Created; DePix not yet received by the provider."},{"const":"sending","description":"DePix received; PIX payout in flight."},{"const":"sent","description":"TERMINAL — success: PIX delivered to the target key.","x-terminal":true},{"const":"refunded","description":"TERMINAL — refunded.","x-terminal":true},{"const":"cancelled","description":"TERMINAL — cancelled.","x-terminal":true},{"const":"error","description":"TERMINAL — upstream processing error.","x-terminal":true},{"const":"expired","description":"TERMINAL — DePix never arrived (swept by cron).","x-terminal":true}]},"CheckoutStatus":{"type":"string","description":"Checkout lifecycle status — the enum below is the complete, closed set. `completed` is the terminal SUCCESS state. Terminal states (safe to stop polling): completed, expired, cancelled.","enum":["pending","processing","approved","completed","expired","cancelled"],"oneOf":[{"const":"pending","description":"Awaiting payment; the PIX QR is active until expires_at."},{"const":"processing","description":"PIX paid; settlement in progress."},{"const":"approved","description":"Payment approved by the provider; DePix on the way to the merchant."},{"const":"completed","description":"TERMINAL — success: DePix delivered to the merchant.","x-terminal":true},{"const":"expired","description":"TERMINAL — QR expired unpaid.","x-terminal":true},{"const":"cancelled","description":"TERMINAL — cancelled upstream by the provider (refund/error).","x-terminal":true}]},"DepositCreateRequest":{"type":"object","description":"Personal deposit request: generates a PIX QR whose payment delivers DePix to `depixAddress`.","required":["amountInCents","depixAddress","payer_tax_number"],"properties":{"amountInCents":{"type":"integer","description":"Deposit amount in cents (BRL). Accepted range: 500–300000 (R$ 5,00–R$ 3.000,00). Account-level and per-key limits may restrict it further.","minimum":500,"maximum":300000},"depixAddress":{"type":"string","description":"Liquid address that will receive the DePix once the PIX settles."},"payer_tax_number":{"type":"string","description":"CPF or CNPJ of the PIX payer. Required — omitting it returns 400 `tax_number_required`. Always validated and forwarded to the payment provider."}}},"DepositCreateResponse":{"type":"object","description":"Deposit creation result (HTTP 200 — success only). A provider business rejection is NOT a 200: it returns HTTP 400 `validation_error` with the upstream message preserved in `response.errorMessage`, mirroring POST /api/withdraw.","required":["async","response"],"additionalProperties":false,"properties":{"async":{"type":"boolean","description":"Always false — QR generation is synchronous."},"response":{"type":"object","description":"PIX QR payload (live or sandbox).","required":["qrCopyPaste","qrImageUrl","id"],"additionalProperties":false,"properties":{"qrCopyPaste":{"type":"string","description":"PIX copy-and-paste (BR Code) payload the payer uses. In sandbox this is a SANDBOX-…-DO-NOT-PAY placeholder that must never be paid."},"qrImageUrl":{"type":["string","null"],"description":"URL (or data URI) of the rendered QR image. Always set on live; null on sandbox (nothing to render)."},"id":{"type":"string","description":"Deposit id — poll GET /api/deposits/{id} with it. Prefixed sandbox_ in test mode."},"sandbox":{"type":"boolean","description":"Present and true only on sk_test_ responses (synthetic sandbox: no PIX, no DePix, nothing to pay)."}}}}},"DepositStatusResponse":{"description":"Deposit status read (stable English subset of the row). Live rows and the fixed synthetic sandbox variant.","oneOf":[{"type":"object","description":"Live deposit row (JWT or sk_live_).","required":["id","type","amount_cents","status","created_at","updated_at","rejection_reasons"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Deposit id (the id returned by POST /api/deposit)."},"type":{"type":"string","enum":["deposit"],"description":"Resource discriminator — always \"deposit\" here."},"amount_cents":{"type":"integer","description":"Deposit amount in cents (BRL)."},"status":{"$ref":"#/components/schemas/DepositStatus"},"created_at":{"type":"string","description":"Creation timestamp (UTC, `YYYY-MM-DD HH:MM:SS`)."},"updated_at":{"type":"string","description":"Last update timestamp (UTC). Only settlement is individually timestamped today, so this equals created_at until depix_sent."},"rejection_reasons":{"type":"array","items":{"type":"string"},"description":"Provider reasons a deposit was refused/held — e.g. PAYER_MISMATCH, PAST_DAILY_LIMIT, BLOCKED_USER, HIGH_VELOCITY. Empty array when the deposit was not refused. New reason codes may appear; display unknown codes as-is."}}},{"type":"object","description":"Sandbox synthetic status (sk_test_ key + sandbox_* id): a fixed, stateless terminal success so agents can exercise the full polling loop in test mode. Echoes amount_cents + deterministic timestamps so the shape matches the live variant.","required":["id","type","amount_cents","status","created_at","updated_at","sandbox","rejection_reasons"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"The sandbox_* id passed in the path."},"type":{"type":"string","enum":["deposit"],"description":"Resource discriminator — always \"deposit\" here."},"amount_cents":{"type":["integer","null"],"description":"Deposit amount in cents (BRL), decoded from the sandbox_* id minted at creation — mirrors the live read so agents can confirm the value in test mode. null only for legacy/malformed sandbox ids that carry no embedded amount."},"status":{"type":"string","enum":["depix_sent"],"description":"Fixed synthetic terminal success state (always depix_sent in sandbox)."},"created_at":{"type":"string","description":"Deterministic synthetic creation timestamp (UTC, `YYYY-MM-DD HH:MM:SS`) — fixed in sandbox (stateless)."},"updated_at":{"type":"string","description":"Deterministic synthetic update timestamp (UTC, `YYYY-MM-DD HH:MM:SS`) — equals created_at in sandbox."},"sandbox":{"type":"boolean","const":true,"description":"Marks the synthetic sandbox response."},"rejection_reasons":{"type":"array","items":{"type":"string"},"description":"Always an empty array in sandbox — the synthetic terminal state is a success, so there is never a reason. Present so agents learn the field's shape in test mode."}}}]},"WithdrawCreateRequest":{"type":"object","description":"Withdrawal (Liquid→PIX) request. Send EXACTLY ONE of depositAmountInCents (\"you send\" mode) or payoutAmountInCents (\"you receive\" mode). A legacy `depixAddress` field is accepted and ignored.","required":["pixKey","taxNumber"],"properties":{"pixKey":{"type":"string","description":"Destination PIX key (email, phone, CPF/CNPJ or random key)."},"depositAmountInCents":{"type":"integer","description":"\"You send\" mode: DePix amount you will deliver, in cents. Range: 500–600000. Mutually exclusive with payoutAmountInCents.","minimum":500,"maximum":600000},"payoutAmountInCents":{"type":"integer","description":"\"You receive\" mode: PIX amount the destination key receives, in cents. Range: 500–588000 (fee-adjusted). Mutually exclusive with depositAmountInCents.","minimum":500,"maximum":588000},"taxNumber":{"type":"string","description":"CPF/CNPJ of the PIX key holder. Required — omitting it returns 400 `tax_number_required`."}},"oneOf":[{"required":["depositAmountInCents"],"not":{"required":["payoutAmountInCents"]}},{"required":["payoutAmountInCents"],"not":{"required":["depositAmountInCents"]}}]},"WithdrawCreateResponse":{"type":"object","description":"Withdrawal quote: send DePix to `response.depositAddress` — and, on the API-key path, the platform fee (`fee_cents`) to `fee_address` in the SAME transaction. Track via GET /api/withdrawals/{id} and/or withdraw.* webhooks.","required":["response"],"additionalProperties":false,"properties":{"response":{"type":"object","description":"Withdrawal quote payload.","required":["withdrawalId","depositAddress","depositAmountInCents","payoutAmountInCents"],"additionalProperties":false,"properties":{"withdrawalId":{"type":"string","description":"Withdrawal id — use it in GET /api/withdrawals/{id}. Prefixed sandbox_ in test mode."},"depositAddress":{"type":"string","description":"Liquid address to send the DePix to. In sandbox this is a SANDBOX-…-DO-NOT-PAY placeholder — never send funds to it."},"depositAmountInCents":{"type":"integer","description":"DePix amount the provider expects to receive, in cents."},"payoutAmountInCents":{"type":"integer","description":"PIX amount the destination key will receive, in cents."},"totalDepositAmountInCents":{"type":"integer","description":"Gross wallet outflow: provider amount + service fee."},"split":{"type":"object","description":"Duplicate of fee_cents/fee_address in an older shape; read fee_cents/fee_address instead.","required":["address","amountCentavos"],"additionalProperties":false,"properties":{"address":{"type":"string","description":"Liquid address of the platform fee output."},"amountCentavos":{"type":"integer","description":"Fee amount in cents for the second output."}}},"fee_cents":{"type":"integer","description":"Platform fee in cents (API-key path). MANDATORY: pay this amount to `fee_address` as an explicit (unblinded) DePix output in the SAME transaction as the provider output. The fee is verified server-side against the provider-reported settlement transaction — a transaction without it results in a failed withdrawal and lost funds."},"fee_address":{"type":"string","description":"Non-confidential (ex1) Liquid address for the platform fee output (API-key path). Pay it EXACTLY as given — a confidential/blinded output cannot be verified and counts as an unpaid fee. The output must carry the DePix asset id `02f22f8d9c76ab41661a2729e4752e2c5d1a263012141b86ea98af5472df5189` (Liquid mainnet)."},"sandbox":{"type":"boolean","description":"Present and true only on sk_test_ responses (synthetic quote, fixed 2% rate)."}}}}},"WithdrawalStatusResponse":{"description":"Withdrawal status read (stable English subset of the row). Live rows and the fixed synthetic sandbox variant.","oneOf":[{"type":"object","description":"Live withdrawal row (JWT or sk_live_).","required":["id","type","amount_cents","status","created_at","updated_at"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Withdrawal id (the withdrawalId returned by POST /api/withdraw)."},"type":{"type":"string","enum":["withdraw"],"description":"Resource discriminator — always \"withdraw\" here."},"amount_cents":{"type":"integer","description":"Provider-side deposit amount in cents (what the caller sends) — consistent with the per-key daily accumulator."},"status":{"$ref":"#/components/schemas/WithdrawalStatus"},"created_at":{"type":"string","description":"Creation timestamp (UTC, `YYYY-MM-DD HH:MM:SS`)."},"updated_at":{"type":"string","description":"Last update timestamp (UTC). No per-status timestamps exist on withdrawals today, so this equals created_at."},"liquid_txid":{"type":"string","description":"Settlement Liquid txid (the provider-reported on-chain tx that funded the withdrawal) — present once the provider reports it."}}},{"type":"object","description":"Sandbox synthetic status (sk_test_ key + sandbox_* id): fixed, stateless terminal state for test-mode polling. Echoes amount_cents + deterministic timestamps so the shape matches the live variant.","required":["id","type","amount_cents","status","created_at","updated_at","sandbox"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"The sandbox_* id passed in the path."},"type":{"type":"string","enum":["withdraw"],"description":"Resource discriminator — always \"withdraw\" here."},"amount_cents":{"type":["integer","null"],"description":"Provider-side deposit amount in cents (what the caller sends), decoded from the sandbox_* id minted at creation — mirrors the live read. null only for legacy/malformed sandbox ids that carry no embedded amount."},"status":{"type":"string","enum":["confirmed"],"description":"Fixed synthetic sandbox-only state (always \"confirmed\")."},"created_at":{"type":"string","description":"Deterministic synthetic creation timestamp (UTC, `YYYY-MM-DD HH:MM:SS`) — fixed in sandbox (stateless)."},"updated_at":{"type":"string","description":"Deterministic synthetic update timestamp (UTC, `YYYY-MM-DD HH:MM:SS`) — equals created_at in sandbox."},"sandbox":{"type":"boolean","const":true,"description":"Marks the synthetic sandbox response."}}}]},"CheckoutCreateRequest":{"type":"object","description":"Checkout creation request (merchant receiving side).","required":["amount","payer_tax_number"],"properties":{"amount":{"type":"integer","description":"Charge amount in cents (BRL). Range: 500–300000.","minimum":500,"maximum":300000},"description":{"type":"string","description":"Free-text description shown on the checkout page (max 500 chars).","maxLength":500},"image_url":{"type":"string","description":"HTTPS image displayed on the checkout page."},"callback_url":{"type":"string","description":"HTTPS webhook endpoint for this checkout's checkout.* events (overrides the merchant default)."},"redirect_url":{"type":"string","description":"HTTPS URL the payer is redirected to after completion."},"metadata":{"type":"object","description":"Arbitrary JSON object echoed back in reads and webhooks (max 4KB serialized)."},"expires_in":{"type":"integer","description":"QR lifetime in seconds. Range: 300–1200; default 1200.","minimum":300,"maximum":1200},"payer_tax_number":{"type":"string","description":"CPF/CNPJ of the payer. Required — omitting it returns 400 `validation_error` naming the field."}}},"CheckoutCreateResponse":{"type":"object","description":"Created checkout with its PIX payload and hosted payment page.","required":["id","status","amount","description","image_url","expires_at","is_live","payment_url","pix"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Checkout id (chk_*)."},"status":{"$ref":"#/components/schemas/CheckoutStatus","description":"Always \"pending\" at creation."},"amount":{"type":"integer","description":"Charge amount in cents."},"description":{"type":["string","null"],"description":"Description echoed back (null when not provided)."},"image_url":{"type":["string","null"],"description":"Image URL echoed back (null when not provided)."},"expires_at":{"type":"string","description":"QR expiry timestamp (UTC, `YYYY-MM-DD HH:MM:SS`)."},"is_live":{"type":"boolean","description":"False for sandbox checkouts (sk_test_): PIX payload is a non-payable placeholder."},"payment_url":{"type":"string","description":"Hosted checkout page URL to hand to the payer."},"pix":{"type":"object","description":"PIX payment payload.","required":["qr_code"],"additionalProperties":false,"properties":{"qr_code":{"type":"string","description":"PIX copy-and-paste (BR Code) payload. SANDBOX-…-DO-NOT-PAY placeholder in test mode."}}}}},"CheckoutDetail":{"type":"object","description":"Full checkout row (authenticated read).","required":["id","status","amount","description","image_url","callback_url","redirect_url","metadata","expires_at","is_live","created_at","processing_at","approved_at","completed_at","cancelled_at","blockchain_tx_id","rejection_reasons"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Checkout id (chk_*)."},"status":{"$ref":"#/components/schemas/CheckoutStatus"},"amount":{"type":"integer","description":"Charge amount in cents."},"description":{"type":["string","null"],"description":"Checkout description."},"image_url":{"type":["string","null"],"description":"Checkout image URL."},"pix_payload":{"type":"string","description":"PIX copy-and-paste payload — present only while status is \"pending\"."},"rejection_reasons":{"type":"array","items":{"type":"string"},"description":"Provider reasons for a refunded/held payment on the underlying deposit — e.g. PAYER_MISMATCH, PAST_DAILY_LIMIT, BLOCKED_USER, HIGH_VELOCITY. Empty array when the payment was not refused. New reason codes may appear; display unknown codes as-is."},"callback_url":{"type":["string","null"],"description":"Webhook endpoint receiving this checkout's checkout.* events."},"redirect_url":{"type":["string","null"],"description":"Post-payment redirect URL."},"metadata":{"type":["object","string","null"],"description":"Merchant metadata. Parsed back to an object when valid JSON; the raw string is preserved otherwise."},"expires_at":{"type":"string","description":"QR expiry timestamp (UTC)."},"is_live":{"type":"integer","description":"1 = live, 0 = sandbox (raw SQLite boolean).","enum":[0,1]},"created_at":{"type":"string","description":"Creation timestamp (UTC)."},"processing_at":{"type":["string","null"],"description":"When the checkout entered processing (null if never)."},"approved_at":{"type":["string","null"],"description":"When the checkout was approved (null if never)."},"completed_at":{"type":["string","null"],"description":"When the checkout completed (null if never)."},"cancelled_at":{"type":["string","null"],"description":"When the checkout was cancelled (null if never)."},"blockchain_tx_id":{"type":["string","null"],"description":"Liquid transaction id of the DePix settlement (null until completed)."}}},"CheckoutGetResponse":{"type":"object","description":"Envelope of the authenticated checkout read.","required":["checkout"],"additionalProperties":false,"properties":{"checkout":{"$ref":"#/components/schemas/CheckoutDetail"}}},"CheckoutListResponse":{"type":"object","description":"Paginated checkout list with aggregate stats.","required":["checkouts","stats","limit","offset"],"additionalProperties":false,"properties":{"checkouts":{"type":"array","description":"Checkout rows, newest first.","items":{"type":"object","description":"Checkout list item.","required":["id","status","amount","description","created_at","expires_at","is_live","processing_at","approved_at","metadata","product_name","rejection_reasons"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Checkout id (chk_*)."},"status":{"$ref":"#/components/schemas/CheckoutStatus"},"amount":{"type":"integer","description":"Charge amount in cents."},"description":{"type":["string","null"],"description":"Checkout description."},"created_at":{"type":"string","description":"Creation timestamp (UTC)."},"expires_at":{"type":"string","description":"QR expiry timestamp (UTC)."},"is_live":{"type":"integer","description":"1 = live, 0 = sandbox (raw SQLite boolean).","enum":[0,1]},"processing_at":{"type":["string","null"],"description":"When the checkout entered processing (null if never)."},"approved_at":{"type":["string","null"],"description":"When the checkout was approved (null if never)."},"metadata":{"type":["string","null"],"description":"Merchant metadata as the raw stored JSON string (not parsed on the list endpoint)."},"product_name":{"type":["string","null"],"description":"Name of the linked product (null for generic checkouts)."},"rejection_reasons":{"type":"array","items":{"type":"string"},"description":"Provider reasons for a refunded/held payment on the underlying deposit — e.g. PAYER_MISMATCH, PAST_DAILY_LIMIT, BLOCKED_USER, HIGH_VELOCITY. Empty array when the payment was not refused. New reason codes may appear; display unknown codes as-is."}}}},"stats":{"type":"object","description":"Aggregates over the CURRENT FILTER (not just the current page).","required":["total","pending","completed","completed_amount"],"additionalProperties":false,"properties":{"total":{"type":"integer","description":"Total checkouts matching the filter."},"pending":{"type":"integer","description":"Checkouts currently pending."},"completed":{"type":"integer","description":"Checkouts completed."},"completed_amount":{"type":"integer","description":"Sum of completed amounts in cents."}}},"limit":{"type":"integer","description":"Applied page size (1–100)."},"offset":{"type":"integer","description":"Applied offset."}}},"MeResponse":{"type":"object","description":"Identity of the authenticated merchant — probe endpoint for key validation.","required":["merchant_id","name","username","merchant_slug","is_live","created_at"],"additionalProperties":false,"properties":{"merchant_id":{"type":"string","description":"Merchant id."},"name":{"type":"string","description":"Merchant business name."},"username":{"type":["string","null"],"description":"Owner account username (null if unavailable)."},"merchant_slug":{"type":"string","description":"Public URL slug of the merchant page (pay.depixapp.com/{merchant_slug})."},"is_live":{"type":"boolean","description":"False when authenticated with a sk_test_ key (sandbox mode)."},"created_at":{"type":"string","description":"Merchant creation timestamp (UTC)."}}},"TicketStatus":{"type":"string","description":"Ticket lifecycle status — the enum below is the complete, closed set. `closed` is terminal (an auto-closed ticket may be reopened by replying within 7 days). Terminal states (safe to stop polling): closed.","enum":["awaiting_reply","answered","closed"],"oneOf":[{"const":"awaiting_reply","description":"The ball is with support — a reply from support is pending. NEVER auto-closes."},{"const":"answered","description":"Support replied; awaiting the user. Auto-closes after 7 days of no user reply."},{"const":"closed","description":"TERMINAL — closed by the user, support, or the 7-day auto-close sweep.","x-terminal":true}]},"Ticket":{"type":"object","description":"A support ticket (summary view).","required":["id","opener_type","status","subject","category","created_at","last_activity_at","closed_reason","closed_at"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Ticket id (tkt_*)."},"opener_type":{"type":"string","description":"Who opened the ticket, snapshotted from the account type at creation.","enum":["human","agent"]},"status":{"$ref":"#/components/schemas/TicketStatus"},"subject":{"type":"string","description":"Ticket subject (4–120 chars)."},"category":{"type":"string","description":"Ticket category.","enum":["bug","question","account","payment","other"]},"created_at":{"type":"string","description":"Creation timestamp (UTC)."},"last_activity_at":{"type":"string","description":"Timestamp of the last user/admin message (UTC). System messages do not bump it."},"closed_reason":{"type":["string","null"],"description":"Why the ticket closed: 'user', 'admin' or 'auto' — null while open."},"closed_at":{"type":["string","null"],"description":"Close timestamp (UTC) — null while open. Anchors the 7-day reopen window for auto-closed tickets."}}},"TicketAttachment":{"type":"object","description":"Metadata of a file attached to a message. The bytes are forwarded to the support team (not stored or served back) — only the name and type are exposed.","required":["name","mime"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Original filename (sanitized)."},"mime":{"type":["string","null"],"description":"Content type (image/png, image/jpeg, image/webp, application/pdf, text/plain or application/json)."}}},"TicketMessage":{"type":"object","description":"A single message in a ticket thread.","required":["id","sender","body","created_at"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Message id."},"sender":{"type":"string","description":"Who sent the message.","enum":["user","admin","system"]},"body":{"type":"string","description":"Message body."},"created_at":{"type":"string","description":"Message timestamp (UTC)."},"attachment":{"description":"Attached file metadata when the message carries a file, otherwise null. Present on every message (null for plain text).","anyOf":[{"$ref":"#/components/schemas/TicketAttachment"},{"type":"null"}]}}},"TicketCreateRequest":{"type":"object","description":"Open a new support ticket. The body becomes the first user message.","required":["subject","body"],"additionalProperties":false,"properties":{"subject":{"type":"string","description":"Short subject (4–120 chars).","minLength":4,"maxLength":120},"body":{"type":"string","description":"Message body (1–4000 chars).","minLength":1,"maxLength":4000},"category":{"type":"string","description":"Optional category (defaults to 'other'). Does not route anything today; used for triage.","enum":["bug","question","account","payment","other"]}}},"TicketResponse":{"type":"object","description":"A single ticket wrapped in `ticket`.","required":["ticket"],"additionalProperties":false,"properties":{"ticket":{"$ref":"#/components/schemas/Ticket"}}},"TicketListResponse":{"type":"object","description":"Paginated list of the tickets created by this principal (session/key).","required":["tickets","total","limit","offset"],"additionalProperties":false,"properties":{"tickets":{"type":"array","description":"Tickets created by this principal, newest activity first.","items":{"$ref":"#/components/schemas/Ticket"}},"total":{"type":"integer","description":"Total tickets for this principal (ignores pagination)."},"limit":{"type":"integer","description":"Applied page size."},"offset":{"type":"integer","description":"Applied pagination offset."}}},"TicketGetResponse":{"type":"object","description":"Ticket detail with its full message thread.","required":["ticket","messages"],"additionalProperties":false,"properties":{"ticket":{"$ref":"#/components/schemas/Ticket"},"messages":{"type":"array","description":"All messages, oldest first.","items":{"$ref":"#/components/schemas/TicketMessage"}}}},"TicketMessageRequest":{"type":"object","description":"Post a reply to a ticket. On an answered ticket this moves it back to awaiting_reply; on an auto-closed ticket within 7 days it reopens it.","required":["body"],"additionalProperties":false,"properties":{"body":{"type":"string","description":"Message body (1–4000 chars).","minLength":1,"maxLength":4000}}},"TicketAttachmentRequest":{"type":"object","description":"Attach ONE file to a ticket. The bytes go in file_b64 (base64, no data: URI prefix) and are forwarded to the support team's Telegram topic — not stored or served back. Max ~3 MB decoded. Same state machine as a reply: an answered ticket returns to awaiting_reply; an auto-closed ticket within 7 days reopens.","required":["filename","content_type","file_b64"],"additionalProperties":false,"properties":{"filename":{"type":"string","description":"Filename shown to support (sanitized; max 200 chars).","maxLength":200},"content_type":{"type":"string","description":"File MIME type.","enum":["image/png","image/jpeg","image/webp","application/pdf","text/plain","application/json"]},"file_b64":{"type":"string","description":"The file bytes, base64-encoded (no data: URI prefix). Max ~3 MB decoded."},"caption":{"type":"string","description":"Optional note shown with the file (max 400 chars).","maxLength":400}}},"TicketMessageResponse":{"type":"object","description":"The posted message plus the updated ticket.","required":["message","ticket"],"additionalProperties":false,"properties":{"message":{"$ref":"#/components/schemas/TicketMessage"},"ticket":{"$ref":"#/components/schemas/Ticket"}}},"MerchantUpdateRequest":{"type":"object","description":"Partial merchant-profile update — only the provided fields change. On the API-key path ONLY these 5 light fields are editable; sending liquid_address, cnpj or password is rejected with 400 validation_error (owner + web dashboard only). split_address is never editable here (admin only). Every key-authenticated PATCH emails the account owner (compensating control).","additionalProperties":false,"properties":{"business_name":{"type":"string","description":"New business name (2–100 chars). Changing it rotates the public merchant_slug and retires the old one, so any outstanding payment links or checkout URLs built on the old slug will 404 — rename with that in mind.","minLength":2,"maxLength":100},"website":{"type":["string","null"],"description":"New website URL (normalized to https://; null/empty clears it)."},"logo_url":{"type":["string","null"],"description":"New HTTPS logo URL (null/empty clears it)."},"default_callback_url":{"type":["string","null"],"description":"New HTTPS default webhook endpoint for deposit.*/withdraw.* events (null/empty clears it)."},"default_redirect_url":{"type":["string","null"],"description":"New HTTPS default post-payment redirect for this merchant's customers (null/empty clears it)."}}},"MerchantUpdateResponse":{"type":"object","description":"Result of a merchant-profile update.","required":["success","merchant_slug"],"additionalProperties":false,"properties":{"success":{"type":"boolean","const":true,"description":"Always true on success."},"merchant_slug":{"type":"string","description":"The merchant's public URL slug after the update (unchanged unless business_name changed)."}}},"ProductCreateRequest":{"type":"object","description":"Product creation request (reusable checkout template with a public page).","required":["name","amount"],"properties":{"name":{"type":"string","description":"Product name (2–80 chars).","minLength":2,"maxLength":80},"slug":{"type":"string","description":"URL slug (lowercase letters, digits, hyphens). Auto-generated from name when omitted."},"amount":{"type":"integer","description":"Price in cents (BRL). Range: 500–300000.","minimum":500,"maximum":300000},"description":{"type":"string","description":"Product description (max 500 chars).","maxLength":500},"image_url":{"type":"string","description":"HTTPS product image URL."},"callback_url":{"type":"string","description":"HTTPS webhook endpoint for checkouts created from this product."},"redirect_url":{"type":"string","description":"HTTPS post-payment redirect for checkouts created from this product."},"metadata":{"type":"object","description":"Arbitrary JSON copied into each checkout (max 4KB serialized)."},"expires_in":{"type":"integer","description":"Checkout QR lifetime in seconds. Range: 300–1200; default 1200.","minimum":300,"maximum":1200}}},"ProductCreateResponse":{"type":"object","description":"Created product.","required":["product"],"additionalProperties":false,"properties":{"product":{"type":"object","description":"The created product.","required":["id","slug","name","amount","description","image_url","callback_url","redirect_url","metadata","expires_in","active","is_live","payment_url","created_at"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Product id (prd_*)."},"slug":{"type":"string","description":"URL slug (unique per merchant and mode)."},"name":{"type":"string","description":"Product name."},"amount":{"type":"integer","description":"Price in cents."},"description":{"type":["string","null"],"description":"Product description (null when not provided)."},"image_url":{"type":["string","null"],"description":"Product image URL (null when not provided)."},"callback_url":{"type":["string","null"],"description":"Webhook endpoint for this product's checkouts (null when not provided)."},"redirect_url":{"type":["string","null"],"description":"Post-payment redirect (null when not provided)."},"metadata":{"type":["object","null"],"description":"Metadata echoed back (null when not provided)."},"expires_in":{"type":"integer","description":"Checkout QR lifetime in seconds."},"active":{"type":"boolean","description":"Products are created active."},"is_live":{"type":"boolean","description":"False for sandbox products (sk_test_)."},"payment_url":{"type":"string","description":"Public product page URL (pay.depixapp.com/{merchant_slug}/{slug})."},"created_at":{"type":"string","description":"Creation timestamp (ISO 8601)."}}}}},"ProductListItem":{"type":"object","description":"Product list row with checkout aggregates.","required":["id","slug","name","amount","description","image_url","active","is_live","expires_in","created_at","position","total_checkouts","completed_checkouts","completed_amount"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Product id (prd_*)."},"slug":{"type":"string","description":"URL slug."},"name":{"type":["string","null"],"description":"Product name."},"amount":{"type":"integer","description":"Price in cents."},"description":{"type":["string","null"],"description":"Product description."},"image_url":{"type":["string","null"],"description":"Product image URL."},"active":{"type":"integer","description":"1 = active (purchasable), 0 = deactivated (raw SQLite boolean).","enum":[0,1]},"is_live":{"type":"integer","description":"1 = live, 0 = sandbox (raw SQLite boolean).","enum":[0,1]},"expires_in":{"type":"integer","description":"Checkout QR lifetime in seconds."},"created_at":{"type":"string","description":"Creation timestamp (UTC)."},"position":{"type":["integer","null"],"description":"Pinned position on the public page (null = not pinned)."},"total_checkouts":{"type":"integer","description":"Total checkouts created from this product."},"completed_checkouts":{"type":"integer","description":"Completed checkouts."},"completed_amount":{"type":"integer","description":"Sum of completed amounts in cents."}}},"ProductListResponse":{"type":"object","description":"Paginated product list.","required":["products","limit","offset"],"additionalProperties":false,"properties":{"products":{"type":"array","description":"Product rows.","items":{"$ref":"#/components/schemas/ProductListItem"}},"limit":{"type":"integer","description":"Applied page size (1–100)."},"offset":{"type":"integer","description":"Applied offset."}}},"ProductGetResponse":{"type":"object","description":"Single product with checkout aggregates. NOTE: `product` mirrors the full database row (SELECT *), so additional columns may appear as the schema evolves — additionalProperties is intentionally open here.","required":["product","stats"],"properties":{"product":{"type":"object","description":"Full product row.","properties":{"id":{"type":"string","description":"Product id (prd_*)."},"merchant_id":{"type":"string","description":"Owning merchant id."},"slug":{"type":"string","description":"URL slug."},"name":{"type":["string","null"],"description":"Product name."},"amount":{"type":"integer","description":"Price in cents."},"description":{"type":["string","null"],"description":"Product description."},"image_url":{"type":["string","null"],"description":"Product image URL."},"callback_url":{"type":["string","null"],"description":"Webhook endpoint for this product's checkouts."},"redirect_url":{"type":["string","null"],"description":"Post-payment redirect."},"metadata":{"type":["object","string","null"],"description":"Metadata (parsed to an object when valid JSON)."},"expires_in":{"type":"integer","description":"Checkout QR lifetime in seconds."},"active":{"type":"integer","description":"1 = active, 0 = deactivated (raw SQLite boolean).","enum":[0,1]},"is_live":{"type":"integer","description":"1 = live, 0 = sandbox (raw SQLite boolean).","enum":[0,1]},"position":{"type":["integer","null"],"description":"Pinned position on the public page (null = not pinned)."},"created_at":{"type":"string","description":"Creation timestamp (UTC)."},"updated_at":{"type":"string","description":"Last update timestamp (UTC)."}}},"stats":{"type":"object","description":"Checkout aggregates for the product.","required":["total","completed","pending","completed_amount"],"additionalProperties":false,"properties":{"total":{"type":"integer","description":"Total checkouts created from this product."},"completed":{"type":"integer","description":"Completed checkouts."},"pending":{"type":"integer","description":"Pending checkouts."},"completed_amount":{"type":"integer","description":"Sum of completed amounts in cents."}}}}},"ProductUpdateRequest":{"type":"object","description":"Partial product update — only the provided fields change. Nullable fields (description, image_url, callback_url, redirect_url, metadata) accept null/empty string to clear.","properties":{"name":{"type":"string","description":"New product name (2–80 chars).","minLength":2,"maxLength":80},"slug":{"type":"string","description":"New URL slug (must stay unique per merchant and mode)."},"amount":{"type":"integer","description":"New price in cents. Range: 500–300000.","minimum":500,"maximum":300000},"description":{"type":["string","null"],"description":"New description (null/empty clears it)."},"image_url":{"type":["string","null"],"description":"New HTTPS image URL (null/empty clears it)."},"callback_url":{"type":["string","null"],"description":"New HTTPS webhook endpoint (null/empty clears it)."},"redirect_url":{"type":["string","null"],"description":"New HTTPS redirect (null/empty clears it)."},"metadata":{"type":["object","null"],"description":"New metadata object (null clears it, max 4KB serialized)."},"expires_in":{"type":"integer","description":"New checkout QR lifetime in seconds (300–1200).","minimum":300,"maximum":1200}}},"ProductCheckoutsResponse":{"type":"object","description":"Paginated checkouts of one product, with aggregates.","required":["checkouts","stats","limit","offset"],"additionalProperties":false,"properties":{"checkouts":{"type":"array","description":"Checkout rows for the product, newest first.","items":{"type":"object","description":"Product checkout list item.","required":["id","status","amount","description","created_at","expires_at","processing_at","completed_at"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Checkout id (chk_*)."},"status":{"$ref":"#/components/schemas/CheckoutStatus"},"amount":{"type":"integer","description":"Charge amount in cents."},"description":{"type":["string","null"],"description":"Checkout description."},"created_at":{"type":"string","description":"Creation timestamp (UTC)."},"expires_at":{"type":"string","description":"QR expiry timestamp (UTC)."},"processing_at":{"type":["string","null"],"description":"When the checkout entered processing (null if never)."},"completed_at":{"type":["string","null"],"description":"When the checkout completed (null if never)."}}}},"stats":{"type":"object","description":"Aggregates over the current filter.","required":["total","completed","completed_amount"],"additionalProperties":false,"properties":{"total":{"type":"integer","description":"Total checkouts matching the filter."},"completed":{"type":"integer","description":"Completed checkouts."},"completed_amount":{"type":"integer","description":"Sum of completed amounts in cents."}}},"limit":{"type":"integer","description":"Applied page size (1–100)."},"offset":{"type":"integer","description":"Applied offset."}}},"ProductPublicResponse":{"type":"object","description":"Public product data (no auth) — powers the public product page.","required":["id","slug","amount","description","image_url","merchant_name","merchant_logo","username","merchant_slug","is_test"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Product id (prd_*)."},"slug":{"type":"string","description":"URL slug."},"amount":{"type":"integer","description":"Price in cents."},"description":{"type":["string","null"],"description":"Product description."},"image_url":{"type":["string","null"],"description":"Product image URL."},"merchant_name":{"type":"string","description":"Merchant display name."},"merchant_logo":{"type":["string","null"],"description":"Merchant logo URL."},"username":{"type":"string","description":"Legacy alias of merchant_slug (kept for integrators; read merchant_slug instead)."},"merchant_slug":{"type":"string","description":"Merchant public URL slug."},"is_test":{"type":"boolean","description":"Always false here — only live products are served publicly."}}},"PublicProductCheckoutResponse":{"type":"object","description":"Checkout created from a public product page.","required":["id","status","amount","description","expires_at","is_live","payment_url","pix"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Checkout id (chk_*)."},"status":{"$ref":"#/components/schemas/CheckoutStatus","description":"Always \"pending\" at creation."},"amount":{"type":"integer","description":"Charge amount in cents (the product price)."},"description":{"type":["string","null"],"description":"Product description carried onto the checkout."},"expires_at":{"type":"string","description":"QR expiry timestamp (UTC)."},"is_live":{"type":"boolean","description":"Always true — only live products accept public checkouts."},"payment_url":{"type":"string","description":"Hosted checkout page URL."},"pix":{"type":"object","description":"PIX payment payload.","required":["qr_code"],"additionalProperties":false,"properties":{"qr_code":{"type":"string","description":"PIX copy-and-paste (BR Code) payload."}}}}},"MerchantPublicResponse":{"type":"object","description":"Public merchant data (no auth) — the storefront identity behind pay.depixapp.com/{merchant_slug}.","required":["business_name","logo_url","username","merchant_slug"],"additionalProperties":false,"properties":{"business_name":{"type":"string","description":"Merchant display name."},"logo_url":{"type":["string","null"],"description":"Merchant logo URL (null when the merchant has no logo)."},"username":{"type":"string","description":"Legacy alias of merchant_slug (kept for integrators; read merchant_slug instead)."},"merchant_slug":{"type":"string","description":"Merchant public URL slug — the same value used in the request path."}}},"MerchantCheckoutRequest":{"type":"object","description":"Public charge against a merchant storefront: the payer chooses the amount. Description, image and URLs are NOT accepted here — callback_url and redirect_url always come from the merchant's saved defaults.","required":["amount","payer_tax_number"],"properties":{"amount":{"type":"integer","description":"Charge amount in cents (BRL). Range: 500–300000. When `items` is sent this MUST equal the sum of qty × the catalog price of every line, otherwise the request is rejected.","minimum":500,"maximum":300000},"expires_in":{"type":"integer","description":"QR lifetime in seconds. Range: 300–1200; default 1200.","minimum":300,"maximum":1200},"payer_tax_number":{"type":"string","description":"CPF/CNPJ of the payer. Required — omitting it returns 400 `validation_error` naming the field."},"items":{"type":"array","description":"Optional cart. Each line names one of the merchant's products by slug; names and unit prices are rebuilt server-side from the catalog and are never trusted from the request. At most 50 lines, no duplicate slugs. Omit it for a plain amount-only charge.","maxItems":50,"items":{"type":"object","description":"One cart line.","required":["slug","qty"],"additionalProperties":false,"properties":{"slug":{"type":"string","description":"Slug of an active, live product of this merchant."},"qty":{"type":"integer","description":"Quantity for this line (1–9999).","minimum":1,"maximum":9999}}}}}},"MerchantCheckoutResponse":{"type":"object","description":"Checkout created from a public merchant storefront page.","required":["id","status","amount","description","expires_at","is_live","payment_url","pix"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Checkout id (chk_*)."},"status":{"$ref":"#/components/schemas/CheckoutStatus","description":"Always \"pending\" at creation."},"amount":{"type":"integer","description":"Charge amount in cents (the amount sent in the request)."},"description":{"type":["string","null"],"description":"Always null — this endpoint accepts no description field."},"expires_at":{"type":"string","description":"QR expiry timestamp (UTC, `YYYY-MM-DD HH:MM:SS`)."},"is_live":{"type":"boolean","description":"Always true — public storefront checkouts are never sandbox."},"payment_url":{"type":"string","description":"Hosted checkout page URL to hand to the payer."},"pix":{"type":"object","description":"PIX payment payload.","required":["qr_code"],"additionalProperties":false,"properties":{"qr_code":{"type":"string","description":"PIX copy-and-paste (BR Code) payload."}}}}},"PayCheckoutResponse":{"type":"object","description":"Public checkout data (no auth) — poll it to track payment from the payer side.","required":["id","status","amount","currency","description","image_url","merchant_name","merchant_username","merchant_slug","remaining_seconds","expires_at","redirect_url","is_test"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Checkout id (chk_*)."},"status":{"$ref":"#/components/schemas/CheckoutStatus"},"amount":{"type":"integer","description":"Charge amount in cents."},"currency":{"type":"string","enum":["BRL"],"description":"Always BRL."},"description":{"type":["string","null"],"description":"Checkout description."},"image_url":{"type":["string","null"],"description":"Checkout image URL."},"merchant_name":{"type":"string","description":"Merchant display name."},"merchant_username":{"type":"string","description":"Legacy alias of merchant_slug (kept for integrators; read merchant_slug instead)."},"merchant_slug":{"type":"string","description":"Merchant public URL slug."},"remaining_seconds":{"type":"integer","description":"Seconds until QR expiry (0 when expired or not pending)."},"expires_at":{"type":["string","null"],"description":"QR expiry timestamp (UTC)."},"redirect_url":{"type":["string","null"],"description":"Post-payment redirect URL."},"is_test":{"type":"boolean","description":"True for sandbox checkouts (non-payable placeholder QR)."},"pix":{"type":"object","description":"PIX payment payload — present only while status is \"pending\".","required":["qr_code"],"additionalProperties":false,"properties":{"qr_code":{"type":"string","description":"PIX copy-and-paste (BR Code) payload."}}}}},"SuccessResponse":{"type":"object","description":"Generic success acknowledgment.","required":["success"],"additionalProperties":false,"properties":{"success":{"type":"boolean","const":true,"description":"Always true on success."}}},"FeaturedResponse":{"type":"object","description":"Result of reconciling the pinned product set.","required":["success","featured"],"additionalProperties":false,"properties":{"success":{"type":"boolean","const":true,"description":"Always true on success."},"featured":{"type":"array","description":"The pinned product ids in their new display order.","items":{"type":"string","description":"Product id (prd_*)."}}}},"HealthResponse":{"type":"object","description":"Dependency health. The HTTP status is the contract: 200 = healthy, 503 = degraded.","required":["status","turso","redis","schema","timestamp"],"additionalProperties":false,"properties":{"status":{"type":"string","enum":["ok","degraded"],"description":"\"ok\" when every dependency check passed, \"degraded\" otherwise (mirrors the HTTP status)."},"turso":{"type":"boolean","description":"Database reachability."},"redis":{"type":"boolean","description":"Rate-limit store reachability."},"schema":{"type":"boolean","description":"Schema migration probe."},"timestamp":{"type":"string","description":"Server time (ISO 8601)."}}},"AgentRegisterRequest":{"type":"object","description":"Agent registration body. The request must ALSO carry the signed agent headers (X-Agent-Public-Key, X-Agent-Timestamp, X-Agent-Nonce, X-Agent-Signature — Ed25519 over the canonical string; the public key becomes the account identity).","required":["name","operator_token","operator_email","liquid_address"],"additionalProperties":false,"properties":{"name":{"type":"string","description":"Display/business name (2–100 chars). Becomes the merchant business_name."},"username":{"type":"string","description":"Optional handle (3–30 chars, [a-zA-Z0-9_]). Defaults to agent_<first 10 hex of the public key>. Taken → 409 username_taken."},"operator_token":{"type":"string","description":"REQUIRED anti-farm anchor: the op_… token minted when the human operator connected via OAuth or the GitHub PAT fast-path. One operator token clusters N agents."},"operator_email":{"type":"string","description":"Operator notification email (format-validated only; never becomes the account login email)."},"liquid_address":{"type":"string","description":"Static Liquid address for merchant receipts — produced by the agent's own wallet (the SDK derives it; not user-chosen). Immutable after registration."},"default_callback_url":{"type":"string","description":"Optional HTTPS webhook endpoint for deposit.*/withdraw.*/checkout.* events."},"ref":{"type":"string","description":"Optional referrer username for affiliate attribution."}}},"AgentRegisterResponse":{"type":"object","description":"Agent onboarding result — the ONLY response that ever carries key plaintexts and the webhook secret.","required":["response"],"additionalProperties":false,"properties":{"response":{"type":"object","description":"Envelope (legacy contract shape).","required":["agent","merchant","keys","graduation","pacing"],"additionalProperties":false,"properties":{"agent":{"type":"object","description":"The created agent account.","required":["username","public_key","account_type"],"additionalProperties":false,"properties":{"username":{"type":"string","description":"Account handle (also the merchant slug until graduation)."},"public_key":{"type":"string","description":"The Ed25519 public key registered as the account identity (64 hex)."},"account_type":{"type":"string","enum":["agent"],"description":"Always \"agent\" — server-set and immutable."}}},"merchant":{"type":"object","description":"The auto-created merchant profile.","required":["id","merchant_slug","liquid_address","webhook_secret"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Merchant id (mrc_…)."},"merchant_slug":{"type":"string","description":"Public page slug — equals the username until graduation (anti-squat)."},"liquid_address":{"type":"string","description":"The static receiving address from the request."},"webhook_secret":{"type":"string","description":"ONE-TIME plaintext webhook signing secret (whsec_…). Rotatable later; never shown again."}}},"keys":{"type":"object","description":"Auto-issued API keys — plaintexts shown ONLY here.","required":["test","live_starter"],"additionalProperties":false,"properties":{"test":{"type":"object","description":"Sandbox key with the full default scopes.","required":["id","key","scopes"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Key id."},"key":{"type":"string","description":"sk_test_… plaintext (one-time)."},"scopes":{"type":"string","description":"Space-separated scopes granted to the sandbox key."}}},"live_starter":{"type":"object","description":"Pre-graduation production key: wallet-only scopes with mandatory low limits.","required":["id","key","scopes","per_tx_limit_cents","daily_limit_cents","starter"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Key id."},"key":{"type":"string","description":"sk_live_… plaintext (one-time)."},"scopes":{"type":"string","description":"Exactly \"wallet_read wallet_write\" — merchant scopes require graduation + a verified domain."},"per_tx_limit_cents":{"type":"integer","description":"Mandatory per-transaction cap on this key."},"daily_limit_cents":{"type":"integer","description":"Mandatory rolling daily cap on this key."},"starter":{"type":"boolean","description":"Always true — marks the auto-issued starter key."}}}}},"graduation":{"type":"object","description":"What unlocks full production capability.","required":["required_settled_deposits","maturation_days"],"additionalProperties":false,"properties":{"required_settled_deposits":{"type":"integer","description":"Settled personal deposits required to graduate."},"maturation_days":{"type":"integer","description":"Single account-level age gate, NOT a wait between deposits: the account graduates once its 5th settled personal deposit is at least this many days old (plus a clean fraud review). Deposits themselves can be created back-to-back."}}},"pacing":{"type":"object","description":"Read-only account limits so the agent can pace itself without trial-and-error 4xx.","required":["first_deposit_max_cents","unverified_per_tx_max_cents","unverified_lifetime_max_cents","inter_deposit_delay_hours","payer_velocity","verified_per_tx_deposit_max_cents","verified_per_tx_withdraw_max_cents"],"additionalProperties":false,"properties":{"first_deposit_max_cents":{"type":"integer","description":"Cap on the account's first deposit."},"unverified_per_tx_max_cents":{"type":"integer","description":"Per-deposit cap before verification."},"unverified_lifetime_max_cents":{"type":"integer","description":"Cumulative deposit cap before verification."},"inter_deposit_delay_hours":{"type":"integer","description":"Settlement delay applied to deposits 2–5 of an unverified account: the DePix payout of each of those deposits is held for this many hours (deposit status `delayed`). It does NOT block CREATING the next deposit — you never have to wait between creates because of this field."},"payer_velocity":{"type":"object","description":"Per-payer deposit velocity gate.","required":["max_per_window","window_minutes"],"additionalProperties":false,"properties":{"max_per_window":{"type":"integer","description":"Deposits allowed per payer per window."},"window_minutes":{"type":"integer","description":"Window length in minutes."}}},"verified_per_tx_deposit_max_cents":{"type":"integer","description":"Per-deposit cap after verification."},"verified_per_tx_withdraw_max_cents":{"type":"integer","description":"Per-withdrawal cap after verification."}}}}}}},"DomainTldsResponse":{"type":"object","description":"The current TLD allowlist for domain verification — discover what verify-domain accepts without trial-and-error.","required":["allowed_tlds"],"additionalProperties":false,"properties":{"allowed_tlds":{"type":"array","description":"Accepted TLD suffixes (leading dot), e.g. \".com\", \".com.br\". A domain whose suffix is not listed is rejected with domain_tld_not_allowed.","items":{"type":"string","description":"A TLD suffix with a leading dot."}}}},"VerifyDomainRequest":{"type":"object","description":"Two-phase domain proof. Phase 1 ({domain}) returns the DNS TXT challenge; phase 2 ({domain, confirm: true}) resolves the TXT and records the verified domain.","required":["domain"],"additionalProperties":false,"properties":{"domain":{"type":"string","description":"The domain to verify — normalized to its registrable eTLD+1 (\"shop.acme.com.br\" → \"acme.com.br\"). URL-ish input tolerated."},"confirm":{"type":"boolean","description":"Set true for phase 2: resolve the TXT record and confirm. Omit/false for phase 1: obtain the challenge."}}},"VerifyDomainResponse":{"description":"Phase 1 returns the challenge to publish; phase 2 returns the verified domain.","oneOf":[{"type":"object","description":"Phase-1 challenge: create this DNS TXT record, then call again with confirm: true.","required":["record_name","record_value"],"additionalProperties":false,"properties":{"record_name":{"type":"string","description":"TXT record name to create (_depix-verify.<domain>)."},"record_value":{"type":"string","description":"Exact TXT record value (depix-verify=<token>). Stable across calls — safe to re-fetch."}}},{"type":"object","description":"Phase-2 confirmation: the domain is now verified for this agent.","required":["verified_domain"],"additionalProperties":false,"properties":{"verified_domain":{"type":"string","description":"The registrable domain (eTLD+1) recorded on the agent."}}}]},"AgentKeyCreateRequest":{"type":"object","description":"Mint an API key for the agent's own merchant. Authenticated by the agent keypair signature (no password step-up — the per-request signature IS the step-up).","additionalProperties":false,"properties":{"live":{"type":"boolean","description":"true → production sk_live_ (requires graduation); false/omitted → sandbox sk_test_."},"scopes":{"type":"array","description":"Any subset of the scope taxonomy. merchant_* scopes require a verified domain. Defaults to merchant_read+merchant_write.","items":{"type":"string","enum":["merchant_read","merchant_write","wallet_read","wallet_write"],"description":"A scope from the taxonomy."}},"label":{"type":["string","null"],"description":"Optional human label (≤100 chars)."},"per_tx_limit_cents":{"type":["integer","null"],"description":"Optional per-transaction cap. wallet_write keys get a mandatory default (10000) if unset."},"daily_limit_cents":{"type":["integer","null"],"description":"Optional rolling daily cap. wallet_write keys get a mandatory default (50000) if unset."}}},"AgentKeyCreateResponse":{"type":"object","description":"The minted key — plaintext returned ONCE.","required":["response"],"additionalProperties":false,"properties":{"response":{"type":"object","description":"Envelope.","required":["id","key","prefix","is_live","scopes","per_tx_limit_cents","daily_limit_cents"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Key id."},"key":{"type":"string","description":"The sk_live_/sk_test_ plaintext (one-time)."},"prefix":{"type":"string","enum":["sk_live_","sk_test_"],"description":"Key prefix."},"is_live":{"type":"boolean","description":"true for a production key."},"scopes":{"type":"string","description":"Space-separated granted scopes."},"per_tx_limit_cents":{"type":["integer","null"],"description":"Per-transaction cap (null if unbounded and not wallet_write)."},"daily_limit_cents":{"type":["integer","null"],"description":"Rolling daily cap (null if unbounded and not wallet_write)."}}}}},"AgentKeyRevokeRequest":{"type":"object","description":"Revoke one of the agent's own keys.","required":["id"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Id of the key to revoke."}}},"AgentKeyRevokeResponse":{"type":"object","description":"Revocation result.","required":["response"],"additionalProperties":false,"properties":{"response":{"type":"object","description":"Envelope.","required":["id","revoked"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"The revoked key id."},"revoked":{"type":"boolean","description":"Always true."}}}}},"AgentWebhookSecretResponse":{"type":"object","description":"Rotated webhook secret — returned ONCE; the previous secret is invalidated immediately.","required":["response"],"additionalProperties":false,"properties":{"response":{"type":"object","description":"Envelope.","required":["webhook_secret"],"additionalProperties":false,"properties":{"webhook_secret":{"type":"string","description":"The new whsec_… secret (one-time)."}}}}},"AgentStatusResponse":{"type":"object","description":"Minimal consumable progress. Never exposes maturation dates or internal review details.","required":["response"],"additionalProperties":false,"properties":{"response":{"type":"object","description":"Envelope.","required":["account_status","settled_personal_deposits","graduated","graduation","keys"],"additionalProperties":false,"properties":{"account_status":{"type":"string","enum":["active","suspended"],"description":"Account state — \"suspended\" when the merchant is paused by the platform."},"reason":{"type":"string","description":"Human-readable suspension reason — present only when account_status is \"suspended\"."},"settled_personal_deposits":{"type":"integer","description":"Count of settled personal deposits (progress toward graduation)."},"graduated":{"type":"boolean","description":"true once the account has graduated to full production."},"graduation":{"type":"object","description":"Coarse graduation state — never the hidden maturation window or review specifics.","required":["blocked_on"],"additionalProperties":false,"properties":{"blocked_on":{"type":["string","null"],"enum":["gate_review",null],"description":"\"gate_review\" when the deposit count is met but graduation hasn't fired; otherwise null."}}},"keys":{"type":"array","description":"The account's API keys (no plaintext — that is shown only at creation).","items":{"type":"object","description":"One API key.","required":["id","prefix","is_live","starter","scopes","revoked_at"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Key id."},"prefix":{"type":"string","enum":["sk_live_","sk_test_"],"description":"Key prefix."},"is_live":{"type":"boolean","description":"true for a production key."},"starter":{"type":"boolean","description":"true for the auto-issued starter key."},"scopes":{"type":"string","description":"Space-separated scopes."},"revoked_at":{"type":["string","null"],"description":"Revocation timestamp, or null if active."}}}}}}}},"WebhookLogListResponse":{"type":"object","description":"The 50 most recent webhook delivery attempts for this account, newest first. Bodies are omitted here — fetch one log by id for the request/response payloads.","required":["logs"],"additionalProperties":false,"properties":{"logs":{"type":"array","description":"Delivery attempts, newest first (fixed window of 50).","items":{"type":"object","description":"One delivery attempt (summary view, no bodies).","required":["id","checkout_id","event","url","status_code","error","attempt","sent_at"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Delivery log id — use it on the detail endpoint."},"checkout_id":{"type":["string","null"],"description":"Checkout id (chk_*) for checkout.* events; null for deposit.*/withdraw.* events."},"event":{"type":"string","description":"Event name delivered (e.g. checkout.completed, deposit.depix_sent, withdraw.sent)."},"url":{"type":"string","description":"The callback URL the event was delivered to."},"status_code":{"type":["integer","null"],"description":"HTTP status answered by the receiver — null when the request failed before a response (timeout, connection error)."},"error":{"type":["string","null"],"description":"Transport/delivery error message, or null when a response was received."},"attempt":{"type":"integer","description":"1-based attempt number within the retry schedule (max 6)."},"sent_at":{"type":"string","description":"Delivery attempt timestamp (UTC)."}}}}}},"WebhookLogDetailResponse":{"type":"object","description":"Full detail of one delivery attempt, including the signed request body sent and the response body received.","required":["log"],"additionalProperties":false,"properties":{"log":{"type":"object","description":"One delivery attempt (full view).","required":["id","checkout_id","merchant_id","url","event","status_code","request_body","response_body","error","attempt","next_retry_at","sent_at"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Delivery log id."},"checkout_id":{"type":["string","null"],"description":"Checkout id (chk_*) for checkout.* events; null for deposit.*/withdraw.* events."},"merchant_id":{"type":["string","null"],"description":"Owning merchant id for deposit.*/withdraw.* events; null for checkout.* events (owned via the checkout)."},"url":{"type":"string","description":"The callback URL the event was delivered to."},"event":{"type":"string","description":"Event name delivered."},"status_code":{"type":["integer","null"],"description":"HTTP status answered by the receiver — null when the request failed before a response."},"request_body":{"type":["string","null"],"description":"The JSON payload sent (as a string) — the same bytes the X-DePix-Signature covers."},"response_body":{"type":["string","null"],"description":"Receiver's response body (as a string, may be truncated), or null."},"error":{"type":["string","null"],"description":"Transport/delivery error message, or null."},"attempt":{"type":"integer","description":"1-based attempt number within the retry schedule (max 6)."},"next_retry_at":{"type":["string","null"],"description":"When the next retry is scheduled (UTC), or null when delivery succeeded or the schedule is exhausted."},"sent_at":{"type":"string","description":"Delivery attempt timestamp (UTC)."}}}}},"DepositWebhookData":{"type":"object","description":"Deposit event payload — same EN shape as GET /api/deposits/{id}, plus the delivery id.","required":["id","type","amount_cents","status","created_at","updated_at","rejection_reasons","event_id"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Deposit id (the id returned by POST /api/deposit)."},"type":{"type":"string","enum":["deposit"],"description":"Resource discriminator — always \"deposit\"."},"amount_cents":{"type":"integer","description":"Deposit amount in cents."},"status":{"$ref":"#/components/schemas/DepositStatus","description":"The status the deposit just transitioned to (matches the event name)."},"created_at":{"type":"string","description":"Creation timestamp (UTC)."},"updated_at":{"type":"string","description":"Last update timestamp (UTC)."},"rejection_reasons":{"type":"array","items":{"type":"string"},"description":"Provider reasons a deposit was refused/held — e.g. PAYER_MISMATCH, PAST_DAILY_LIMIT, BLOCKED_USER, HIGH_VELOCITY. Empty array when the deposit was not refused. New reason codes may appear; display unknown codes as-is."},"event_id":{"type":"string","description":"Stable delivery id (evt_*) — identical across retries of the same event; use it for deduplication. Also sent as the X-DePix-Event-Id header."}}},"WithdrawalWebhookData":{"type":"object","description":"Withdrawal event payload — same EN shape as GET /api/withdrawals/{id}, plus the delivery id.","required":["id","type","amount_cents","status","created_at","updated_at","event_id"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Withdrawal id (the withdrawalId returned by POST /api/withdraw)."},"type":{"type":"string","enum":["withdraw"],"description":"Resource discriminator — always \"withdraw\"."},"amount_cents":{"type":"integer","description":"Provider-side deposit amount in cents."},"status":{"$ref":"#/components/schemas/WithdrawalStatus","description":"The status the withdrawal just transitioned to (matches the event name)."},"created_at":{"type":"string","description":"Creation timestamp (UTC)."},"updated_at":{"type":"string","description":"Last update timestamp (UTC)."},"liquid_txid":{"type":"string","description":"Settlement Liquid txid (the provider-reported on-chain tx that funded the withdrawal) — present once the provider reports it."},"event_id":{"type":"string","description":"Stable delivery id (evt_*) — identical across retries of the same event; use it for deduplication. Also sent as the X-DePix-Event-Id header."}}},"CheckoutWebhookData":{"type":"object","description":"Checkout event payload.","required":["id","status","amount","event_id"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Checkout id (chk_*)."},"status":{"$ref":"#/components/schemas/CheckoutStatus","description":"The status the checkout just transitioned to (matches the event name)."},"amount":{"type":"integer","description":"Charge amount in cents."},"metadata":{"type":["object","string"],"description":"Merchant metadata when set on the checkout (omitted otherwise)."},"processing_at":{"type":"string","description":"Transition timestamp — present on checkout.processing."},"approved_at":{"type":"string","description":"Transition timestamp — present on checkout.approved."},"completed_at":{"type":"string","description":"Transition timestamp — present on checkout.completed."},"cancelled_at":{"type":"string","description":"Transition timestamp — present on checkout.cancelled."},"blockchain_tx_id":{"type":"string","description":"Liquid txid of the settlement — present on checkout.completed when known."},"event_id":{"type":"string","description":"Stable delivery id (evt_*) — identical across retries of the same event; use it for deduplication. Also sent as the X-DePix-Event-Id header."}}},"AgentGraduatedWebhookData":{"type":"object","description":"agent.graduated event payload. Emitted once, when an agent account is promoted to full production (5 settled deposits, matured, clean fraud gate). NEVER contains a key — a webhook is not a secret channel.","required":["username","graduated_at","event_id"],"additionalProperties":false,"properties":{"username":{"type":"string","description":"The agent account's username (also its public affiliate code)."},"graduated_at":{"type":"string","description":"Graduation timestamp (UTC, 'YYYY-MM-DD HH:MM:SS')."},"event_id":{"type":"string","description":"Stable delivery id (evt_*) — identical across retries of the same event; use it for deduplication. Also sent as the X-DePix-Event-Id header."}}}}}}