{ "openapi": "3.1.0", "info": { "title": "Cofri Acquiring API", "version": "1.0.0", "description": "API custodial para compra e liquidação de DePix, transferências internas, consulta de saldo e webhooks.\n\n## Autenticação\nIntegrações server-to-server usam `X-API-Key` e HMAC. JWT é destinado a sessões humanas. Para HMAC, envie `X-Cofri-Timestamp` (Unix seconds), `X-Cofri-Nonce` (8–128 caracteres) e `X-Cofri-Signature`. A string canônica é `timestamp\\nnonce\\nMETHOD\\nrequest-target\\nsha256(raw-body)` e a assinatura é `sha256=`. A janela é de 5 minutos e o nonce é de uso único.\n\n## Idempotência\n`Idempotency-Key` é obrigatório para chamadas financeiras autenticadas por API key (`/market/buy`, `/market/sell`). Repetir a mesma chave e o mesmo payload devolve a resposta original com `Idempotency-Replayed: true`; payload diferente retorna `409 IDEMPOTENCY_CONFLICT`.\n\n## Valores\nValores BRL em Market são decimais. Valores de wallet/withdraw são inteiros em base units (8 casas para DePix), salvo quando explicitamente informado. CPF/CNPJ em `customer` ou `beneficiary` pertence ao cliente final da transação, não à credencial da plataforma.\n\n## Webhooks\nEntregas são `POST` HTTPS, assinadas sobre `timestamp.raw_body`. Confirme com qualquer 2xx. Eventos podem ser repetidos; deduplique pelo campo `id`. O endpoint precisa resolver somente para IPs públicos e redirects não são seguidos.\n\n## Escopo desta API\nEsta é a API pública de adquirência — cash-in (`/market/buy`), cash-out (`/market/sell`), consulta de saldo/transações e gestão de webhooks. **`/market/sell` é o cash-out Pix** (liquidação de DePix, valor sai via Pix para o beneficiário). Transferência interna entre carteiras da Rede Ares (`/withdraw/*`) é um recurso do dashboard humano da COFRI, não faz parte desta integração e não é documentado aqui. Login, cadastro, 2FA e administração também pertencem ao dashboard humano — fora do escopo desta API.\n\n## Modelo de custódia\nO cash-in (`POST /market/buy`) credita saldo custodial em **DePix** (1 DePix = 1 BRL, lastreado 1:1) — não é um crédito em BRL disponível pra saque bancário direto. Pra converter de volta em Real e liquidar via Pix, chame `POST /market/sell` (o cash-out). O `id` retornado em cada operação é o identificador estável pra conciliação — use-o pra cruzar com os eventos de webhook recebidos.", "license": { "name": "Proprietary", "identifier": "LicenseRef-Proprietary" } }, "servers": [ { "url": "https://api.cofri.digital" } ], "tags": [ { "name": "Wallet", "description": "Custodial wallet, balance, asset and address operations." }, { "name": "Market", "description": "Pix cash-in (buy) and Pix cash-out (sell) acquiring flows." }, { "name": "Transactions", "description": "Transaction history, summaries and public receipts." }, { "name": "Webhooks", "description": "Client webhook subscriptions, delivery logs and retries." } ], "paths": { "/wallet/balance": { "get": { "tags": [ "Wallet" ], "summary": "Read custodial balances", "operationId": "getWalletBalance", "security": [ { "apiKey": [] } ], "description": "Scope `wallet:read`. Signed API keys: 600 reads/minute.", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "wallet_id": { "type": "string", "format": "uuid" }, "balances": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string" }, "precision": { "type": "integer" }, "available": { "type": "integer", "format": "int64" }, "pending": { "type": "integer", "format": "int64" }, "locked": { "type": "integer", "format": "int64" }, "available_formatted": { "type": "string" } } } } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/market/fees": { "get": { "tags": [ "Market" ], "summary": "Read public fees and transaction boundaries", "operationId": "getMarketFees", "security": [], "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "required": [ "buy_min_brl", "buy_max_brl", "sell_min_brl" ], "properties": { "asset": { "const": "DePix" }, "buy_fee_percent": { "type": "number" }, "buy_fee_fixed": { "type": "number" }, "buy_min_brl": { "type": "number" }, "buy_max_brl": { "type": "number" }, "sell_fee_percent": { "type": "number" }, "sell_fee_fixed": { "type": "number" }, "sell_min_brl": { "type": "number", "description": "Minimum net Pix payout in BRL. The gross DePix amount sent to /market/sell must also cover the applicable percentage and fixed fees." } } } } } ] } } } } } } }, "/market/limits": { "get": { "tags": [ "Market" ], "summary": "Read effective account limits and usage", "operationId": "getMarketLimits", "security": [ { "apiKey": [] } ], "description": "Scope `market:read`. Null means that no account-specific cap is configured for that period.", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "type": [ "number", "integer", "object", "null" ] } } } } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/market/buy": { "post": { "tags": [ "Market" ], "summary": "Create a Pix charge to buy DePix", "operationId": "postMarketBuy", "security": [ { "apiKey": [] } ], "description": "Scope `market:buy`; signed writes: 60/minute. Limits are enforced with 422. `expires_at` always reflects the rail expiry, never a client-side estimate.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "customer" ], "properties": { "amount": { "type": "number", "exclusiveMinimum": 0, "description": "Gross BRL amount.", "multipleOf": 0.01 }, "asset": { "const": "DEPIX", "default": "DEPIX" }, "external_reference": { "type": "string", "maxLength": 128 }, "customer": { "$ref": "#/components/schemas/Customer" } } } } } }, "responses": { "201": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BuyCreated" } } } ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" }, "500": { "$ref": "#/components/responses/Error500" } } } }, "/market/buy/status/{id}": { "get": { "tags": [ "Market" ], "summary": "Read buy settlement status", "operationId": "getMarketBuyStatusId", "security": [ { "apiKey": [] } ], "description": "Scope `market:read`. Polling is allowed at the credential read limit; webhooks are the preferred mechanism.", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BuyOrder" } } } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/market/buy/list": { "get": { "tags": [ "Market" ], "summary": "List buy orders", "operationId": "getMarketBuyList", "security": [ { "apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" } ], "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BuyOrder" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/market/sell": { "post": { "tags": [ "Market" ], "summary": "Sell DePix and initiate a Pix payout", "operationId": "postMarketSell", "security": [ { "apiKey": [] } ], "description": "Scope `market:sell`; signed writes: 60/minute. The `amount` is gross; after fees, `net_brl` must be at least `sell_min_brl` from `GET /market/fees`. The DePix amount is reserved once. Normal requests begin automatically; risk exceptions use `risk_review`. A MED reserve is tied to the affected order and does not implicitly block unrelated platform accounts.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "pix_key", "pix_key_type", "beneficiary" ], "properties": { "amount": { "type": "number", "exclusiveMinimum": 0, "description": "DePix amount (1 DePix = R$ 1 gross).", "multipleOf": 0.01 }, "asset": { "const": "DEPIX", "default": "DEPIX" }, "pix_key": { "type": "string" }, "pix_key_type": { "type": "string", "enum": [ "CPF", "CNPJ", "EMAIL", "PHONE", "EVP" ] }, "external_reference": { "type": "string", "maxLength": 128 }, "beneficiary": { "$ref": "#/components/schemas/Beneficiary" } } } } } }, "responses": { "201": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SellOrder" } } } ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" }, "500": { "$ref": "#/components/responses/Error500" } } } }, "/market/sell/status/{id}": { "get": { "tags": [ "Market" ], "summary": "Read sell settlement status", "operationId": "getMarketSellStatusId", "security": [ { "apiKey": [] } ], "description": "Scope `market:read`. This is the authoritative status endpoint; balance inference is unnecessary.", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SellOrder" } } } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/market/sell/list": { "get": { "tags": [ "Market" ], "summary": "List sell orders", "operationId": "getMarketSellList", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SellOrder" } } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/transactions": { "get": { "tags": [ "Transactions" ], "summary": "List the transaction ledger view", "operationId": "getTransactions", "security": [ { "apiKey": [] } ], "description": "Scope `transactions:read`.", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "asset", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "429": { "$ref": "#/components/responses/Error429" } } } }, "/transaction/{id}": { "get": { "tags": [ "Transactions" ], "summary": "Read one transaction", "operationId": "getTransactionId", "security": [ { "apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" } } } }, "/transactions/summary": { "get": { "tags": [ "Transactions" ], "summary": "Read transaction totals", "operationId": "getTransactionsSummary", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object" } } } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" } } } }, "/webhook/events": { "get": { "tags": [ "Webhooks" ], "summary": "List supported event names", "operationId": "getWebhookEvents", "security": [ { "apiKey": [] } ], "description": "Scope `webhooks:manage`.", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" } } } }, "/webhook/create": { "post": { "tags": [ "Webhooks" ], "summary": "Register a webhook endpoint", "operationId": "postWebhookCreate", "security": [ { "apiKey": [] } ], "description": "Scope `webhooks:manage`. Only public HTTPS URLs are accepted. The signing secret is shown once.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "url", "events" ], "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri", "pattern": "^https://" }, "events": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/WebhookEvent" } } } } } } }, "responses": { "201": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "secret": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "422": { "$ref": "#/components/responses/Error422" }, "500": { "$ref": "#/components/responses/Error500" } } } }, "/webhook/list": { "get": { "tags": [ "Webhooks" ], "summary": "List registered webhooks", "operationId": "getWebhookList", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" } } } }, "/webhook/{id}": { "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook", "operationId": "deleteWebhookId", "security": [ { "apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" } } } }, "/webhook/test": { "post": { "tags": [ "Webhooks" ], "summary": "Send a test delivery", "operationId": "postWebhookTest", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "webhook_id" ], "properties": { "webhook_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "delivered": { "type": "boolean" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "500": { "$ref": "#/components/responses/Error500" } } } }, "/webhook/logs": { "get": { "tags": [ "Webhooks" ], "summary": "List delivery logs", "operationId": "getWebhookLogs", "security": [ { "apiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "name": "webhook_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" } } } }, "/webhook/retry": { "post": { "tags": [ "Webhooks" ], "summary": "Retry a delivery", "operationId": "postWebhookRetry", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "log_id" ], "properties": { "log_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "500": { "$ref": "#/components/responses/Error500" } } } }, "/webhook/{id}/rotate": { "post": { "tags": [ "Webhooks" ], "summary": "Rotate a webhook's signing secret", "operationId": "postWebhookIdRotate", "security": [ { "apiKey": [] } ], "description": "Scope `webhooks:manage`. The previous secret stops validating immediately. The new secret is shown once — save it, it cannot be retrieved again.", "responses": { "200": { "description": "Success", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "schema": { "type": "integer" } }, "Idempotency-Replayed": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SuccessEnvelope" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "secret": { "type": "string", "description": "New signing secret, shown once" } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook subscription id.", "schema": { "type": "string", "format": "uuid" } } ] } } }, "components": { "schemas": { "Customer": { "type": "object", "required": [ "name", "email", "document", "phone" ], "description": "Identity of the final customer for this transaction. It may default to the Cofri account profile, but should be supplied when the platform acts for multiple customers.", "properties": { "name": { "type": "string", "minLength": 2 }, "email": { "type": "string", "format": "email" }, "document": { "type": "string", "pattern": "^(\\d{11}|\\d{14})$", "description": "Final customer CPF or CNPJ, digits only." }, "phone": { "type": "string", "pattern": "^\\d{10,11}$" } } }, "WebhookEvent": { "type": "string", "enum": [ "market.buy.pending", "market.buy.completed", "market.buy.expired", "market.buy.failed", "market.buy.disputed", "market.sell.pending", "market.sell.risk_review", "market.sell.processing", "market.sell.completed", "market.sell.failed", "market.sell.cancelled", "risk.dispute.created", "risk.dispute.released" ] }, "Error": { "type": "object", "required": [ "status", "message", "code", "timestamp" ], "properties": { "status": { "const": false }, "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNAUTHORIZED", "VALIDATION_ERROR", "RATE_LIMIT_EXCEEDED", "INTERNAL_ERROR", "INVALID_API_KEY", "INSUFFICIENT_FUNDS", "ASSET_NOT_FOUND", "AMOUNT_BELOW_MINIMUM", "AMOUNT_ABOVE_LIMIT", "ACCOUNT_LIMIT_EXCEEDED", "SIGNATURE_REQUIRED", "SIGNATURE_EXPIRED", "INVALID_SIGNATURE", "REPLAY_DETECTED", "IDEMPOTENCY_KEY_REQUIRED", "INVALID_IDEMPOTENCY_KEY", "IDEMPOTENCY_CONFLICT", "OPERATION_IN_PROGRESS", "PIX_PROVIDER_UNAVAILABLE", "QR_EXPIRED", "PROVIDER_CONFIRMATION_PENDING", "INVALID_FEE_CONFIGURATION" ] }, "errors": { "type": "object", "additionalProperties": true }, "timestamp": { "type": "integer" } } }, "SuccessEnvelope": { "type": "object", "required": [ "status", "message", "data", "timestamp" ], "properties": { "status": { "const": true }, "message": { "type": "string" }, "data": {}, "timestamp": { "type": "integer", "description": "Unix timestamp" } } }, "SellOrder": { "type": "object", "required": [ "id", "external_reference", "asset", "amount", "gross_brl", "fee", "net_brl", "pix_key_type", "pix_key_masked", "status", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "external_reference": { "type": "string" }, "asset": { "const": "DePix" }, "amount": { "type": "number" }, "gross_brl": { "type": "number" }, "fee": { "type": "number" }, "net_brl": { "type": "number" }, "pix_key_type": { "type": "string", "enum": [ "CPF", "CNPJ", "EMAIL", "PHONE", "EVP" ] }, "pix_key_masked": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "risk_review", "processing", "completed", "failed", "cancelled" ] }, "failure_code": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Beneficiary": { "type": "object", "required": [ "name", "document" ], "properties": { "name": { "type": "string", "minLength": 2 }, "document": { "type": "string", "pattern": "^(\\d{11}|\\d{14})$", "description": "Beneficiary CPF or CNPJ, digits only." } } }, "BuyCreated": { "type": "object", "required": [ "id", "order_id", "external_reference", "qr_code", "amount", "fee", "net_amount", "asset", "expires_at", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "order_id": { "type": "string", "format": "uuid" }, "external_reference": { "type": "string" }, "qr_code": { "type": "string", "description": "Pix copy-and-paste code" }, "qr_image": { "type": [ "string", "null" ] }, "amount": { "type": "number" }, "fee": { "type": "number" }, "fee_fixed": { "type": "number" }, "fee_percent": { "type": "number" }, "net_amount": { "type": "number" }, "asset": { "const": "DePix" }, "expires_at": { "type": "string", "format": "date-time" }, "status": { "const": "pending_payment" } } }, "BuyOrder": { "type": "object", "required": [ "id", "external_reference", "asset", "amount", "fee", "net_amount", "status", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "external_reference": { "type": "string" }, "asset": { "const": "DePix" }, "amount": { "type": "number", "format": "double" }, "fee": { "type": "number" }, "fee_percent": { "type": "number" }, "net_amount": { "type": "number" }, "status": { "type": "string", "enum": [ "pending_payment", "paid", "processing", "completed", "expired", "failed", "cancelled", "disputed" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "failure_code": { "type": [ "string", "null" ] }, "failure_reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookPayload": { "type": "object", "required": [ "id", "event", "created_at", "api_version", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable event id used for deduplication." }, "event": { "oneOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "const": "test", "description": "Diagnostic delivery emitted by POST /webhook/test." } ] }, "created_at": { "type": "string", "format": "date-time" }, "api_version": { "type": "string" }, "data": { "anyOf": [ { "$ref": "#/components/schemas/DisputeCreatedEvent" }, { "$ref": "#/components/schemas/BuyDisputedEvent" }, { "$ref": "#/components/schemas/DisputeReleasedEvent" }, { "type": "object", "additionalProperties": true } ], "description": "Event-specific payload. Typed dispute variants are included below; other event payloads remain forward-compatible." } } }, "DisputeCreatedEvent": { "type": "object", "description": "data payload for the risk.dispute.created event.", "required": [ "order_id", "amount", "asset", "balance_negative" ], "properties": { "order_id": { "type": "string", "format": "uuid" }, "amount": { "type": "number", "description": "DePix amount withheld, in DePix units" }, "asset": { "const": "DePix" }, "balance_negative": { "type": "boolean", "description": "True if the withheld amount had already been spent, leaving the account balance negative" } } }, "BuyDisputedEvent": { "type": "object", "description": "data payload for the market.buy.disputed event.", "required": [ "id", "status", "amount", "withheld_amount", "reason" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "buy order id" }, "status": { "const": "disputed" }, "amount": { "type": "number", "description": "Original order amount, in BRL" }, "withheld_amount": { "type": "number", "description": "DePix amount withheld, in DePix units" }, "reason": { "type": "string" } } }, "DisputeReleasedEvent": { "type": "object", "description": "data payload for the risk.dispute.released event — the disputed buy order completes and the withheld amount is credited back.", "required": [ "order_id", "amount", "asset", "reason" ], "properties": { "order_id": { "type": "string", "format": "uuid" }, "amount": { "type": "number" }, "asset": { "type": "string" }, "reason": { "type": "string" } } } }, "responses": { "Error503": { "description": "Pix rail temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error403": { "description": "Scope, account or policy denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error401": { "description": "Invalid or expired credentials/signature", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error422": { "description": "Validation or business rule error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error409": { "description": "Idempotency/replay conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Error404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": { "Page": { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "Id": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 128 }, "description": "Required for signed machine financial requests." }, "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Requires the three HMAC headers described above." } } }, "security": [], "webhooks": { "cofriEvent": { "post": { "tags": [ "Webhooks" ], "summary": "Receive a Cofri event delivery", "operationId": "receiveCofriWebhookEvent", "description": "Implement this HTTPS callback on the client platform. Verify `X-Cofri-Signature` as `sha256=`, reject stale timestamps, return any 2xx only after durable receipt, and deduplicate by payload `id`.", "parameters": [ { "name": "X-Cofri-Event", "in": "header", "required": true, "schema": { "oneOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "const": "test", "description": "Diagnostic delivery emitted by POST /webhook/test." } ] } }, { "name": "X-Cofri-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^sha256=[a-f0-9]{64}$" } }, { "name": "X-Cofri-Timestamp", "in": "header", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "X-Cofri-Delivery", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" }, "examples": { "market.buy.completed": { "summary": "Successful Pix cash-in", "value": { "id": "9c3b2b8e-2f9e-4a1e-9b0a-8f1c2a3b4c5d", "event": "market.buy.completed", "created_at": "2026-08-03T14:02:11Z", "api_version": "1.0.0", "data": { "id": "b0c1d2e3-f4a5-4678-9b0c-d1e2f3a4b5c6", "status": "completed", "amount": 100.0, "net_amount": 97.0 } } }, "market.sell.completed": { "summary": "Successful Pix cash-out", "value": { "id": "1a2b3c4d-5e6f-4789-8a0b-1c2d3e4f5a6b", "event": "market.sell.completed", "created_at": "2026-08-03T14:10:05Z", "api_version": "1.0.0", "data": { "id": "c4d5e6f7-a8b9-4012-8c3d-4e5f6a7b8c9d", "status": "completed", "net_brl": 194.0 } } }, "market.buy.disputed": { "summary": "Buy order placed under chargeback dispute — amount already credited may be reversed", "value": { "id": "5e6f7a8b-9c0d-4123-8e4f-5a6b7c8d9e0f", "event": "market.buy.disputed", "created_at": "2026-08-03T15:00:00Z", "api_version": "1.0.0", "data": { "id": "b0c1d2e3-f4a5-4678-9b0c-d1e2f3a4b5c6", "status": "disputed", "amount": 100.0, "withheld_amount": 97.0, "reason": "Chargeback reported by payer's bank" } } }, "risk.dispute.created": { "summary": "Funds withheld pending dispute review", "value": { "id": "7a8b9c0d-1e2f-4345-8a6b-7c8d9e0f1a2b", "event": "risk.dispute.created", "created_at": "2026-08-03T15:00:00Z", "api_version": "1.0.0", "data": { "order_id": "b0c1d2e3-f4a5-4678-9b0c-d1e2f3a4b5c6", "amount": 97.0, "asset": "DePix", "balance_negative": false } } }, "risk.dispute.released": { "summary": "Dispute resolved in the buyer's favor — withheld amount released", "value": { "id": "9d0e1f2a-3b4c-4567-8d8e-9f0a1b2c3d4e", "event": "risk.dispute.released", "created_at": "2026-08-04T09:15:00Z", "api_version": "1.0.0", "data": { "order_id": "b0c1d2e3-f4a5-4678-9b0c-d1e2f3a4b5c6", "amount": 97.0, "asset": "DePix", "reason": "Dispute closed, no fraud confirmed" } } } } } } }, "responses": { "200": { "description": "Delivery durably accepted." }, "400": { "description": "Invalid payload or signature." } } } } } }