{"openapi":"3.1.0","info":{"title":"DePix API","version":"0.50.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**Payment rails**: every checkout carries a `payment_method`. `pix` (default) is the PIX QR flow settled by the provider. `depix` charges the payer directly in DePix on Liquid: the response carries a `depix` object with a dedicated address, the EXACT amount to send and a wallet URI instead of a PIX QR; the merchant may grant a discount on this rail; there is no payer CPF/CNPJ; the checkout turns `approved` at the first confirmation (money already in the merchant's wallet) and `completed` at the second; and it only turns `expired` 15 minutes after `expires_at`, so a payment broadcast in the final seconds still settles. An on-chain payment is irreversible: send the exact amount, and only the DePix asset. A human merchant enables the rail and sets the discount in the DePix App (owner login + password) — that surface (`/api/merchants/me/depix-pay`, `/api/merchants/me/depix-outputs`) is authenticated by the owner's session and deliberately undocumented; an integration never calls it. An AGENT account has no password and no browser, so it enables the same rail through `POST /api/agents/depix-pay`, which is documented here: same rules, same view-key seal, the request signature standing in for the password.\n\n**Acting without a human**: an error may carry `error.details.next_action` — the single next move, in a closed vocabulary (`call_tool`, `human_step`, `http_call`, `wait`, `reconnect`). There is never more than one per error, and `retry_after_seconds` mirrors `retry_after` rather than disagreeing with it.\n\n**Scope of this document**: only the agent/integrator surface. JWT-only dashboard routes (auth/*, merchant create/get + rotate-webhook-secret + direct-rail setup, api-keys management, reports, uploads, webhook-logs, status, contact, …) are internal SPA contract and intentionally undocumented here. That carve-out covers the browser-rendered social signup and security step-up (`/api/auth/oauth-signup/*`, `/api/auth/oauth-session`, `/api/auth/step-up/*`): they are account surface a person walks through, not endpoints an integration calls. 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":"account","description":"Account self-service — the verification state that gates the merchant tools."},{"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. A provider that does not answer at all (timeout or network failure) returns HTTP 503 `service_unavailable` and IS worth retrying; it was an HTTP 500 until 2026-08-04. 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://qr.example/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–600000, 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$ 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}}}},"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 PAID transactions for the same payer CPF/CNPJ (`payer_velocity_limit`: max 2 paid per sliding 30-minute window, deposits + checkouts combined; unpaid/expired QRs don't count). 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/vault/status":{"get":{"tags":["pay"],"operationId":"getVaultStatus","summary":"Receive cap, trust level and hold window","description":"What the account may receive, how long a new deposit will be held, and what it still needs for the next level — read this BEFORE creating a charge so the amount is never refused and the hold is never a surprise. A deposit that would break the cap answers HTTP 400 `account_limit_exceeded` with the same numbers in `error.details`. The cap and the hold are independent: `vault_window_hours: 0` with `cap.enforced: true` means charges are refused above the cap and nothing is held below it. Deliberately omits which risk rule fired and every threshold: a caller learns that a limit exists, never the map around it.","x-required-scope":"wallet_read","responses":{"200":{"description":"Current position in the hold policy.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VaultStatusResponse"},"examples":{"new_account":{"value":{"vault_active":true,"policy_version":"2026-07-30.1","level":{"current":0,"max":4,"pinned":false,"frozen_until":null,"eligible":0},"cap":{"enforced":true,"cents":50000,"used_cents":12000,"available_cents":38000,"window_days":14,"resets_at":"2026-08-12T03:00:00.000Z","pinned":false,"first_deposit_pending":false},"vault_window_hours":336,"instant":{"enabled":true,"max_per_tx_cents":10000,"cap_cents":50000,"used_cents":2000,"window_days":14,"graduation_completed":false,"deposits_settled":2,"deposits_required":5,"identity_ok":true,"graduation_hold_hours":24,"graduation_per_tx_cents":10000,"graduation_first_max_cents":10000},"progress":{"account_age_days":6,"matured_volume_cents":0,"next_level":{"level":1,"cap_cents":200000,"window_hours":240,"min_age_days":14,"min_volume_cents":20000,"current_age_days":6,"current_volume_cents":0,"missing_age_days":8,"missing_volume_cents":20000}},"merchant_tools":{"verified":false},"kyc":{"available":true,"booking_url":"https://calendly.com/suportedepixapp/15min"}}},"cap_enforced_no_hold":{"summary":"Cap enforced, no hold — the rollback regime (window off)","value":{"vault_active":true,"policy_version":"2026-07-30.7","level":{"current":0,"max":4,"pinned":false,"frozen_until":null,"eligible":0},"cap":{"enforced":true,"cents":50000,"used_cents":12000,"available_cents":38000,"window_days":14,"resets_at":"2026-08-12T03:00:00.000Z","pinned":false,"first_deposit_pending":false},"vault_window_hours":0,"instant":{"enabled":true,"max_per_tx_cents":10000,"cap_cents":50000,"used_cents":12000,"window_days":14,"graduation_completed":false,"deposits_settled":2,"deposits_required":5,"identity_ok":true,"graduation_hold_hours":24,"graduation_per_tx_cents":10000,"graduation_first_max_cents":10000},"progress":{"account_age_days":6,"matured_volume_cents":0,"next_level":{"level":1,"cap_cents":200000,"window_hours":240,"min_age_days":14,"min_volume_cents":20000,"current_age_days":6,"current_volume_cents":0,"missing_age_days":8,"missing_volume_cents":20000}},"merchant_tools":{"verified":false},"kyc":{"available":true,"booking_url":"https://calendly.com/suportedepixapp/15min"}}},"top_of_ladder":{"value":{"vault_active":true,"policy_version":"2026-07-30.1","level":{"current":4,"max":4,"pinned":false,"frozen_until":null,"eligible":4},"cap":{"enforced":true,"cents":3000000,"used_cents":0,"available_cents":3000000,"window_days":14,"resets_at":null,"pinned":false,"first_deposit_pending":false},"vault_window_hours":72,"instant":{"enabled":true,"max_per_tx_cents":10000,"cap_cents":50000,"used_cents":0,"window_days":14,"graduation_completed":true,"deposits_settled":42,"deposits_required":5,"identity_ok":true,"graduation_hold_hours":24,"graduation_per_tx_cents":10000,"graduation_first_max_cents":10000},"progress":{"account_age_days":400,"matured_volume_cents":5000000,"next_level":null},"merchant_tools":{"verified":true},"kyc":{"available":true,"booking_url":"https://calendly.com/suportedepixapp/15min"}}}}}}},"401":{"description":"Missing or invalid credentials.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"invalid":{"value":{"response":{"errorMessage":"API key inválida."},"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"}}}}}}},"403":{"description":"Account 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"}}}}}}},"404":{"description":"Account not found.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"missing":{"value":{"response":{"errorMessage":"Conta 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"}}}}}}}}}}},"/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-01T12:00:00.000Z","updated_at":"2026-07-01T12:34:56.000Z","rejection_reasons":[]}},"sandbox":{"summary":"Sandbox synthetic (fixed)","value":{"id":"sandbox_3uw_a1b2c3d4e5f60708","type":"deposit","amount_cents":5000,"status":"depix_sent","created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","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`) with the same fee arithmetic and the same fields as live today — the rates are the provider's and can move; the quoted pair is what counts — on unpayable placeholder addresses, 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":9900}}},"api_key_fee":{"summary":"API key — mandatory platform fee (fee_cents/fee_address)","value":{"response":{"withdrawalId":"wd-124","depositAddress":"lq1qq2v9wxkyz…","depositAmountInCents":9900,"payoutAmountInCents":9800,"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":9800,"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":9900,"payoutAmountInCents":9800,"totalDepositAmountInCents":10000,"split":{"address":"SANDBOX-LIQUID-FEE-ADDRESS-DO-NOT-PAY","amountCentavos":100},"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, missing WhatsApp verification, or the FIRST-WITHDRAW LOCK: until an account has landed one withdrawal (status `sent`), every withdrawal must be addressed to the same CPF/CNPJ that paid the account's first completed deposit. An account with no completed deposit carrying a document is not locked, and only a deposit settled after the mechanism's epoch can anchor one — an account whose history predates it is never locked. sk_test_ (sandbox) is exempt.","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"}}},"first_withdraw_tax_number_mismatch":{"value":{"response":{"errorMessage":"Seu primeiro saque precisa ir para o mesmo CPF/CNPJ que pagou seu primeiro depósito (final 8909). Depois desse saque, você pode sacar para qualquer chave Pix."},"error":{"code":"first_withdraw_tax_number_mismatch","message":"The account's first withdrawal must go to the same CPF/CNPJ that paid its first completed deposit. Later withdrawals are unrestricted.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"anchor_tax_number":"•••••••8909"}}}}}}}},"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-01T10:00:00.000Z","updated_at":"2026-07-01T10:00:00.000Z","liquid_txid":"abababababababababababababababababababababababababababababababab"}},"sandbox":{"summary":"Sandbox synthetic (fixed)","value":{"id":"sandbox_7ps_0011223344556677","type":"withdraw","amount_cents":10000,"status":"confirmed","created_at":"2026-01-01T00:00:00.000Z","updated_at":"2026-01-01T00:00:00.000Z","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 hosted payment page. Default rail (`payment_method: \"pix\"`): a PIX QR the payer pays in any bank app. Alternative rail (`payment_method: \"depix\"`): the payer sends DePix wallet-to-wallet on Liquid to the merchant's dedicated address — no PIX QR, no payer document, an optional merchant discount, and settlement observed on-chain (approved at the first confirmation, completed at the second). Requires scope `merchant_write` on the API-key path; a merchant profile is required. sk_test_ creates a sandbox checkout (non-payable placeholder payload — 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"}},"depix":{"summary":"DePix direct rail — no payer document, longer window","value":{"amount":9990,"payment_method":"depix","description":"Pedido #124","expires_in":1800,"expected_discount_pct":10}}}}}},"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-01T12:20:00.000Z","is_live":true,"payment_url":"https://pay.depixapp.com/chk_abc123","payment_method":"pix","pix":{"qr_code":"00020126580014br.gov.bcb.pix…"}}},"created_depix":{"summary":"DePix direct rail — pay-to-address instructions instead of a PIX QR","value":{"id":"chk_dpx123","status":"pending","amount":9990,"description":"Pedido #124","image_url":null,"expires_at":"2026-07-29T12:30:00.000Z","is_live":true,"payment_url":"https://pay.depixapp.com/chk_dpx123","payment_method":"depix","depix":{"address":"lq1qqw8re6vg9dqfazzsx4h9pkq6trxfmk8n0h0ykr7v9k8xn7pdrjq9m4v0rn3hhkq2c6jl2m8q7z0v","amount_cents":8991,"amount":"89.91","asset_id":"02f22f8d9c76ab41661a2729e4752e2c5d1a263012141b86ea98af5472df5189","uri":"liquidnetwork:lq1qqw8re6vg9dqfazzsx4h9pkq6trxfmk8n0h0ykr7v9k8xn7pdrjq9m4v0rn3hhkq2c6jl2m8q7z0v?amount=89.91&assetid=02f22f8d9c76ab41661a2729e4752e2c5d1a263012141b86ea98af5472df5189&depixid=chk_01jxxxxxxxxxxxxxxxxxxxxxx","discount_pct":10,"original_amount_cents":9990,"detected":false}}}}}}},"400":{"description":"Validation failure — the legacy per-field `response.errors[]` sibling is preserved — or a depix checkout requested from a merchant that does not have the direct DePix rail enabled, or the settlement provider REFUSING this request (`provider_refused`).\n\n**`provider_refused` is terminal — do not retry it.** The provider looked at this specific request (the payer's document, the destination address, the split) and declined; its own reason is in `response.errorMessage`. It is the opposite of 503 `service_unavailable`, which means the provider could not be reached or failed, and which IS worth retrying. Until 2026-08-04 both were reported as that 503, so an integration was told to retry a refusal that could never succeed.","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"}}}},"depix_not_enabled":{"value":{"response":{"errorMessage":"Este lojista não aceita pagamento direto em DePix."},"error":{"code":"depix_not_enabled","message":"This merchant does not accept direct DePix payments.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"provider_refused":{"value":{"response":{"errorMessage":"After a compliance review, we are unable to process deposits for this payer at this time."},"error":{"code":"provider_refused","message":"The payment provider refused this request. Retrying will not change the outcome.","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 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 negócio."},"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 (`idempotency_in_flight` — retry after `retry_after` seconds), or the depix rail cannot issue this charge right now: `depix_busy` (no free unique amount — fall back to PIX) / `discount_changed` (the merchant's discount moved under a stale page; `details` carries the current values).","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"}}},"depix_busy":{"value":{"response":{"errorMessage":"Muitos pagamentos DePix abertos neste valor agora. Tente em instantes ou pague com Pix."},"error":{"code":"depix_busy","message":"Too many open DePix checkouts at this price right now. Retry shortly or pay with Pix.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"discount_changed":{"value":{"response":{"errorMessage":"O desconto DePix deste lojista mudou. Atualize a página e confirme o novo valor."},"error":{"code":"discount_changed","message":"The merchant's DePix discount changed. Reload the page and confirm the new amount.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"discount_pct":15,"amount_cents":8492}}}}}}}},"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 PAID transactions for the same payer CPF/CNPJ (`payer_velocity_limit`: max 2 paid per sliding 30-minute window, deposits + checkouts combined; unpaid/expired QRs don't count). 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.\n\n**This list is paginated and `limit` caps at 100.** `stats` is computed over the WHOLE filter, not over the page, so `stats.total` is what tells you whether you have every row — summing `amount` across one page and calling it a total is how a reconciliation silently comes out short.\n\n**Held sales**: a sale whose money is not released yet stays in `processing` and carries `vault_hours` (the wait it was booked for) and, once the provider answers, `delay_until` (the release date). `?status=processing` with `vault_hours > 0` or a `delay_until` is the reconciliation query for \"paid, not settled yet\" — money received but not landed, and until it lands the provider can still reverse it (see `rejection_reasons`). On a sale the hold policy decided not to hold, `vault_hours` is `0` and `delay_until` is null; on one it never saw, `vault_hours` is null too (see the field description — null is not zero).","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. RFC 3339 (\"2026-08-01T00:00:00Z\"); the legacy \"2026-08-01 00:00:00\" shape is also accepted.","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"Filter: created_at <= this timestamp. RFC 3339 (\"2026-08-31T23:59:59Z\"); the legacy \"2026-08-31 23:59:59\" shape is also accepted.","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":{"summary":"A settled sale","value":{"checkouts":[{"id":"chk_abc123","status":"completed","amount":1500,"description":"Pedido #123","created_at":"2026-07-01T12:00:00.000Z","expires_at":"2026-07-01T12:20:00.000Z","is_live":1,"processing_at":"2026-07-01T12:01:00.000Z","approved_at":null,"metadata":"{\"order_id\":\"123\"}","product_name":null,"rejection_reasons":[],"payment_method":"pix","delay_until":null,"vault_hours":0}],"stats":{"total":1,"pending":0,"completed":1,"completed_amount":1500},"limit":50,"offset":0}},"held":{"summary":"A held sale — paid, money not released yet","description":"The payer paid, the sale sits in `processing`, and `delay_until` says when the money lands — the same RFC 3339 UTC instant as every other timestamp. `vault_hours` is what the sale was booked for at creation and answers WHETHER it is held; it is not a date and `created_at + vault_hours` is not one either (the wait runs from the payment, which is later). Before the provider answers, `delay_until` is null and there is simply no release date yet.","value":{"checkouts":[{"id":"chk_def456","status":"processing","amount":250000,"description":"Pedido #124","created_at":"2026-07-30T12:00:00.000Z","expires_at":"2026-07-30T12:20:00.000Z","is_live":1,"processing_at":"2026-07-30T12:03:00.000Z","approved_at":null,"metadata":null,"product_name":null,"rejection_reasons":[],"payment_method":"pix","delay_until":"2026-08-13T12:03:00.000Z","vault_hours":336}],"stats":{"total":1,"pending":0,"completed":0,"completed_amount":0},"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.\n\n`processing` means the payer's money reached us — it does NOT mean the money has landed in the merchant's wallet, and a checkout can sit there for days while a hold runs. It is also not a settled outcome: a sale in `processing` can still resolve to `cancelled` (a refunded or reversed payment — see `rejection_reasons`). `delay_until` says when the money lands (null until the provider answers with a date) and `vault_hours` says whether it was held at all. Releasing the order at `processing` or waiting for `completed` is the merchant's own policy; this endpoint publishes the facts either choice needs.","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-01T12:20:00.000Z","is_live":1,"created_at":"2026-07-01T12:00:00.000Z","processing_at":"2026-07-01T12:01:00.000Z","approved_at":null,"completed_at":"2026-07-01T12:02:00.000Z","cancelled_at":null,"blockchain_tx_id":"cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd","rejection_reasons":[],"payment_method":"pix","delay_until":null,"vault_hours":0}}},"held":{"summary":"Paid, money still held — same status, different answer","description":"The payer paid and the sale sits in `processing`, exactly like one settling in the next few seconds. `delay_until` is what separates the two, and it is the only date: `created_at + vault_hours` runs from the wrong instant (the wait starts at the payment) and always lands early. Whether to release the order now or wait for `completed` is the merchant's own policy — `processing` means the payer's money reached us, not that the outcome is settled: a sale in `processing` can still resolve to `cancelled` (a refunded or reversed payment — see `rejection_reasons`), so releasing before `completed` is a risk the merchant chooses to carry.","value":{"checkout":{"id":"chk_def456","status":"processing","amount":5990,"description":"Assinatura anual","image_url":null,"callback_url":"https://store.example.com/webhooks/depix","redirect_url":null,"metadata":{"order_id":"124"},"expires_at":"2026-07-30T12:20:00.000Z","is_live":1,"created_at":"2026-07-30T12:00:00.000Z","processing_at":"2026-07-30T12:03:00.000Z","approved_at":null,"completed_at":null,"cancelled_at":null,"blockchain_tx_id":null,"rejection_reasons":[],"payment_method":"pix","delay_until":"2026-08-13T12:03:00.000Z","vault_hours":336}}},"pending_depix":{"summary":"DePix direct rail, awaiting payment","description":"The depix rail creates no paired deposit, so the hold fields answer null — the shape described on `vault_hours` as \"no decision recorded\". The route always emits both keys; an example without them would document a second response shape that does not exist.","value":{"checkout":{"id":"chk_dpx123","status":"pending","amount":9990,"description":"Pedido #124","image_url":null,"callback_url":null,"redirect_url":null,"metadata":null,"expires_at":"2026-07-29T12:30:00.000Z","is_live":1,"created_at":"2026-07-29T12:00:00.000Z","processing_at":null,"approved_at":null,"completed_at":null,"cancelled_at":null,"blockchain_tx_id":null,"rejection_reasons":[],"payment_method":"depix","delay_until":null,"vault_hours":null,"depix":{"address":"lq1qqw8re6vg9dqfazzsx4h9pkq6trxfmk8n0h0ykr7v9k8xn7pdrjq9m4v0rn3hhkq2c6jl2m8q7z0v","amount_cents":8991,"amount":"89.91","asset_id":"02f22f8d9c76ab41661a2729e4752e2c5d1a263012141b86ea98af5472df5189","uri":"liquidnetwork:lq1qqw8re6vg9dqfazzsx4h9pkq6trxfmk8n0h0ykr7v9k8xn7pdrjq9m4v0rn3hhkq2c6jl2m8q7z0v?amount=89.91&assetid=02f22f8d9c76ab41661a2729e4752e2c5d1a263012141b86ea98af5472df5189&depixid=chk_01jxxxxxxxxxxxxxxxxxxxxxx","discount_pct":10,"original_amount_cents":9990,"detected":false}}}}}}}},"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-01T00:00:00.000Z"}}}}}},"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 negócio 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-22T12:00:00.000Z","last_activity_at":"2026-07-22T12:00:00.000Z","closed_reason":null,"closed_at":null,"rating":null,"rated_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-22T12:00:00.000Z","last_activity_at":"2026-07-22T13:00:00.000Z","closed_reason":null,"closed_at":null,"rating":null,"rated_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-22T12:00:00.000Z","last_activity_at":"2026-07-22T13:00:00.000Z","closed_reason":null,"closed_at":null,"rating":null,"rated_at":null},"messages":[{"id":"tmsg_1","sender":"user","body":"Paguei o PIX há 1h e o DePix não chegou.","created_at":"2026-07-22T12:00:00.000Z"},{"id":"tmsg_2","sender":"admin","body":"Olá! Já localizamos seu depósito, será creditado em instantes.","created_at":"2026-07-22T13:00:00.000Z"}]}}}}}},"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-22T14:00:00.000Z"},"ticket":{"id":"tkt_ab12cd34ef","opener_type":"human","status":"awaiting_reply","subject":"Não recebi meu depósito","category":"other","created_at":"2026-07-22T12:00:00.000Z","last_activity_at":"2026-07-22T14:00:00.000Z","closed_reason":null,"closed_at":null,"rating":null,"rated_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-22T14:05:00.000Z","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-22T12:00:00.000Z","last_activity_at":"2026-07-22T14:05:00.000Z","closed_reason":null,"closed_at":null,"rating":null,"rated_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-22T12:00:00.000Z","last_activity_at":"2026-07-22T13:00:00.000Z","closed_reason":"user","closed_at":"2026-07-22T15:00:00.000Z","rating":null,"rated_at":null}}}}}}},"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/tickets/{id}/rating":{"post":{"tags":["support"],"operationId":"rateTicket","summary":"Rate the support you received","description":"Scores a CLOSED ticket from 0 (worst) to 10 (best). Write-once: the second call returns 409 already_rated, so the first score is never silently overwritten. Rating an open ticket returns 409 ticket_open. This records a datapoint only — it does not reopen the ticket, does not count as a message, and does not change last_activity_at. 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":{"type":"object","required":["rating"],"additionalProperties":false,"properties":{"rating":{"type":"integer","minimum":0,"maximum":10,"description":"0 = worst, 10 = best."}}},"examples":{"happy":{"value":{"rating":10}}}}}},"responses":{"200":{"description":"Rating recorded.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketResponse"},"examples":{"rated":{"value":{"ticket":{"id":"tkt_ab12cd34ef","opener_type":"human","status":"closed","subject":"Não recebi meu depósito","category":"other","created_at":"2026-07-22T12:00:00.000Z","last_activity_at":"2026-07-22T13:00:00.000Z","closed_reason":"admin","closed_at":"2026-07-22T15:00:00.000Z","rating":10,"rated_at":"2026-07-22T15:04:00.000Z"}}}}}}},"400":{"description":"The rating is missing or outside 0–10.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"validation_error":{"value":{"response":{"errorMessage":"Nota deve ser um número inteiro de 0 a 10."},"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"}}}}}}},"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 still open, or it has already been rated.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"ticket_open":{"value":{"response":{"errorMessage":"Só é possível avaliar um ticket encerrado."},"error":{"code":"ticket_open","message":"Only a closed ticket can be rated.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"already_rated":{"value":{"response":{"errorMessage":"Este ticket já foi avaliado."},"error":{"code":"already_rated","message":"This ticket has already been rated.","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,"kind":"product","due_date":null,"recurrence":null,"late_fine_bps":0,"late_interest_monthly_bps":0,"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 negócio."},"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":"kind","in":"query","required":false,"description":"Row kind filter. DEFAULTS to 'product' so pre-charges consumers never see charges; 'charge' lists charges (with charge_state), 'all' both.","schema":{"type":"string","enum":["product","charge","all"],"default":"product"}},{"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-01T12:00:00.000Z","position":null,"kind":"product","due_date":null,"recurrence":null,"late_fine_bps":0,"late_interest_monthly_bps":0,"total_checkouts":3,"completed_checkouts":2,"completed_amount":1400,"settled_count":2,"processing_count":0}],"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-01T12:00:00.000Z","updated_at":"2026-07-01T12:00:00.000Z"},"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-01T12:00:00.000Z","expires_at":"2026-07-01T12:20:00.000Z","processing_at":"2026-07-01T12:01:00.000Z","completed_at":"2026-07-01T12:02:00.000Z"}],"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 AND of charge pages (/c/{id}). For charges the amount is computed per visit (base + late fees for the current FIFO cycle — see ChargeState) and the settled cycle is stamped into metadata.charge_cycle. Optional body: payer metadata and payer_tax_number.\n\n**Errors on this operation are payer-scoped.** The caller is an anonymous third party paying a merchant, so an error is only allowed to keep its `response.errorMessage` and its `error.details` when it describes the payer, the payer's input, or a fact about the thing being paid — which is every code documented below. Refusals that belong to the MERCHANT'S account (receive limits, onboarding gates, account configuration) answer a fixed neutral message (\"Não foi possível gerar o pagamento. Fale com o vendedor.\", or \"…agora. Tente novamente em alguns minutos.\" for a 5xx) with `error.details` OMITTED. `error.code` is always the real one. Do not build a payer flow that reads `error.details` from a code not listed here: it is withheld by design, and the same call authenticated as the merchant (POST /api/checkouts) returns the full numbers.","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)."},"payment_method":{"$ref":"#/components/schemas/PaymentMethod","default":"pix","description":"Rail to charge on. Omit it (or send \"pix\") for the PIX QR flow. \"depix\" requires the merchant to have the direct DePix rail enabled, otherwise the request is rejected with 400 `depix_not_enabled`."},"expected_discount_pct":{"type":"integer","description":"The DePix discount percentage the page showed the payer, 0–90. Send it on the depix rail to make a stale page fail loudly: if the merchant's current discount differs, the request is rejected with 409 `discount_changed` carrying the fresh values instead of charging a different price.","minimum":0,"maximum":90},"payer_tax_number":{"type":"string","description":"CPF/CNPJ of the payer. Required on the pix rail — omitting it returns 400 `tax_number_required`. Ignored on the depix rail."}}},"examples":{"with_tax":{"value":{"payer_tax_number":"52998224725"}},"depix":{"summary":"Pay this product directly in DePix","value":{"payment_method":"depix","expected_discount_pct":10}}}}}},"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-01T12:20:00.000Z","is_live":true,"payment_url":"https://pay.depixapp.com/chk_pub123","payment_method":"pix","pix":{"qr_code":"00020126580014br.gov.bcb.pix…"}}},"created_depix":{"summary":"DePix direct rail","value":{"id":"chk_pub124","status":"pending","amount":9990,"description":null,"expires_at":"2026-07-29T12:30:00.000Z","is_live":true,"payment_url":"https://pay.depixapp.com/chk_pub124","payment_method":"depix","depix":{"address":"lq1qqw8re6vg9dqfazzsx4h9pkq6trxfmk8n0h0ykr7v9k8xn7pdrjq9m4v0rn3hhkq2c6jl2m8q7z0v","amount_cents":8991,"amount":"89.91","asset_id":"02f22f8d9c76ab41661a2729e4752e2c5d1a263012141b86ea98af5472df5189","uri":"liquidnetwork:lq1qqw8re6vg9dqfazzsx4h9pkq6trxfmk8n0h0ykr7v9k8xn7pdrjq9m4v0rn3hhkq2c6jl2m8q7z0v?amount=89.91&assetid=02f22f8d9c76ab41661a2729e4752e2c5d1a263012141b86ea98af5472df5189&depixid=chk_01jxxxxxxxxxxxxxxxxxxxxxx","discount_pct":10,"original_amount_cents":9990,"detected":false}}}}}}},"400":{"description":"Invalid metadata, missing payer tax number, or a depix checkout requested from a merchant that does not accept the direct DePix rail.","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"}}},"depix_not_enabled":{"value":{"response":{"errorMessage":"Este lojista não aceita pagamento direto em DePix."},"error":{"code":"depix_not_enabled","message":"This merchant does not accept direct DePix payments.","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"}}}}}}},"409":{"description":"Charge already paid (one-time), a payment is settling, an un-expired QR already holds the only remaining cycle, or the depix rail cannot issue this charge right now (`depix_busy` — fall back to PIX; `discount_changed` — the merchant's discount moved under a stale page).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"charge_already_paid":{"value":{"response":{"errorMessage":"Esta cobrança já foi paga."},"error":{"code":"charge_already_paid","message":"This charge has already been paid.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"charge_payment_in_progress":{"value":{"response":{"errorMessage":"Já existe um pagamento em processamento para esta cobrança. Aguarde a confirmação."},"error":{"code":"charge_payment_in_progress","message":"A payment for this charge is already being processed.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"charge_payment_pending":{"value":{"response":{"errorMessage":"Já existe um código de pagamento em aberto para esta cobrança. Aguarde alguns minutos e tente novamente."},"error":{"code":"charge_payment_pending","message":"An unpaid payment code is still open for this charge.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"depix_busy":{"value":{"response":{"errorMessage":"Muitos pagamentos DePix abertos neste valor agora. Tente em instantes ou pague com Pix."},"error":{"code":"depix_busy","message":"Too many open DePix checkouts at this price right now. Retry shortly or pay with Pix.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"discount_changed":{"value":{"response":{"errorMessage":"O desconto DePix deste lojista mudou. Atualize a página e confirme o novo valor."},"error":{"code":"discount_changed","message":"The merchant's DePix discount changed. Reload the page and confirm the new amount.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"discount_pct":15,"amount_cents":8492}}}}}}}},"429":{"description":"Rate limited, or too many PAID transactions for the same payer CPF/CNPJ (`payer_velocity_limit`: max 2 paid per sliding 30-minute window, deposits + checkouts combined; unpaid/expired QRs don't count). 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).\n\n**Errors on this operation are payer-scoped.** The caller is an anonymous third party paying a merchant, so an error is only allowed to keep its `response.errorMessage` and its `error.details` when it describes the payer, the payer's input, or a fact about the thing being paid — which is every code documented below. Refusals that belong to the MERCHANT'S account (receive limits, onboarding gates, account configuration) answer a fixed neutral message (\"Não foi possível gerar o pagamento. Fale com o vendedor.\", or \"…agora. Tente novamente em alguns minutos.\" for a 5xx) with `error.details` OMITTED. `error.code` is always the real one. Do not build a payer flow that reads `error.details` from a code not listed here: it is withheld by design, and the same call authenticated as the merchant (POST /api/checkouts) returns the full numbers.","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"}},"depix":{"summary":"DePix direct rail — no payer document","value":{"amount":9990,"payment_method":"depix","expected_discount_pct":10}},"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-01T12:20:00.000Z","is_live":true,"payment_url":"https://pay.depixapp.com/chk_mrc123","payment_method":"pix","pix":{"qr_code":"00020126580014br.gov.bcb.pix…"}}},"created_depix":{"summary":"DePix direct rail","value":{"id":"chk_mrc124","status":"pending","amount":9990,"description":null,"expires_at":"2026-07-29T12:30:00.000Z","is_live":true,"payment_url":"https://pay.depixapp.com/chk_mrc124","payment_method":"depix","depix":{"address":"lq1qqw8re6vg9dqfazzsx4h9pkq6trxfmk8n0h0ykr7v9k8xn7pdrjq9m4v0rn3hhkq2c6jl2m8q7z0v","amount_cents":8991,"amount":"89.91","asset_id":"02f22f8d9c76ab41661a2729e4752e2c5d1a263012141b86ea98af5472df5189","uri":"liquidnetwork:lq1qqw8re6vg9dqfazzsx4h9pkq6trxfmk8n0h0ykr7v9k8xn7pdrjq9m4v0rn3hhkq2c6jl2m8q7z0v?amount=89.91&assetid=02f22f8d9c76ab41661a2729e4752e2c5d1a263012141b86ea98af5472df5189&depixid=chk_01jxxxxxxxxxxxxxxxxxxxxxx","discount_pct":10,"original_amount_cents":9990,"detected":false}}}}}}},"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) — all legacy-envelope only. A depix charge against a merchant without the direct DePix rail enabled answers `depix_not_enabled` in the dual envelope.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"description":"Either the legacy-only envelope (validation/cart failures) or the dual envelope (`depix_not_enabled`).","oneOf":[{"$ref":"#/components/schemas/LegacyErrorEnvelope"},{"$ref":"#/components/schemas/ErrorEnvelope"}]},"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."}}},"depix_not_enabled":{"value":{"response":{"errorMessage":"Este lojista não aceita pagamento direto em DePix."},"error":{"code":"depix_not_enabled","message":"This merchant does not accept direct DePix payments.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}}}}}},"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. Graduation follows verification: prove a domain via POST /api/agents/verify-domain, then poll GET /api/agents/status."},"error":{"code":"graduation_pending","message":"This capability unlocks after the account graduates. Graduation follows verification: prove a domain via POST /api/agents/verify-domain, then poll GET /api/agents/status.","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."}}}}}}},"409":{"description":"The depix rail cannot issue this charge right now: `depix_busy` (no free unique amount left — fall back to PIX) or `discount_changed` (the merchant's discount moved under a stale page; `details` carries the current values).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"depix_busy":{"value":{"response":{"errorMessage":"Muitos pagamentos DePix abertos neste valor agora. Tente em instantes ou pague com Pix."},"error":{"code":"depix_busy","message":"Too many open DePix checkouts at this price right now. Retry shortly or pay with Pix.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors"}}},"discount_changed":{"value":{"response":{"errorMessage":"O desconto DePix deste lojista mudou. Atualize a página e confirme o novo valor."},"error":{"code":"discount_changed","message":"The merchant's DePix discount changed. Reload the page and confirm the new amount.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"discount_pct":15,"amount_cents":8492}}}}}}}},"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 PAID transactions for the same payer CPF/CNPJ (`payer_velocity_limit`: max 2 paid per sliding 30-minute window, deposits + checkouts combined; unpaid/expired QRs don't count). 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. The payment payload (`pix` or `depix`, per `payment_method`) is present only while pending. On the depix rail, `depix.detected` flips to true as soon as a matching payment is seen on the network — the status still only moves at the first confirmation.","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-01T12:20:00.000Z","redirect_url":null,"is_test":false,"payment_method":"pix","pix":{"qr_code":"00020126580014br.gov.bcb.pix…"}}},"pending_depix":{"summary":"DePix direct rail, payment already seen on the network","value":{"id":"chk_pub124","status":"pending","amount":9990,"currency":"BRL","description":null,"image_url":null,"merchant_name":"Loja Teste","merchant_username":"loja-teste","merchant_slug":"loja-teste","remaining_seconds":1655,"expires_at":"2026-07-29T12:30:00.000Z","redirect_url":null,"is_test":false,"payment_method":"depix","depix":{"address":"lq1qqw8re6vg9dqfazzsx4h9pkq6trxfmk8n0h0ykr7v9k8xn7pdrjq9m4v0rn3hhkq2c6jl2m8q7z0v","amount_cents":8991,"amount":"89.91","asset_id":"02f22f8d9c76ab41661a2729e4752e2c5d1a263012141b86ea98af5472df5189","uri":"liquidnetwork:lq1qqw8re6vg9dqfazzsx4h9pkq6trxfmk8n0h0ykr7v9k8xn7pdrjq9m4v0rn3hhkq2c6jl2m8q7z0v?amount=89.91&assetid=02f22f8d9c76ab41661a2729e4752e2c5d1a263012141b86ea98af5472df5189&depixid=chk_01jxxxxxxxxxxxxxxxxxxxxxx","discount_pct":10,"original_amount_cents":9990,"detected":true}}}}}}},"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":{"requires":"domain_proof","verify_domain_endpoint":"POST /api/agents/verify-domain","allowed_tlds_endpoint":"GET /api/agents/domain-tlds"},"pacing":{"first_deposit_max_cents":10000,"unverified_per_tx_max_cents":10000,"inter_deposit_delay_hours":24,"payer_velocity":{"max_per_window":2,"window_minutes":30},"verified_per_tx_deposit_max_cents":600000,"verified_per_tx_withdraw_send_max_cents":600000,"verified_per_tx_withdraw_receive_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 by one of the two anti-farm caps: registrations from this IP in 24h (`rate_limited`, `details.scope` = \"agent-register-daily\"), or agent accounts registered under this OPERATOR TOKEN in a rolling 24h window (`operator_register_cap_exceeded`, default 5). Retry after `retry_after` seconds (also in the Retry-After header); an operator cap you did not cause means the token has leaked and should be revoked.","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":3600,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"agent-register-daily"}}}},"operator_register_cap_exceeded":{"value":{"response":{"errorMessage":"Este operador já registrou 5 contas-agente nas últimas 24 horas. Aguarde a janela virar e tente de novo. Se não foi você que criou essas contas, o token do operador vazou — fale com o suporte para revogá-lo."},"error":{"code":"operator_register_cap_exceeded","message":"This operator token has already registered its maximum number of agent accounts in the last 24 hours. Wait for the window to roll off and retry. If you did not create those accounts the token has leaked — ask the operator to revoke it through support.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","retry_after":47520,"docs_url":"https://depixapp.com/docs/en/#errors","details":{"scope":"agent-register-operator","max_per_window":5,"window_hours":24}}}}}}}},"503":{"description":"A registration guard could not run, so it refused: the nonce anti-replay store, or the per-IP cap that shares it, was unavailable. Both fail 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 AND, for an agent account, the merchant tools — the domain proof stands in for the document round trip a human does. 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","verified":true}}}}}},"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. Graduation follows verification: prove a domain via POST /api/agents/verify-domain, then poll GET /api/agents/status."},"error":{"code":"graduation_pending","message":"This capability unlocks after the account graduates. Graduation follows verification: prove a domain via POST /api/agents/verify-domain, then poll GET /api/agents/status.","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/depix-pay":{"post":{"tags":["agents"],"operationId":"setAgentDepixRail","summary":"Turn the DePix direct rail on or off","description":"Registers (or removes) the dedicated confidential Liquid address the agent's merchant is paid at on the DePix rail, so its checkouts can be paid in DePix on-chain instead of only by Pix. Auth is the agent keypair signature — the human twin of this endpoint is password-gated dashboard surface, which an agent account can never satisfy. Enabling requires the address AND its blinding private key: the key is proof of possession (the address is rebuilt from it and must match) and it is the ONLY thing that lets us read the amounts arriving there. It is sealed at rest and never returned. The address must be confidential (lq1…) and exclusive — the payout and split addresses are refused. Disabling takes no key and deletes the grant; an address with a DePix payment still in flight keeps its key until that checkout is terminal. Requires a verified account (for an agent, that is the domain proof) and rejects a suspended merchant.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDepixPayRequest"},"examples":{"enable":{"value":{"enabled":true,"address":"lq1qq…","blinding_key":"3f9a…","derivation_index":12}},"disable":{"value":{"enabled":false}}}}}},"responses":{"200":{"description":"The rail's new state.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDepixPayResponse"},"examples":{"enabled":{"value":{"response":{"depix_pay_enabled":true,"depix_pay_address":"lq1qq…","depix_derivation_index":12,"depix_discount_pct":0}}},"disabled":{"value":{"response":{"depix_pay_enabled":false,"view_key_deleted":true,"pending_addresses":0}}}}}}},"400":{"description":"Malformed body (validation_error with details.field), a non-confidential or undecodable address (depix_address_unsupported), an address that is not exclusive or is already registered (depix_address_conflict), or a blinding key that does not belong to the address (invalid_blinding_key).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unsupported":{"value":{"response":{"errorMessage":"O endereço de recebimento DePix precisa ser um endereço Liquid confidencial (lq1…)."},"error":{"code":"depix_address_unsupported","message":"The DePix receiving address must be a confidential Liquid address (lq1…).","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"field":"address"}}}},"bad_key":{"value":{"response":{"errorMessage":"A chave de visão não corresponde ao endereço informado."},"error":{"code":"invalid_blinding_key","message":"The blinding key does not match the supplied address.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"field":"blinding_key"}}}}}}}},"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), or the account is not verified yet (verification_required — for an agent, prove a domain).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"unverified":{"value":{"response":{"errorMessage":"This operation requires a verified account. Complete verification first (GET /api/verification lists what is missing)."},"error":{"code":"verification_required","message":"This operation requires a verified account. Complete verification first (GET /api/verification lists what is missing).","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"next_action":{"kind":"call_tool","tool":"get_onboarding_status"}}}}}}}}},"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":"The rail's key-encryption key is not configured, so no view key could be stored and read back; the nonce anti-replay store is 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":{"rail_dark":{"value":{"response":{"errorMessage":"Recebimento em DePix indisponível no momento. Tente novamente em instantes."},"error":{"code":"service_unavailable","message":"A dependency is unavailable. Try again shortly.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","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, graduation state, and the account's keys. `graduation.blocked_on` is the actionable field — \"domain_proof\" means the account must prove a domain, \"gate_review\" means it is verified but not graduated yet. 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":{"unverified":{"summary":"Not verified yet — the agent's own move","value":{"response":{"account_status":"active","graduated":false,"graduation":{"blocked_on":"domain_proof"},"keys":[{"id":"k_1","prefix":"sk_live_","is_live":true,"starter":true,"scopes":"wallet_read wallet_write","revoked_at":null}]}}},"awaiting_review":{"summary":"Verified, graduation not landed yet — just poll","value":{"response":{"account_status":"active","graduated":false,"graduation":{"blocked_on":"gate_review"},"keys":[{"id":"k_1","prefix":"sk_live_","is_live":true,"starter":true,"scopes":"wallet_read wallet_write","revoked_at":null}]}}},"graduated":{"summary":"Graduated — full sk_live_ available","value":{"response":{"account_status":"active","graduated":true,"graduation":{"blocked_on":null},"keys":[{"id":"k_1","prefix":"sk_live_","is_live":true,"starter":false,"scopes":"merchant_read merchant_write 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/webhook-logs":{"get":{"tags":["merchant"],"operationId":"listWebhookLogs","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 audit of what was delivered, retried or failed. Bodies are omitted in the list; fetch one log by id for the payloads. Requires scope `merchant_read` on the API-key path. (An agent account uses the keypair-signed twin at GET /api/agents/webhook-logs.)","x-required-scope":"merchant_read","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://store.example.com/hook","status_code":200,"error":null,"attempt":1,"sent_at":"2026-07-22T12:00:00.000Z"},{"id":"wlog_2","checkout_id":null,"event":"deposit.depix_sent","url":"https://store.example.com/hook","status_code":null,"error":"fetch timeout","attempt":2,"sent_at":"2026-07-22T11:58:00.000Z"}]}},"empty":{"value":{"logs":[]}}}}}},"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 `merchant_read`, 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":{"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"}}}},"no_merchant":{"value":{"response":{"errorMessage":"Você não possui conta de negócio."},"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"}}}}}}},"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/webhook-logs/{id}":{"get":{"tags":["merchant"],"operationId":"getWebhookLog","summary":"Get one webhook delivery log","description":"Full detail of one delivery attempt, including the signed request payload sent and the response body received. Ownership enforced: another account's log answers 404. Requires scope `merchant_read` on the API-key path.","x-required-scope":"merchant_read","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://store.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-22T11:00:00.000Z\",\"updated_at\":\"2026-07-22T12:00:00.000Z\",\"rejection_reasons\":[],\"event_id\":\"evt_1\"}}","response_body":"{\"ok\":true}","error":null,"attempt":1,"next_retry_at":null,"sent_at":"2026-07-22T12:00:00.000Z"}}}}}}},"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 `merchant_read`, 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":{"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"}}}},"no_merchant":{"value":{"response":{"errorMessage":"Você não possui conta de negócio."},"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"}}}}}}},"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. 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/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-22T12:00:00.000Z"},{"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-22T11:58:00.000Z"}]}},"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 negócio."},"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-22T11:00:00.000Z\",\"updated_at\":\"2026-07-22T12:00:00.000Z\",\"rejection_reasons\":[],\"event_id\":\"evt_1\"}}","response_body":"{\"ok\":true}","error":null,"attempt":1,"next_retry_at":null,"sent_at":"2026-07-22T12:00:00.000Z"}}}}}}},"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 negócio."},"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/verification":{"get":{"tags":["account"],"operationId":"getVerification","summary":"Read account verification state","description":"Whether this account can use the merchant tools (checkouts and products), and exactly what is missing if it cannot. Send a Bearer JWT or an sk_ API key; NO scope is required. Read-only. Two proofs exist and `method` says which one applies. A human account proves ownership of a bank account: receive at least `requirements.deposit_cents` from one CPF/CNPJ and withdraw at least `requirements.withdraw_cents` back to the SAME document, both inside one window of `requirements.max_days_between_legs` days, and with the account at least `requirements.min_account_age_days` old (0 today — no waiting period). The withdrawal is measured in DePix LEAVING the wallet — the amount you enter — not in what lands in the bank, so it is a number you control. An agent account proves a domain instead (POST /api/agents/verify-domain). `steps` is the checklist in the order it must be done, including converting a little DePix to L-BTC to pay the Liquid network fee — without it a withdrawal cannot be broadcast at all. Render `steps` as given. Only movements made after this feature went live count — older history never verifies an account by itself. Verification is INDEPENDENT of how much the account may receive: it unlocks tools, never a limit. Poll this while the customer completes the steps, then call POST /api/verification.","security":[],"responses":{"200":{"description":"Current verification state.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationStatusResponse"},"examples":{"pending":{"summary":"Received, still has to withdraw back","value":{"verified":false,"verified_at":null,"whatsapp_verified":1,"method":"round_trip","enabled":true,"eligible":false,"requirements":{"deposit_cents":9500,"withdraw_cents":8500,"min_account_age_days":0,"max_days_between_legs":30,"domain_proof":false},"progress":{"account_age_days":9,"account_age_ok":true,"deposited_cents":9500,"withdrawn_cents":0,"deposit_leg_ok":true,"withdraw_leg_ok":false,"tax_number":null,"tax_number_locked":false,"domain":null},"remaining":{"deposit_cents":0,"withdraw_cents":8500,"account_age_days":0},"missing":["withdraw_leg"],"unlocks":["checkouts","products"],"lbtc_fuel":{"min_depix_cents":500,"balance_known":false,"sufficient":null},"steps":[{"id":"deposit","state":"done","target_cents":9500,"remaining_cents":0,"target_days":null,"remaining_days":null},{"id":"convert_lbtc","state":"unknown","target_cents":500,"remaining_cents":null,"target_days":null,"remaining_days":null},{"id":"withdraw","state":"pending","target_cents":8500,"remaining_cents":8500,"target_days":null,"remaining_days":null}]}},"verified":{"summary":"Already verified","value":{"verified":true,"verified_at":"2026-08-14T18:03:11.000Z","whatsapp_verified":1,"method":"round_trip","enabled":true,"eligible":false,"requirements":{"deposit_cents":9500,"withdraw_cents":8500,"min_account_age_days":0,"max_days_between_legs":30,"domain_proof":false},"progress":{"account_age_days":41,"account_age_ok":true,"deposited_cents":0,"withdrawn_cents":0,"deposit_leg_ok":true,"withdraw_leg_ok":true,"tax_number":"•••••••8909","tax_number_locked":true,"domain":null},"remaining":{"deposit_cents":0,"withdraw_cents":0,"account_age_days":0},"missing":[],"unlocks":["checkouts","products"],"lbtc_fuel":{"min_depix_cents":500,"balance_known":false,"sufficient":null},"steps":[{"id":"deposit","state":"done","target_cents":9500,"remaining_cents":0,"target_days":null,"remaining_days":null},{"id":"convert_lbtc","state":"done","target_cents":500,"remaining_cents":null,"target_days":null,"remaining_days":null},{"id":"withdraw","state":"done","target_cents":8500,"remaining_cents":0,"target_days":null,"remaining_days":null}]}}}}}},"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 account is 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. 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"}}}}}}}}},"post":{"tags":["account"],"operationId":"claimVerification","summary":"Verify the account","description":"Evaluates the proof and, when everything is satisfied, unlocks the merchant tools. No request body. Send a Bearer JWT or an sk_ API key; NO scope is required. Idempotent: an already-verified account answers 200. On 409 the reason is in `error.code` and the detail in `error.details.missing` / `error.details.remaining` — the same values GET returns. A CPF/CNPJ verifies exactly one account: once bound it can never verify another (`verification_tax_number_in_use`).","security":[],"responses":{"200":{"description":"The account is verified (just now, or already was).","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationStatusResponse"},"examples":{"verified":{"value":{"verified":true,"verified_at":"2026-08-14T18:03:11.000Z","whatsapp_verified":1,"method":"round_trip","enabled":true,"eligible":true,"requirements":{"deposit_cents":9500,"withdraw_cents":8500,"min_account_age_days":0,"max_days_between_legs":30,"domain_proof":false},"progress":{"account_age_days":9,"account_age_ok":true,"deposited_cents":9500,"withdrawn_cents":8500,"deposit_leg_ok":true,"withdraw_leg_ok":true,"tax_number":"•••••••8909","tax_number_locked":false,"domain":null},"remaining":{"deposit_cents":0,"withdraw_cents":0,"account_age_days":0},"missing":[],"unlocks":["checkouts","products"],"lbtc_fuel":{"min_depix_cents":500,"balance_known":false,"sufficient":null},"steps":[{"id":"deposit","state":"done","target_cents":9500,"remaining_cents":0,"target_days":null,"remaining_days":null},{"id":"convert_lbtc","state":"done","target_cents":500,"remaining_cents":null,"target_days":null,"remaining_days":null},{"id":"withdraw","state":"done","target_cents":8500,"remaining_cents":0,"target_days":null,"remaining_days":null}]}}}}}},"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 account is 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"}}}}}}},"409":{"description":"Not verified. `verification_requirements_not_met`: something is still missing (see details). `verification_tax_number_in_use`: that document already verified another account.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"requirements":{"value":{"response":{"errorMessage":"Sua conta ainda não cumpre os requisitos de verificação."},"error":{"code":"verification_requirements_not_met","message":"The account does not meet the verification requirements yet. details.missing lists what is left and details.remaining how much.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"missing":["withdraw_leg"],"remaining":{"deposit_cents":0,"withdraw_cents":8500,"account_age_days":0}}}}},"document_in_use":{"value":{"response":{"errorMessage":"Este CPF/CNPJ já verificou outra conta. Um documento verifica uma conta só."},"error":{"code":"verification_tax_number_in_use","message":"This CPF/CNPJ has already verified another account. One document verifies one account.","request_id":"gru1::iad1::v9x4k-1751476800000-abc123","docs_url":"https://depixapp.com/docs/en/#errors","details":{"missing":["tax_number_in_use"],"remaining":{"deposit_cents":0,"withdraw_cents":0,"account_age_days":0}}}}}}}}},"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"}}}}}}},"503":{"description":"Automatic verification is switched off platform-wide.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"},"examples":{"off":{"value":{"response":{"errorMessage":"A verificação automática está indisponível no momento. Fale com o suporte."},"error":{"code":"verification_unavailable","message":"Account verification is temporarily unavailable. Try again later or contact support.","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-01T12:00:00.000Z","updated_at":"2026-07-01T12:00:00.000Z","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-01T12:00:00.000Z","updated_at":"2026-07-01T12:00:00.000Z","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-01T12:00:00.000Z","updated_at":"2026-07-01T12:00:00.000Z","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-01T12:00:00.000Z","updated_at":"2026-07-01T12:00:00.000Z","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-01T12:00:00.000Z","updated_at":"2026-07-01T12:00:00.000Z","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-01T12:00:00.000Z","updated_at":"2026-07-01T12:00:00.000Z","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-01T12:00:00.000Z","updated_at":"2026-07-01T12:34:56.000Z","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-01T12:00:00.000Z","updated_at":"2026-07-01T12:00:00.000Z","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-01T12:00:00.000Z","updated_at":"2026-07-01T12:00:00.000Z","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-01T12:00:00.000Z","updated_at":"2026-07-01T12:00:00.000Z","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-01T12:00:00.000Z","updated_at":"2026-07-01T12:00:00.000Z","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-01T10:00:00.000Z","updated_at":"2026-07-01T10:00:00.000Z","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-01T10:00:00.000Z","updated_at":"2026-07-01T10:00:00.000Z","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-01T10:00:00.000Z","updated_at":"2026-07-01T10:00:00.000Z","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-01T10:00:00.000Z","updated_at":"2026-07-01T10:00:00.000Z","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-01T10:00:00.000Z","updated_at":"2026-07-01T10:00:00.000Z","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-01T10:00:00.000Z","updated_at":"2026-07-01T10:00:00.000Z","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-01T10:00:00.000Z","updated_at":"2026-07-01T10:00:00.000Z","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","is_live":true,"amount":1500,"product_id":null,"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). On the depix rail it means the payer's transaction got its FIRST confirmation and was matched to this checkout — the money is already in the merchant's wallet, so this is the safe point to release goods. 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","is_live":true,"amount":1500,"payment_method":"depix","amount_received":1349,"discount_pct":10,"product_id":null,"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). On the depix rail it means the payer's transaction reached two confirmations. 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","is_live":true,"amount":1500,"product_id":null,"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","is_live":true,"amount":1500,"product_id":null,"cancelled_at":"2026-07-01T12:05:00.000Z","rejection_reasons":["PAYER_MISMATCH"],"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 expires unpaid (cron sweep). On the depix rail this lands 15 minutes AFTER expires_at — the grace window that lets a transaction broadcast in the final seconds still confirm and settle. It fires once, and `expired` stays terminal. 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","is_live":true,"amount":1500,"product_id":null,"event_id":"evt_c1d2e3f4a5c0"}}}}}}},"responses":{"200":{"description":"Any 2xx acknowledges the delivery; anything else (or a timeout) schedules a retry."}}}},"checkout.unmatched_payment":{"post":{"summary":"DePix received without a matching checkout","description":"Sent when a DePix payment lands on the merchant's direct-rail address and cannot be tied to a checkout (wrong amount typed, payment after the grace window, several candidate checkouts, or a second payment for an already settled one). The funds are in the merchant's wallet; nothing is credited automatically, and the receipt is listed for manual reconciliation in the merchant app. Delivered to the merchant'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 checkout.unmatched_payment event.","required":["event","data"],"additionalProperties":false,"properties":{"event":{"type":"string","enum":["checkout.unmatched_payment"],"description":"Event name — fixed for this webhook."},"data":{"$ref":"#/components/schemas/UnmatchedPaymentWebhookData"}}},"examples":{"checkout_unmatched_payment":{"value":{"event":"checkout.unmatched_payment","data":{"id":"dout_9f8e7d6c5b4a","type":"depix_output","status":"unattributed","amount_cents":8997,"txid":"abababababababababababababababababababababababababababababababab","vout":1,"first_seen_at":"2026-07-29T12:07:00.000Z","event_id":"evt_c1d2e3f4a5c1"}}}}}}},"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 (a verified account that is not suspended). 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-16T12:34:56.000Z","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","verification_required","step_up_required","live_access_required","whatsapp_verification_required","withdraw_disabled","external_wallet_disabled","first_withdraw_tax_number_mismatch","sandbox_only","validation_error","password_required","tax_number_required","amount_out_of_range","account_limit_exceeded","key_limit_exceeded","provider_refused","attachment_too_large","not_found","conflict","charge_already_paid","depix_not_enabled","depix_busy","depix_address_unsupported","depix_address_conflict","invalid_blinding_key","discount_changed","charge_payment_in_progress","charge_payment_pending","agent_pubkey_exists","email_in_use","account_exists","ticket_closed","ticket_open","already_rated","verification_requirements_not_met","verification_tax_number_in_use","verification_unavailable","username_taken","idempotency_in_flight","idempotency_key_reuse","domain_tld_not_allowed","domain_free_host","domain_txt_not_found","rate_limited","merchant_rate_limited","operator_register_cap_exceeded","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?} for the legacy per-account limits, and {limit: \"receive_cap\", current_level, cap_cents, used_cents, amount_cents, window_days, resets_at, next_level_requirements, kyc_url, concurrent?} for the receive cap; key_limit_exceeded → {limit, limit_cents, used_cents}; payer_velocity_limit → {window_minutes, max_per_window}; operator_register_cap_exceeded → {scope, max_per_window, window_hours}; ticket_open_cap → {max_open}; agent_signature_expired → {server_time}; discount_changed → {discount_pct, amount_cents} (the merchant's current values); the verification_* codes → {missing, remaining} (same shape as GET /api/verification); first_withdraw_tax_number_mismatch → {anchor_tax_number} (masked).","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)."},"window_hours":{"type":"integer","description":"Rolling-window length in hours (operator_register_cap_exceeded)."},"max_per_window":{"type":"integer","description":"Maximum inside the window: QRs per payer CPF/CNPJ (payer_velocity_limit), or agent registrations per operator token (operator_register_cap_exceeded)."},"limit":{"type":"string","description":"Which limit tripped: \"receive_cap\" | \"first_deposit\" | \"per_tx\" (account_limit_exceeded) or \"per_tx\" | \"daily\" (key_limit_exceeded). \"cumulative\" was removed on 2026-07-31 with the lifetime cap it reported."},"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, and the receive cap)."},"current_level":{"type":"integer","description":"Account tier the cap came from (receive_cap)."},"cap_cents":{"type":"integer","description":"The account's receive cap for the window, in cents (receive_cap)."},"amount_cents":{"type":"integer","description":"The amount that would be due now, in cents — at the current discount (discount_changed), or the refused amount (receive_cap)."},"window_days":{"type":"integer","description":"Length of the rolling receive window, in days (receive_cap)."},"resets_at":{"type":["string","null"],"description":"When the OLDEST counted amount leaves the rolling window, i.e. when part of the cap frees up (receive_cap). Null when nothing is counted — there is nothing to wait for."},"next_level_requirements":{"type":["object","null"],"description":"What the next tier requires (receive_cap). Null at the top tier. Age and volume only — never a client count.","additionalProperties":false,"properties":{"level":{"type":"integer","description":"The next tier."},"min_age_days":{"type":["integer","null"],"description":"Minimum account age, in days."},"min_volume_cents":{"type":["integer","null"],"description":"Minimum settled volume, in cents."}}},"kyc_url":{"type":["string","null"],"description":"Where to arrange a manually raised cap (receive_cap). Null when that route is unavailable."},"concurrent":{"type":"boolean","description":"Present and true when the refusal came from simultaneous requests rather than from amounts already settled (receive_cap) — retrying after the sibling requests finish may succeed."},"anchor_tax_number":{"type":["string","null"],"description":"MASKED CPF/CNPJ the account's first withdrawal must be addressed to (first_withdraw_tax_number_mismatch) — the document that paid the first completed deposit. Masked (•••••••8909) because it is there for the owner to RECOGNISE, not for a caller to read off."},"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."},"discount_pct":{"type":"integer","description":"The merchant's CURRENT DePix discount (discount_changed) — re-render the price from it and retry."},"missing":{"type":"array","description":"What is still blocking account verification (the verification_* codes) — identical to the `missing` array of GET /api/verification.","items":{"type":"string","description":"One blocking reason.","enum":["verification_disabled","account_age","deposit_leg","withdraw_leg","domain_proof","account_blocked","tax_number_in_use"]}},"remaining":{"type":"object","description":"How much is left on each verification requirement (the verification_* codes) — identical to the `remaining` object of GET /api/verification.","required":["deposit_cents","withdraw_cents","account_age_days"],"additionalProperties":false,"properties":{"deposit_cents":{"type":["integer","null"],"description":"Still to receive from one document, in cents."},"withdraw_cents":{"type":["integer","null"],"description":"Still to withdraw back to it, in cents."},"account_age_days":{"type":["integer","null"],"description":"Days the account still has to wait."}}},"next_action":{"type":"object","description":"The ONE move that unblocks this error, for a caller acting without a human in the loop. At most one per error; `kind` is a closed vocabulary. Absent on codes where the only answer is to fix the request itself, and on the anonymous payer endpoints (every action here addresses the account owner).","required":["kind"],"additionalProperties":false,"properties":{"kind":{"type":"string","description":"call_tool = call the named tool; human_step = a person must open the URL and do something; http_call = call the named endpoint; wait = retry after retry_after_seconds; reconnect = re-authorise the connector.","enum":["call_tool","human_step","http_call","wait","reconnect"]},"tool":{"type":"string","description":"Tool to call (kind=call_tool)."},"url":{"type":"string","description":"URL a person opens (kind=human_step) or an endpoint to call (kind=http_call)."},"retry_after_seconds":{"type":"integer","description":"Seconds to wait (kind=wait). Mirrors error.retry_after and the Retry-After header when the response carries one — never a third, disagreeing deadline."}}}}}}}}},"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, expired.","enum":["pending","under_review","pending_pix2fa","approved","delayed","will_refund","error","depix_sent","refunded","canceled","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":"error","description":"Upstream processing error. NOT terminal — the provider still owes an outcome, so keep polling: the deposit can still reach `depix_sent` or `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":"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, expired.","enum":["unsent","sending","error","sent","refunded","cancelled","expired"],"oneOf":[{"const":"unsent","description":"Created; DePix not yet received by the provider."},{"const":"sending","description":"DePix received; PIX payout in flight."},{"const":"error","description":"The DePix arrived and the PIX payout failed. NOT terminal — the provider holds the funds and still owes an outcome, so keep polling: the withdrawal can still reach `sent` (payout retried) or `refunded`."},{"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":"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}]},"PaymentMethod":{"type":"string","enum":["pix","depix"],"description":"Which rail settles the checkout. `pix` (default): the payer pays a PIX QR and the provider delivers DePix to the merchant. `depix`: the payer sends DePix wallet-to-wallet on Liquid to an address dedicated to this merchant, and settlement is observed on-chain — no PIX QR exists on this rail."},"DepixPayment":{"type":"object","description":"Payment instructions for the depix rail — present only on checkouts created with payment_method=depix, and only while the checkout can still be paid. The payer must send EXACTLY `amount_cents` of the DePix asset to `address`: attribution is by exact amount, so any other value stays unattributed and cannot be credited automatically. An on-chain payment is irreversible.","required":["address","amount_cents","amount","asset_id","uri","discount_pct","original_amount_cents","detected"],"additionalProperties":false,"properties":{"address":{"type":"string","description":"Confidential Liquid address (lq1…) dedicated to this merchant's direct DePix receipts. In sandbox it is a non-payable placeholder — never send funds to it."},"amount_cents":{"type":"integer","description":"EXACT amount to send, in cents. It is the face amount minus the merchant's discount and minus a per-checkout cents adjustment (at most 99 cents, always DOWNWARDS) that makes the value unique among the merchant's open checkouts — that uniqueness is how an incoming payment is matched to this checkout."},"amount":{"type":"string","description":"The same amount as the decimal string a wallet signs (e.g. \"89.97\"). Display and transmit this value verbatim; never round it."},"asset_id":{"type":"string","description":"Liquid asset id of DePix. Sending any other asset to this address loses the funds — they cannot be returned."},"uri":{"type":["string","null"],"description":"BIP21-style Liquid payment URI carrying address, amount, asset and this checkout's id (`liquidnetwork:<address>?amount=<amount>&assetid=<asset_id>&depixid=<checkout_id>`) — hand it to a wallet instead of asking the payer to type anything. Any BIP21 wallet ignores `depixid` (it is deliberately not `req-`-prefixed, which would make a wallet reject the whole URI); the DePix App uses it to re-read this checkout and confirm the address and status before offering to pay, so a URI written by someone else is refused rather than paid. The URI never carries a store name: a name in the URI is a name in the payer's clipboard, which anyone can write. Null in sandbox, which has no payable destination, and null on a checkout that is no longer payable (see the `depix` field on CheckoutDetail): the rest of the object is then a settlement record, not an instruction."},"discount_pct":{"type":"integer","description":"Merchant discount applied on this rail, 0–90 (0 when the merchant offers none)."},"original_amount_cents":{"type":"integer","description":"Face amount in cents before discount and uniqueness adjustment — the same value as the checkout's `amount`."},"detected":{"type":"boolean","description":"True once a matching payment has been SEEN on the network but not yet confirmed. Informational only: the status stays `pending` and no webhook fires until the first confirmation."}}},"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–600000 (R$ 5,00–R$ 6.000,00). Account-level and per-key limits may restrict it further.","minimum":500,"maximum":600000},"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."},"verification_flow":{"type":"boolean","description":"Set to `true` only when this deposit is the one being made IN ORDER TO VERIFY the account (the round trip described by GET /api/verification). That deposit does not consume the receive cap reported by GET /api/vault/status, so a new account does not spend part of its limit just to unlock the merchant tools. Worth ONCE and only up to the verification amount — the excess consumes the cap normally, as does every other deposit from the owner's own document. Ignored (never an error) when the account is already verified or is an agent account, which verifies by proving a domain instead. A non-boolean value returns 400 `validation_error`."}}},"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). Served from a provider-controlled host that can change: allow it dynamically rather than hard-coding it."},"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 (RFC 3339 UTC, `YYYY-MM-DDTHH:MM:SS.sssZ`)."},"updated_at":{"type":"string","description":"Last update timestamp (RFC 3339 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 (RFC 3339 UTC, `YYYY-MM-DDTHH:MM:SS.sssZ`) — fixed in sandbox (stateless)."},"updated_at":{"type":"string","description":"Deterministic synthetic update timestamp (RFC 3339 UTC, `YYYY-MM-DDTHH:MM:SS.sssZ`) — 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–600000 — the same ceiling as depositAmountInCents: the provider bounds whichever field you send, and the DePix it quotes for a payout near the ceiling sits above it (its fee is charged on the gross). Mutually exclusive with depositAmountInCents.","minimum":500,"maximum":600000},"taxNumber":{"type":"string","description":"CPF/CNPJ of the PIX key holder. Required — omitting it returns 400 `tax_number_required`."},"refundAddress":{"type":"string","description":"Optional Liquid address where the provider returns the DePix if the PIX payout can't be completed. Send one you control — without it a refused payout has no automatic way back. Validated with a full checksum: a malformed address is refused with 400 `validation_error` (`details.field: \"refundAddress\"`) before the withdrawal is quoted."}},"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: a synthetic quote with the live fee arithmetic on unpayable placeholder addresses."}}}}},"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 (RFC 3339 UTC, `YYYY-MM-DDTHH:MM:SS.sssZ`)."},"updated_at":{"type":"string","description":"Last update timestamp (RFC 3339 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 (RFC 3339 UTC, `YYYY-MM-DDTHH:MM:SS.sssZ`) — fixed in sandbox (stateless)."},"updated_at":{"type":"string","description":"Deterministic synthetic update timestamp (RFC 3339 UTC, `YYYY-MM-DDTHH:MM:SS.sssZ`) — 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). Rules differ per rail — see `payment_method`.","required":["amount"],"properties":{"amount":{"type":"integer","description":"Charge amount in cents (BRL). Range: 500–600000. On the depix rail this is the FACE amount, before the merchant's discount.","minimum":500,"maximum":600000},"payment_method":{"$ref":"#/components/schemas/PaymentMethod","default":"pix","description":"Rail to charge on. Omit it (or send \"pix\") for the PIX QR flow. \"depix\" requires the merchant to have the direct DePix rail enabled, otherwise the request is rejected with 400 `depix_not_enabled`."},"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":"How long this checkout stays open, in seconds. pix rail: 300–1200, default 1200. depix rail: 300–3600, default 1800. On the pix rail it governs the checkout, not the PIX BR Code — the payment provider sets its own QR expiry.","minimum":300,"maximum":3600},"expected_discount_pct":{"type":"integer","description":"The DePix discount percentage the page showed the payer, 0–90. Send it on the depix rail to make a stale page fail loudly: if the merchant's current discount differs, the request is rejected with 409 `discount_changed` carrying the fresh values instead of charging a different price.","minimum":0,"maximum":90},"payer_tax_number":{"type":"string","description":"CPF/CNPJ of the payer. Required on the pix rail — omitting it returns 400 `validation_error` naming the field. Ignored on the depix rail (there is no fiat leg to identify a payer for), so a shared integration can keep sending it."}},"allOf":[{"description":"Rail-conditional rules. On `depix`: expires_in accepts 300–3600 (default 1800) and no payer document is used. On `pix` (default): expires_in accepts 300–1200 (default 1200) and payer_tax_number is required.","if":{"description":"Matches a body that explicitly selects the depix rail.","properties":{"payment_method":{"const":"depix","description":"The depix rail."}},"required":["payment_method"]},"then":{"description":"depix rail — wider lifetime window, no payer document.","properties":{"expires_in":{"type":"integer","description":"Payment-URI lifetime in seconds on the depix rail: 300–3600; default 1800.","minimum":300,"maximum":3600}}},"else":{"description":"pix rail — the payer document is mandatory and `expires_in` caps at 20 minutes.","required":["payer_tax_number"],"properties":{"expires_in":{"type":"integer","description":"How long THIS CHECKOUT stays open, in seconds, on the pix rail: 300–1200; default 1200. It governs the checkout, not the PIX BR Code: the payment provider is not sent an expiry and applies its own, which can be longer. Treat a paid-after-expiry PIX as possible and reconcile from the deposit.* webhooks.","minimum":300,"maximum":1200}}}}]},"CheckoutCreateResponse":{"type":"object","description":"Created checkout with its payment instructions and hosted payment page. Exactly one of `pix` / `depix` is present, matching `payment_method`.","required":["id","status","amount","description","image_url","expires_at","is_live","payment_url"],"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 (face value — what the buyer owes before any depix discount)."},"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":"Expiry timestamp (RFC 3339 UTC, `YYYY-MM-DDTHH:MM:SS.sssZ`)."},"is_live":{"type":"boolean","description":"False for sandbox checkouts (sk_test_): the payment payload is a non-payable placeholder."},"payment_url":{"type":"string","description":"Hosted checkout page URL to hand to the payer."},"payment_method":{"$ref":"#/components/schemas/PaymentMethod","description":"The rail this checkout was created on."},"pix":{"type":"object","description":"PIX payment payload — present on the pix rail only.","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."}}},"depix":{"$ref":"#/components/schemas/DepixPayment","description":"DePix (Liquid) payment instructions — present on the depix rail only."}}},"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 (face value)."},"description":{"type":["string","null"],"description":"Checkout description."},"image_url":{"type":["string","null"],"description":"Checkout image URL."},"payment_method":{"$ref":"#/components/schemas/PaymentMethod","description":"The rail this checkout was created on."},"depix":{"$ref":"#/components/schemas/DepixPayment","description":"DePix (Liquid) payment for this checkout — present on the depix rail for the whole life of the checkout, not just while it is payable. On this rail `amount` is the FACE value; `depix.amount_cents` is the discounted, uniqueness-adjusted amount that actually had to arrive (and did, once the status is approved/completed — attribution is exact-match). Reconcile on it. Once the checkout is no longer payable `uri` is null, so nothing renders a payable QR for a settled order."},"pix_payload":{"type":"string","description":"PIX copy-and-paste payload — present only while status is \"pending\" on the pix rail."},"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 (RFC 3339 UTC)."},"is_live":{"type":"integer","description":"1 = live, 0 = sandbox (raw SQLite boolean).","enum":[0,1]},"created_at":{"type":"string","description":"Creation timestamp (RFC 3339 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)."},"delay_until":{"type":["string","null"],"description":"When this sale's money is released, if it is being held. Same RFC 3339 UTC instant as every other timestamp here (`\"2026-08-13T12:03:00.000Z\"`). Non-null only once the provider has answered with a date, so a sale that is held right now still reads null for a while; it also stays set after the money lands, so it is a hold RECORD, not a live flag. Pair it with `status`: a sale still waiting sits in `processing`. Never a reason — what triggered the hold is not published."},"vault_hours":{"type":["integer","null"],"description":"How many hours this sale was booked to wait when it was created. `0` means the hold policy looked at it and imposed no wait. **Null is not zero**: it means no hold decision was recorded against this sale at all — a sandbox checkout (no paired deposit exists), a row created before the mechanism shipped, or one created while the mechanism was switched off. Today the vast majority of rows read null. Use it as an answer to WHETHER, never to WHEN: the real wait starts when the payer pays, not when the sale was created, so `created_at + vault_hours` lands EARLY and must not be presented as a release date. `delay_until` is the only date."}}},"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 (RFC 3339 UTC)."},"expires_at":{"type":"string","description":"QR expiry timestamp (RFC 3339 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)."},"payment_method":{"$ref":"#/components/schemas/PaymentMethod","description":"The rail this checkout was created on."},"depix_discount_pct":{"type":["integer","null"],"description":"depix rail only: the discount percentage applied to this checkout (0–90). Null on the pix rail."},"depix_due_cents":{"type":["integer","null"],"description":"depix rail only: the discounted, uniqueness-adjusted amount in cents that had to arrive (and did, once settled — attribution is exact-match). This, not `amount` (the face value), is what the merchant received. Null on the pix rail."},"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."},"payer_name":{"type":["string","null"],"description":"Name the provider reports for whoever paid, off the underlying deposit. Null while the sale is unpaid, on the depix rail (no Pix payer to name), and on any sale the provider settled without one."},"blockchain_tx_id":{"type":["string","null"],"description":"Liquid txid that settled this sale, on either rail. Null until the money lands — and for a short while after, on the pix rail, when the provider reports the txid in a later callback than the one that completed the sale."},"delay_until":{"type":["string","null"],"description":"When this sale's money is released, if it is being held. Same RFC 3339 UTC instant as every other timestamp here (`\"2026-08-13T12:03:00.000Z\"`). Non-null only once the provider has answered with a date, so a sale that is held right now still reads null for a while; it also stays set after the money lands, so it is a hold RECORD, not a live flag. Pair it with `status`: a sale still waiting sits in `processing`. Never a reason — what triggered the hold is not published."},"vault_hours":{"type":["integer","null"],"description":"How many hours this sale was booked to wait when it was created. `0` means the hold policy looked at it and imposed no wait. **Null is not zero**: it means no hold decision was recorded against this sale at all — a sandbox checkout (no paired deposit exists), a row created before the mechanism shipped, or one created while the mechanism was switched off. Today the vast majority of rows read null. Use it as an answer to WHETHER, never to WHEN: the real wait starts when the payer pays, not when the sale was created, so `created_at + vault_hours` lands EARLY and must not be presented as a release date. `delay_until` is the only date."}}}},"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 (RFC 3339 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 2 business days of no user reply."},{"const":"closed","description":"TERMINAL — closed by the user, support, or the 2-business-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","rating","rated_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 (RFC 3339 UTC)."},"last_activity_at":{"type":"string","description":"Timestamp of the last user/admin message (RFC 3339 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 (RFC 3339 UTC) — null while open. Anchors the 7-day reopen window for auto-closed tickets."},"rating":{"type":["integer","null"],"minimum":0,"maximum":10,"description":"Satisfaction score the ticket owner gave (0 = worst, 10 = best) — null until rated. Only a closed ticket can be rated, and only once."},"rated_at":{"type":["string","null"],"description":"When the rating was submitted (RFC 3339 UTC) — null until rated."}}},"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 (RFC 3339 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"}}},"VerificationStatusResponse":{"type":"object","description":"Whether this account can use the merchant tools, and what is still missing if it cannot. Verification is independent of how much the account may receive — it never changes a limit.","required":["verified","verified_at","whatsapp_verified","method","enabled","eligible","requirements","progress","remaining","missing","unlocks","lbtc_fuel","steps"],"additionalProperties":false,"properties":{"verified":{"type":"boolean","description":"True when the merchant tools are unlocked on this account."},"verified_at":{"type":["string","null"],"description":"When verification completed (RFC 3339 UTC, \"YYYY-MM-DDTHH:MM:SS.sssZ\"). Null while unverified."},"whatsapp_verified":{"type":"integer","description":"1 once the account has verified its WhatsApp number, 0 otherwise (raw SQLite boolean). It gates the first deposit — a human account must clear it in the app before verifying. Always 0 for an agent account, which is exempt (it proves a domain instead).","enum":[0,1]},"method":{"type":"string","description":"Which proof applies to this account. `round_trip`: send money from a CPF/CNPJ to the account and withdraw it back to the SAME document. `domain`: prove control of a registrable domain by DNS TXT (agent accounts — POST /api/agents/verify-domain).","enum":["round_trip","domain"]},"enabled":{"type":"boolean","description":"False when automatic verification is switched off platform-wide; contact support instead of retrying."},"eligible":{"type":"boolean","description":"True when every requirement is satisfied and POST /api/verification would promote the account. A promotion still has to land: a suspended account never verifies."},"requirements":{"type":"object","description":"What this account's proof requires. Null members do not apply to the account's method.","required":["deposit_cents","withdraw_cents","min_account_age_days","max_days_between_legs","domain_proof"],"additionalProperties":false,"properties":{"deposit_cents":{"type":["integer","null"],"description":"Minimum to receive from one document, in cents. Null on the domain method."},"withdraw_cents":{"type":["integer","null"],"description":"Minimum to withdraw back to that SAME document, in cents. Lower than deposit_cents because fees are deducted along the way. Null on the domain method."},"min_account_age_days":{"type":["integer","null"],"description":"Minimum account age in days. Null on the domain method. **0 means there is no age requirement at all** — the `account_age` step is then omitted from `steps` and never appears in `missing`. 0 is the value in force."},"max_days_between_legs":{"type":["integer","null"],"description":"Maximum days between the two movements — they must sit inside one window of this length. Null on the domain method."},"domain_proof":{"type":"boolean","description":"True when a proven domain is what verifies this account."}}},"progress":{"type":"object","description":"What has been done so far. Amounts count only movements made after this feature went live.","required":["account_age_days","account_age_ok","deposited_cents","withdrawn_cents","deposit_leg_ok","withdraw_leg_ok","tax_number","tax_number_locked","domain"],"additionalProperties":false,"properties":{"account_age_days":{"type":"integer","description":"Age of the account in whole days."},"account_age_ok":{"type":"boolean","description":"True when the age requirement is satisfied."},"deposited_cents":{"type":"integer","description":"Received from the best-matching document, in cents."},"withdrawn_cents":{"type":"integer","description":"Withdrawn back to that same document, in cents."},"deposit_leg_ok":{"type":"boolean","description":"True when the received side reaches its minimum."},"withdraw_leg_ok":{"type":"boolean","description":"True when the withdrawn side reaches its minimum."},"tax_number":{"type":["string","null"],"description":"The document being matched, MASKED (only the last digits are shown). Null when no document has been seen yet."},"tax_number_locked":{"type":"boolean","description":"True once a document is permanently bound to this account. A document verifies exactly one account, so a bound one can never verify another."},"domain":{"type":["string","null"],"description":"The proven domain, on the domain method. Null otherwise."}}},"remaining":{"type":"object","description":"How much is left on each requirement — zero when satisfied, null when it does not apply.","required":["deposit_cents","withdraw_cents","account_age_days"],"additionalProperties":false,"properties":{"deposit_cents":{"type":["integer","null"],"description":"Still to receive from one document, in cents."},"withdraw_cents":{"type":["integer","null"],"description":"Still to withdraw back to it, in cents."},"account_age_days":{"type":["integer","null"],"description":"Days the account still has to wait."}}},"missing":{"type":"array","description":"Machine-readable list of what is blocking verification — empty when eligible. Branch on these instead of parsing prose.","items":{"type":"string","description":"`account_age`: the account is too young (never reported while `requirements.min_account_age_days` is 0). `deposit_leg`: not enough received from one document. `withdraw_leg`: not enough withdrawn back to it (also reported when both sides are met but too far apart in time). `domain_proof`: no proven domain yet. `account_blocked`: the account is suspended. `tax_number_in_use`: that document already verified another account. `verification_disabled`: automatic verification is switched off.","enum":["verification_disabled","account_age","deposit_leg","withdraw_leg","domain_proof","account_blocked","tax_number_in_use"]}},"unlocks":{"type":"array","description":"What verification unlocks on this account.","items":{"type":"string","description":"A capability name."}},"lbtc_fuel":{"type":["object","null"],"description":"How much DePix to convert to L-BTC before withdrawing, and null when it does not apply (agent accounts). The Liquid network charges its transaction fee in L-BTC, so a wallet holding only DePix cannot move its own money — the most common reason a first withdrawal never leaves. This is GUIDANCE, not a requirement: it is absent from `requirements` and never affects `eligible`, because a non-custodial wallet's balance is not visible server-side.","required":["min_depix_cents","balance_known","sufficient"],"additionalProperties":false,"properties":{"min_depix_cents":{"type":"integer","description":"Minimum DePix to convert to L-BTC, in cents. Convert about this much — converting a lot more can leave too little DePix to complete the withdrawal step."},"balance_known":{"type":"boolean","description":"Whether the server knows this account's L-BTC balance. Always false: the wallet is non-custodial and no balance is reported to the server. Determine it in the wallet."},"sufficient":{"type":["boolean","null"],"description":"Whether the account already holds enough L-BTC. Always null, for the reason in balance_known — treat null as \"unknown\", never as \"no\"."}}},"steps":{"type":"array","description":"The checklist IN THE ORDER THE ACCOUNT MUST ACT — render it as given and do not reorder or recompute it. `convert_lbtc` comes before `withdraw` because the withdrawal cannot be broadcast without network fuel. Amounts and days are pre-computed per step so the client never restates the rule.","items":{"type":"object","description":"One step of the checklist.","required":["id","state","target_cents","remaining_cents","target_days","remaining_days"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"`deposit`: receive from your own CPF/CNPJ. `convert_lbtc`: convert a little DePix to L-BTC for the network fee. `withdraw`: send DePix back to the same document. `account_age`: the account also has to be old enough — PRESENT ONLY when `requirements.min_account_age_days` > 0, which it is not today. `domain_proof`: agent accounts — replaces all of the above. Render the list as given; a step that is absent is not a requirement.","enum":["deposit","convert_lbtc","withdraw","account_age","domain_proof"]},"state":{"type":"string","description":"`done`, `pending`, or `unknown` — `unknown` means the server genuinely cannot tell (the L-BTC step, since no wallet balance reaches it) and the client must resolve it locally. Never render `unknown` as a failure.","enum":["done","pending","unknown"]},"target_cents":{"type":["integer","null"],"description":"What this step asks for, in cents. Null when the step is not about an amount."},"remaining_cents":{"type":["integer","null"],"description":"How much of that is left, in cents. Null when the step is not about an amount, or when the server cannot know."},"target_days":{"type":["integer","null"],"description":"What this step asks for, in days. Null when the step is not about time."},"remaining_days":{"type":["integer","null"],"description":"How many days are left. Null when the step is not about time."}}}}}},"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–600000.","minimum":500,"maximum":600000},"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},"kind":{"type":"string","description":"Row kind: 'product' (catalog item, default) or 'charge' (cobrança — a configurable payment link with a due date and late fees, served at pay.depixapp.com/c/{id} and never listed on any store surface).","enum":["product","charge"]},"due_date":{"type":"string","description":"Charges only (required for them): first due date, YYYY-MM-DD — the recurrence anchor."},"recurrence":{"type":["string","null"],"description":"Charges only: null (one-time) or weekly | monthly | quarterly | semiannual | yearly. Monthly-and-up anchor on the due day, clamping to shorter months."},"late_fine_bps":{"type":"integer","description":"Charges only: one-time late fine in basis points of the base (200 = 2%). Default 0.","minimum":0,"maximum":2000},"late_interest_monthly_bps":{"type":"integer","description":"Charges only: monthly interest in basis points, accrued pro-rata per day late (100 = 1% a.m.). Default 0.","minimum":0,"maximum":1000}}},"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","kind","due_date","recurrence","late_fine_bps","late_interest_monthly_bps","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_)."},"kind":{"type":"string","description":"'product' or 'charge'.","enum":["product","charge"]},"due_date":{"type":["string","null"],"description":"First due date (charges; null for products)."},"recurrence":{"type":["string","null"],"description":"Recurrence (charges; null = one-time and for products)."},"late_fine_bps":{"type":"integer","description":"One-time late fine in basis points (0 for products)."},"late_interest_monthly_bps":{"type":"integer","description":"Monthly interest in basis points (0 for products)."},"payment_url":{"type":"string","description":"Public payment URL: pay.depixapp.com/{merchant_slug}/{slug} for products, pay.depixapp.com/c/{id} for charges."},"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","kind","due_date","recurrence","late_fine_bps","late_interest_monthly_bps","total_checkouts","completed_checkouts","completed_amount","settled_count","processing_count"],"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 (RFC 3339 UTC)."},"position":{"type":["integer","null"],"description":"Pinned position on the public page (null = not pinned)."},"kind":{"type":"string","description":"'product' or 'charge'.","enum":["product","charge"]},"due_date":{"type":["string","null"],"description":"First due date (charges; null for products)."},"recurrence":{"type":["string","null"],"description":"Recurrence (charges; null = one-time and for products)."},"late_fine_bps":{"type":"integer","description":"One-time late fine in basis points (0 for products)."},"late_interest_monthly_bps":{"type":"integer","description":"Monthly interest in basis points (0 for products)."},"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."},"settled_count":{"type":"integer","description":"Checkouts that EVER reached approved or completed — for charges, the number of settled cycles (the FIFO position). A checkout cancelled AFTER being approved still counts: the position is monotonic by design, so a reversal never rewinds the series onto a competência that is still paid. Re-billing a reversed cycle is the merchant's decision, not the API's."},"processing_count":{"type":"integer","description":"Checkouts currently processing (Pix paid, settling)."},"charge_state":{"allOf":[{"$ref":"#/components/schemas/ChargeState"}],"description":"Derived payable state — present on charge rows only."},"payment_url":{"type":"string","description":"Public payment URL — present on charge rows only (pay.depixapp.com/c/{id})."}}},"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."},"charge_state":{"allOf":[{"$ref":"#/components/schemas/ChargeState"}],"description":"Derived payable state — charge rows only. Present here as well as on the list so a single-row read can answer what is owed today."},"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 (RFC 3339 UTC)."},"updated_at":{"type":"string","description":"Last update timestamp (RFC 3339 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–600000.","minimum":500,"maximum":600000},"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},"due_date":{"type":"string","description":"Charges only: new first due date (YYYY-MM-DD). Cannot be cleared."},"recurrence":{"type":["string","null"],"description":"Charges only: new recurrence (null makes it one-time)."},"late_fine_bps":{"type":"integer","description":"Charges only: new one-time fine in basis points (0–2000).","minimum":0,"maximum":2000},"late_interest_monthly_bps":{"type":"integer","description":"Charges only: new monthly interest in basis points (0–1000).","minimum":0,"maximum":1000}}},"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 (RFC 3339 UTC)."},"expires_at":{"type":"string","description":"QR expiry timestamp (RFC 3339 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."}}},"ChargeState":{"type":"object","description":"Derived payable state of a charge (kind='charge' product). Settlement is FIFO over the due-date series: the current cycle is selected by the number of cycles that EVER settled (a checkout that reached approved or completed — a later reversal does not rewind the series; re-billing a reversed cycle is the merchant's decision, not the API's) PLUS un-expired pending QRs, since a minted QR reserves the cycle it was priced for and two open QRs must never bill the same competência; the total is base + one-time fine + linear pro-rata interest (base × monthlyBps/10000 × daysLate/30), computed on the América/São_Paulo calendar (the due date itself is not late; lateness starts the next day) and clamped at the R$ 6.000 per-transaction cap.","required":["settled"],"additionalProperties":false,"properties":{"settled":{"type":"boolean","description":"True when a one-time charge is fully paid (every other field is then absent)."},"cycle_due_date":{"type":"string","description":"Due date (YYYY-MM-DD) of the current — oldest unsettled — cycle."},"days_late":{"type":"integer","description":"Days past the due date on the São Paulo calendar (0 = not late)."},"base_cents":{"type":"integer","description":"Configured base amount in cents."},"fine_cents":{"type":"integer","description":"One-time late fine in cents (0 when not late)."},"interest_cents":{"type":"integer","description":"Accrued pro-rata interest in cents (0 when not late)."},"total_today_cents":{"type":"integer","description":"What a QR created now charges: base + fine + interest, capped at 600000."},"capped":{"type":"boolean","description":"True when base + encargos exceeded the per-transaction cap and the total was clamped."},"status":{"type":"string","description":"Cycle status.","enum":["late","due_today","upcoming"]},"open_past_due_cycles":{"type":"integer","description":"Cycles already due and still unpaid (>1 means competências accumulated)."},"in_flight":{"type":"boolean","description":"True when a processing checkout exists (Pix paid, settling) — present on list rows only."}}},"PublicProductCheckoutResponse":{"type":"object","description":"Checkout created from a public product page. Exactly one of `pix` / `depix` is present, matching `payment_method`.","required":["id","status","amount","description","expires_at","is_live","payment_url"],"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 or, for charges (kind='charge'), the day's computed total (see `charge`)."},"description":{"type":["string","null"],"description":"Product description carried onto the checkout."},"expires_at":{"type":"string","description":"Expiry timestamp (RFC 3339 UTC)."},"is_live":{"type":"boolean","description":"Always true — only live products accept public checkouts."},"payment_url":{"type":"string","description":"Hosted checkout page URL."},"payment_method":{"$ref":"#/components/schemas/PaymentMethod","description":"The rail this checkout was created on."},"pix":{"type":"object","description":"PIX payment payload — present on the pix rail only.","required":["qr_code"],"additionalProperties":false,"properties":{"qr_code":{"type":"string","description":"PIX copy-and-paste (BR Code) payload."}}},"depix":{"$ref":"#/components/schemas/DepixPayment","description":"DePix (Liquid) payment instructions — present on the depix rail only."},"charge":{"allOf":[{"$ref":"#/components/schemas/ChargeState"}],"description":"Breakdown of the charged amount — present only when the product is a charge. Render totals from THIS response, never from an earlier page load."}}},"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. Rules differ per rail — see `payment_method`.","required":["amount"],"properties":{"amount":{"type":"integer","description":"Charge amount in cents (BRL). Range: 500–600000. When `items` is sent this MUST equal the sum of qty × the catalog price of every line, otherwise the request is rejected. On the depix rail this is the FACE amount, before the merchant's discount.","minimum":500,"maximum":600000},"payment_method":{"$ref":"#/components/schemas/PaymentMethod","default":"pix","description":"Rail to charge on. Omit it (or send \"pix\") for the PIX QR flow. \"depix\" requires the merchant to have the direct DePix rail enabled, otherwise the request is rejected with 400 `depix_not_enabled`."},"expires_in":{"type":"integer","description":"How long this checkout stays open, in seconds. pix rail: 300–1200, default 1200. depix rail: 300–3600, default 1800. On the pix rail it governs the checkout, not the PIX BR Code — the payment provider sets its own QR expiry.","minimum":300,"maximum":3600},"expected_discount_pct":{"type":"integer","description":"The DePix discount percentage the page showed the payer, 0–90. Send it on the depix rail to make a stale page fail loudly: if the merchant's current discount differs, the request is rejected with 409 `discount_changed` carrying the fresh values instead of charging a different price.","minimum":0,"maximum":90},"payer_tax_number":{"type":"string","description":"CPF/CNPJ of the payer. Required on the pix rail — omitting it returns 400 `validation_error` naming the field. Ignored on the depix rail."},"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}}}}},"allOf":[{"description":"Rail-conditional rules. On `depix`: expires_in accepts 300–3600 (default 1800) and no payer document is used. On `pix` (default): expires_in accepts 300–1200 (default 1200) and payer_tax_number is required.","if":{"description":"Matches a body that explicitly selects the depix rail.","properties":{"payment_method":{"const":"depix","description":"The depix rail."}},"required":["payment_method"]},"then":{"description":"depix rail — wider lifetime window, no payer document.","properties":{"expires_in":{"type":"integer","description":"Payment-URI lifetime in seconds on the depix rail: 300–3600; default 1800.","minimum":300,"maximum":3600}}},"else":{"description":"pix rail — the payer document is mandatory and `expires_in` caps at 20 minutes.","required":["payer_tax_number"],"properties":{"expires_in":{"type":"integer","description":"How long THIS CHECKOUT stays open, in seconds, on the pix rail: 300–1200; default 1200. It governs the checkout, not the PIX BR Code: the payment provider is not sent an expiry and applies its own, which can be longer. Treat a paid-after-expiry PIX as possible and reconcile from the deposit.* webhooks.","minimum":300,"maximum":1200}}}}]},"MerchantCheckoutResponse":{"type":"object","description":"Checkout created from a public merchant storefront page. Exactly one of `pix` / `depix` is present, matching `payment_method`.","required":["id","status","amount","description","expires_at","is_live","payment_url"],"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":"Expiry timestamp (RFC 3339 UTC, `YYYY-MM-DDTHH:MM:SS.sssZ`)."},"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."},"payment_method":{"$ref":"#/components/schemas/PaymentMethod","description":"The rail this checkout was created on."},"pix":{"type":"object","description":"PIX payment payload — present on the pix rail only.","required":["qr_code"],"additionalProperties":false,"properties":{"qr_code":{"type":"string","description":"PIX copy-and-paste (BR Code) payload."}}},"depix":{"$ref":"#/components/schemas/DepixPayment","description":"DePix (Liquid) payment instructions — present on the depix rail only."}}},"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 expiry (0 when expired or not pending). On the depix rail a payment broadcast in the last seconds still settles: the checkout only turns `expired` 15 minutes after `expires_at`, so keep polling while remaining_seconds is 0 and the status is still `pending`."},"expires_at":{"type":["string","null"],"description":"Expiry timestamp (RFC 3339 UTC)."},"redirect_url":{"type":["string","null"],"description":"Post-payment redirect URL."},"is_test":{"type":"boolean","description":"True for sandbox checkouts (non-payable placeholder payload)."},"payment_method":{"$ref":"#/components/schemas/PaymentMethod","description":"The rail this checkout was created on."},"pix":{"type":"object","description":"PIX payment payload — present on the pix rail only, while status is \"pending\".","required":["qr_code"],"additionalProperties":false,"properties":{"qr_code":{"type":"string","description":"PIX copy-and-paste (BR Code) payload."}}},"depix":{"$ref":"#/components/schemas/DepixPayment","description":"DePix (Liquid) payment instructions — present on the depix rail only, while status is \"pending\"."}}},"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, and where to do it. Graduation is downstream of verification, and an AGENT account verifies by proving control of a registrable domain over DNS — never by settling a number of deposits. Deposits buy nothing here; the two calls below are the whole path.","required":["requires","verify_domain_endpoint","allowed_tlds_endpoint"],"additionalProperties":false,"properties":{"requires":{"type":"string","enum":["domain_proof"],"description":"The gate, as a machine-readable token — the same one GET /api/verification reports in `missing[]`/`steps[]` and GET /api/agents/status reports in `graduation.blocked_on`."},"verify_domain_endpoint":{"type":"string","description":"Method + path of the call that performs the proof, in two phases: `{domain}` returns the TXT record to publish, `{domain, confirm: true}` resolves it. A successful proof verifies the account, and graduation follows on its own (watch `graduation.blocked_on` on GET /api/agents/status, or the `agent.graduated` webhook)."},"allowed_tlds_endpoint":{"type":"string","description":"Method + path of the public TLD allowlist. Call it before picking a domain — it is what verify-domain will accept, and it avoids a trial-and-error 422."}}},"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","inter_deposit_delay_hours","payer_velocity","verified_per_tx_deposit_max_cents","verified_per_tx_withdraw_send_max_cents","verified_per_tx_withdraw_receive_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."},"inter_deposit_delay_hours":{"type":"integer","description":"MINIMUM settlement delay applied to deposits 2–5 of ANY account — verified or not, personal deposit or Pix checkout, since the account has one deposit ledger. The DePix payout of each of those deposits is held AT LEAST this many hours (deposit status `delayed`). It is a floor, not the whole answer: the rules that hold a deposit compose by taking the LONGEST, so a deposit 2–5 too large to count as pacing, or one under risk review, is held for the account's trust-level window instead — which is longer. Read `vault_window_hours` on GET /api/vault/status and pace against the greater of the two before promising anyone a release time. Deposit 1 settles immediately and deposit 6 onward is governed by the receive cap and the instant lane. 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, on `amountInCents` — what the payer sends on POST /api/deposit."},"verified_per_tx_withdraw_send_max_cents":{"type":"integer","description":"Per-withdrawal cap after verification, on `depositAmountInCents` — the DePix the wallet sends. Mirrors the request schema maximum."},"verified_per_tx_withdraw_receive_max_cents":{"type":"integer","description":"Per-withdrawal cap after verification, on `payoutAmountInCents` — the BRL the destination key receives. Mirrors the request schema maximum; the provider bounds each request field at the same figure, so this equals the send cap."}}}}}}},"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","verified"],"additionalProperties":false,"properties":{"verified_domain":{"type":"string","description":"The registrable domain (eTLD+1) recorded on the agent."},"verified":{"type":"boolean","description":"Whether the proof also unlocked the merchant tools (checkouts and products) on this account. For an agent the domain proof IS the account verification, so this is normally true. It can be false while the account is suspended — the domain proof itself is recorded either way. Read GET /api/verification for the current state."}}}]},"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)."}}}}},"AgentDepixPayRequest":{"type":"object","description":"Turn the DePix direct rail on or off for the agent's own merchant. Authenticated by the agent keypair signature — the per-request proof-of-possession IS the step-up the human door gets from a password. Enabling ALWAYS needs a fresh (address, blinding_key) pair: there is no re-activation without one, because re-activating means a brand new dedicated address.","required":["enabled"],"additionalProperties":false,"properties":{"enabled":{"type":"boolean","description":"true → register the dedicated address and start watching it. false → turn the rail off and delete the view key (no other field is read, and none is required)."},"address":{"type":"string","description":"The dedicated CONFIDENTIAL Liquid address (lq1…) this merchant will be paid at. Required when enabled is true. An unconfidential ex1/base58 address is refused: it would publish every amount received to the whole world. It must also be exclusive — never the merchant's payout or split address."},"blinding_key":{"type":"string","description":"The 32-byte blinding PRIVATE key of that address, hex. It grants visibility of the amounts arriving at that ONE script and nothing else: no spending power, no other address, no descriptor. Sent once, stored sealed, and deleted when the rail is turned off."},"derivation_index":{"type":["integer","null"],"description":"Optional wallet derivation index of the address, echoed back so the wallet can keep the index reserved across a restore. Non-negative integer."}}},"AgentDepixPayResponse":{"type":"object","description":"The rail's new state.","required":["response"],"additionalProperties":false,"properties":{"response":{"description":"Enabled and disabled answer different questions, so they carry different fields.","oneOf":[{"type":"object","description":"The rail is on and this address is being watched.","required":["depix_pay_enabled","depix_pay_address","depix_derivation_index","depix_discount_pct"],"additionalProperties":false,"properties":{"depix_pay_enabled":{"type":"boolean","const":true,"description":"Always true here."},"depix_pay_address":{"type":"string","description":"The registered dedicated address (lower-cased)."},"depix_derivation_index":{"type":["integer","null"],"description":"The index sent in, echoed back; null when none was sent."},"depix_discount_pct":{"type":"integer","description":"The discount currently granted on this rail, in percent. Unchanged by this call."}}},{"type":"object","description":"The rail is off. `view_key_deleted` says whether any viewing grant was actually destroyed; an address with a DePix payment still in flight keeps its key until that checkout is terminal, otherwise the payer's money would land on a script nobody watches.","required":["depix_pay_enabled","view_key_deleted","pending_addresses"],"additionalProperties":false,"properties":{"depix_pay_enabled":{"type":"boolean","const":false,"description":"Always false here."},"view_key_deleted":{"type":"boolean","description":"Whether at least one view key was deleted."},"pending_addresses":{"type":"integer","description":"How many addresses kept their key because a DePix checkout there is still open."}}}]}}},"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","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\"."},"graduated":{"type":"boolean","description":"true once the account has graduated to full production."},"graduation":{"type":"object","description":"Coarse graduation state: which side the ball is on, never the review specifics.","required":["blocked_on"],"additionalProperties":false,"properties":{"blocked_on":{"type":["string","null"],"enum":["domain_proof","gate_review",null],"description":"What graduation is waiting on. \"domain_proof\": the account is not verified yet and YOU act — prove a domain via POST /api/agents/verify-domain. \"gate_review\": verified, but graduation has not landed yet — it settles on its own, poll. null: already graduated. Deposit counts never appear here."}}},"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."}}}}}}}},"VaultStatusResponse":{"type":"object","description":"Receive cap, trust level, hold window and what the account still needs for the next level. Same payload for a human JWT and an agent API key — the economics never fork by account type.","required":["vault_active","policy_version","level","cap","vault_window_hours","instant","progress","merchant_tools","kyc"],"additionalProperties":false,"properties":{"vault_active":{"type":"boolean","description":"false when the whole mechanism is switched off — every number below is then informational only and deposits settle on the pre-Cofre rules. true does NOT by itself mean deposits are held: the receive cap and the hold window are independent switches, and `vault_window_hours` is the one that says whether this account waits."},"policy_version":{"type":"string","description":"Version of the policy that produced these numbers. Every deposit records the version that decided its own deadline."},"level":{"type":"object","description":"Trust level (0-4). Drives the cap and the hold window; it does NOT unlock the merchant tools.","required":["current","max","pinned","frozen_until","eligible"],"additionalProperties":false,"properties":{"current":{"type":"integer","description":"Level in force right now."},"max":{"type":"integer","description":"Highest level the ladder defines."},"pinned":{"type":"boolean","description":"true when support fixed the level by hand; the automatic evaluation then leaves it alone."},"frozen_until":{"type":["string","null"],"description":"Timestamp until which the level cannot rise automatically; null when it is not frozen. Expires on its own."},"eligible":{"type":"integer","description":"Level the automatic ladder would grant today — differs from `current` only while the level is pinned."}}},"cap":{"type":"object","description":"How much the account may RECEIVE inside the rolling window.","required":["enforced","cents","used_cents","available_cents","window_days","resets_at","pinned","first_deposit_pending"],"additionalProperties":false,"properties":{"enforced":{"type":"boolean","description":"false when the cap is not being applied; nothing is refused in that state."},"cents":{"type":"integer","description":"The cap, in cents, for the current window."},"used_cents":{"type":"integer","description":"Already received inside the window. Includes recent unpaid QRs, so creating charges without paying them does not free up room."},"available_cents":{"type":"integer","description":"cents - used_cents, floored at zero."},"window_days":{"type":"integer","description":"Length of the rolling window in days."},"resets_at":{"type":["string","null"],"description":"When the OLDEST counted deposit leaves the window, i.e. when part of the cap frees up. null when nothing is counted. The window rolls; it is not a calendar reset."},"pinned":{"type":"boolean","description":"true when the cap was set by hand (support/KYC) instead of coming from the level."},"first_deposit_pending":{"type":"boolean","description":"true while the account has no PERSONAL deposit past `pending`. This is a rung BELOW `cents`: until it clears, a deposit is refused above the first-deposit ceiling whatever the cap says (400 account_limit_exceeded with limit \"first_deposit\"), so a client must not quote `available_cents` as spendable while it is true. Counted exactly as POST /api/deposit counts it — personal deposits only, post-payment statuses — and NOT keyed on verification: the rung is about history."}}},"vault_window_hours":{"type":"integer","description":"Hours a new deposit will wait before converting, at the current level. **0 means no hold is added** — either the whole mechanism is off, or the hold window is off while the receive cap keeps being enforced (`vault_active: true` with `cap.enforced: true`). Read this field, not `vault_active`, before telling anyone their money will wait. It never reports the pre-existing per-account delays, which are outside this mechanism."},"instant":{"type":"object","description":"The only irreversible path: money that settles immediately. Bounded per transaction AND per window.","required":["enabled","max_per_tx_cents","cap_cents","used_cents","window_days","graduation_completed","deposits_settled","deposits_required","identity_ok","graduation_hold_hours","graduation_per_tx_cents","graduation_first_max_cents"],"additionalProperties":false,"properties":{"enabled":{"type":"boolean","description":"false when instant settlement is switched off; everything then goes through the hold."},"max_per_tx_cents":{"type":"integer","description":"Above this amount a deposit NEVER settles instantly, whatever the cap says."},"cap_cents":{"type":"integer","description":"Ceiling on the total settled instantly inside the window."},"used_cents":{"type":"integer","description":"Already settled instantly inside the window."},"window_days":{"type":"integer","description":"Length of the instant-settlement window in days."},"graduation_completed":{"type":"boolean","description":"true once enough deposits have settled for instant settlement to be available."},"deposits_settled":{"type":"integer","description":"Settled deposits counted toward that requirement."},"deposits_required":{"type":"integer","description":"Settled deposits the requirement asks for."},"identity_ok":{"type":"boolean","description":"true when the account cleared its identity requirement (verified WhatsApp for a human, being an agent for an agent)."},"graduation_hold_hours":{"type":["integer","null"],"description":"EXACT hours a deposit settling under the graduation waits (deposits 2 to `deposits_required`, at or below `graduation_per_tx_cents`) — for this account, today. Reflects a manual per-account delay when support set one, so it can exceed the default; never quote the default instead of this field. Null when the graduation mechanism is off: then no exact figure exists and `vault_window_hours` is the honest upper bound. This is what lets a client warn \"1 dia\" for the second sale of a new account instead of rounding up to the level window."},"graduation_per_tx_cents":{"type":["integer","null"],"description":"Per-deposit ceiling under which the graduation wait above applies. A graduating deposit ABOVE it takes the level's `vault_window_hours` instead. Null when the graduation mechanism is off."},"graduation_first_max_cents":{"type":["integer","null"],"description":"Ceiling of the very FIRST deposit (deposits_settled = 0), which settles instantly at or below it — above it, a personal deposit is refused by the first-deposit rung (see `cap.first_deposit_pending`), so no hold happens on a first deposit either way. Null when the graduation mechanism is off."}}},"progress":{"type":"object","description":"Inputs of the automatic ladder, and the gap to the next rung.","required":["account_age_days","matured_volume_cents","next_level"],"additionalProperties":false,"properties":{"account_age_days":{"type":"integer","description":"Days since the account was created."},"matured_volume_cents":{"type":"integer","description":"Received volume that has already matured and counts toward the next level. Counts from the moment the PIX was PAID, not from the conversion."},"next_level":{"description":"Requirements for the next level, or null at the top of the ladder.","oneOf":[{"type":"object","description":"The next rung and what is still missing.","required":["level","cap_cents","window_hours","min_age_days","min_volume_cents","current_age_days","current_volume_cents","missing_age_days","missing_volume_cents"],"additionalProperties":false,"properties":{"level":{"type":"integer","description":"The next level."},"cap_cents":{"type":["integer","null"],"description":"The receive cap that level grants, in cents — what the requirements below buy. Null only if the ladder is misconfigured."},"window_hours":{"type":["integer","null"],"description":"How long a deposit waits at that level, in hours — the other half of what the requirements below buy, since climbing both raises the cap and shortens the wait. Unlike the top-level `vault_window_hours`, this is the LADDER's number and is reported whether or not the hold window is currently in force: it describes a rung, not the money arriving now. A client must therefore never render it as a wait that applies today. Null only if the ladder is misconfigured."},"min_age_days":{"type":"integer","description":"Minimum account age it asks for."},"min_volume_cents":{"type":"integer","description":"Minimum matured volume it asks for."},"current_age_days":{"type":"integer","description":"Current account age in days."},"current_volume_cents":{"type":"integer","description":"Current matured volume in cents."},"missing_age_days":{"type":"integer","description":"Days still missing, zero when satisfied."},"missing_volume_cents":{"type":"integer","description":"Cents of matured volume still missing, zero when satisfied."}}},{"type":"null","description":"Already at the top of the ladder."}]}}},"merchant_tools":{"type":"object","description":"A SEPARATE axis from the level: it unlocks checkouts and products, and never changes the cap or the window.","required":["verified"],"additionalProperties":false,"properties":{"verified":{"type":"boolean","description":"true when the account may create checkouts and products."}}},"kyc":{"type":"object","description":"The path to a higher cap, available at every level. Always a human action — an agent passes the link to its operator.","required":["available","booking_url"],"additionalProperties":false,"properties":{"available":{"type":"boolean","description":"true when the higher-cap path is open."},"booking_url":{"type":["string","null"],"description":"Where to book the verification call; null when unavailable."}}}}},"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 (RFC 3339 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 (RFC 3339 UTC), or null when delivery succeeded or the schedule is exhausted."},"sent_at":{"type":"string","description":"Delivery attempt timestamp (RFC 3339 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 (RFC 3339 UTC)."},"updated_at":{"type":"string","description":"Last update timestamp (RFC 3339 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 (RFC 3339 UTC)."},"updated_at":{"type":"string","description":"Last update timestamp (RFC 3339 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","is_live","amount","product_id","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)."},"is_live":{"type":"boolean","description":"False for a sandbox checkout (sk_test_, or one completed from the hosted sandbox payment page). Sandbox events are signed with the same secret and carry the same shape as live ones, so this is the field that separates them — never release goods on false."},"amount":{"type":"integer","description":"Charge amount in cents — always the FACE value, never what the payer actually paid (see amount_received)."},"payment_method":{"$ref":"#/components/schemas/PaymentMethod","description":"The rail that settled this checkout."},"amount_received":{"type":"integer","description":"What the payer actually paid, in cents — present on the depix rail, where it is `amount` minus the merchant's discount and minus the cents adjustment that made the value unique. Release goods against THIS value."},"discount_pct":{"type":"integer","description":"DePix discount applied to this checkout, 0–90 — present on the depix rail."},"product_id":{"type":["string","null"],"description":"Originating product/charge id (prd_*); null for standalone checkouts. For charges, pair with metadata.charge_cycle to know WHICH competência settled."},"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."},"rejection_reasons":{"type":"array","items":{"type":"string"},"description":"Provider reasons for the refusal/refund — present on checkout.cancelled, so revoking on the webhook needs no follow-up GET to learn WHY. Same catalog as the REST reads (PAYER_MISMATCH, PAST_DAILY_LIMIT, BLOCKED_USER, HIGH_VELOCITY, ...); [] when the provider reported none. New codes may appear; display unknown codes as-is."},"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."}}},"UnmatchedPaymentWebhookData":{"type":"object","description":"A DePix payment landed on the merchant's direct-rail address but could not be tied to a checkout — the amount matched no open checkout, or it matched one that was already paid. The money IS in the merchant's wallet; only the automatic attribution failed, and reconciling it is a human decision (never an automatic credit).","required":["id","type","status","amount_cents","txid","vout","first_seen_at","event_id"],"additionalProperties":false,"properties":{"id":{"type":"string","description":"Detected-output id (dout_*) — stable handle for this receipt."},"type":{"type":"string","enum":["depix_output"],"description":"Resource discriminator — always \"depix_output\"."},"status":{"type":"string","enum":["unattributed","duplicate"],"description":"Why it was not credited: `unattributed` — no open checkout has this exact amount (wrong value typed, payment after expiry, or several candidates); `duplicate` — a second payment for a checkout that was already settled."},"amount_cents":{"type":"integer","description":"Amount received, in cents."},"txid":{"type":"string","description":"Liquid transaction id that carried the payment."},"vout":{"type":"integer","description":"Index of the paying output inside that transaction."},"first_seen_at":{"type":"string","description":"When the payment was first seen on the merchant's address (RFC 3339 UTC, `YYYY-MM-DDTHH:MM:SS.sssZ`). Same value — and same field name — the merchant dashboard lists it under; it is when the payment was SEEN, which may be minutes before this notification."},"reason":{"type":"string","enum":["no_matching_checkout","duplicate_payment","ambiguous_candidates","value_not_whole_cents","max_attributions_per_tx","transition_lost"],"description":"Why the automatic attribution did not happen. `no_matching_checkout` — no open checkout carries this exact amount; `duplicate_payment` — the matching checkout was already settled; `ambiguous_candidates` — more than one open checkout matched, so none was credited; `value_not_whole_cents` — the amount is not a whole number of cents; `max_attributions_per_tx` — this transaction already paid the per-tx limit of checkouts; `transition_lost` — a concurrent settlement won the race. Advisory: reconcile on `id`, not on this string."},"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 (the account got verified — for an agent, by proving a domain — and the account is not suspended). 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 (RFC 3339 UTC, 'YYYY-MM-DDTHH:MM:SS.sssZ')."},"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."}}}}}}