{ "openapi": "3.1.0", "info": { "title": "Mivy — API de recebimentos", "version": "1.0.0", "description": "Rotas reais do backend Mivy. Tokens são criados no painel e pertencem a uma loja. Todos os valores são em BRL. Exemplos não representam cobranças reais." }, "servers": [ { "url": "https://api.mivy.com.br/api/v1", "description": "Backend oficial Mivy" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Recebimentos", "description": "Depósitos Pix, consulta de pagamentos e saldo da loja." } ], "paths": { "/status": { "get": { "summary": "Verificar autenticação e permissões", "operationId": "getStatus", "tags": [ "Recebimentos" ], "responses": { "400": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de 120 chamadas por minuto por chave.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Segundos até uma nova tentativa.", "schema": { "type": "integer", "minimum": 1 } } } }, "200": { "description": "Chave autenticada.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Status" } } } } } } } } }, "/balance": { "get": { "summary": "Consultar o saldo disponível da loja", "operationId": "getBalance", "tags": [ "Recebimentos" ], "x-mivy-permission": "balance:read", "responses": { "400": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de 120 chamadas por minuto por chave.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Segundos até uma nova tentativa.", "schema": { "type": "integer", "minimum": 1 } } } }, "200": { "description": "Saldo em reais.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Balance" } } } } } } } } }, "/payments": { "post": { "summary": "Criar um depósito Pix para a carteira da loja", "operationId": "createPayment", "tags": [ "Recebimentos" ], "x-mivy-permission": "payments:create", "responses": { "400": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de 120 chamadas por minuto por chave.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Segundos até uma nova tentativa.", "schema": { "type": "integer", "minimum": 1 } } } }, "201": { "description": "Nova cobrança criada.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } } } }, "200": { "description": "Cobrança existente para o mesmo UUID e corpo.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } } } } }, "description": "Não credita a carteira até o pagamento ser confirmado. Reutilize o UUID e o mesmo corpo em novas tentativas. Máximo de 8 KiB no corpo. Taxas conforme o plano da loja.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "UUID persistido junto do seu pedido antes da chamada. Mesmo UUID com outros dados retorna 409.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePayment" }, "example": { "amount": 100, "currency": "BRL", "description": "Pedido 123", "passFee": false, "validityMinutes": 30 } } } } }, "get": { "summary": "Listar recebimentos da API da loja", "operationId": "listPayments", "tags": [ "Recebimentos" ], "x-mivy-permission": "payments:read", "responses": { "400": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de 120 chamadas por minuto por chave.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Segundos até uma nova tentativa.", "schema": { "type": "integer", "minimum": 1 } } } }, "200": { "description": "Lista ordenada por data; sem qrCode em cada recebimento.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } } }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ] } }, "/payments/{id}": { "get": { "summary": "Consultar um recebimento pelo ID", "operationId": "getPayment", "tags": [ "Recebimentos" ], "x-mivy-permission": "payments:read", "responses": { "400": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Falha; o corpo contém error e pode conter code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite de 120 chamadas por minuto por chave.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Segundos até uma nova tentativa.", "schema": { "type": "integer", "minimum": 1 } } } }, "200": { "description": "Recebimento desta loja.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,100}$" } } ] } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "mivy_live_...", "description": "Chave da loja criada em Integrações → API." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" } } }, "Payment": { "type": "object", "required": [ "id", "status", "amount", "requestedAmount", "fee", "netAmount", "currency", "description", "passFee", "pixCode", "validityMinutes", "expiresAt", "paidAt", "createdAt" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "CREATING", "PENDING", "PAID", "EXPIRED", "FAILED" ] }, "amount": { "type": "number", "description": "Valor em reais." }, "requestedAmount": { "type": "number", "description": "Valor em reais." }, "fee": { "type": "number", "description": "Valor em reais." }, "netAmount": { "type": "number", "description": "Valor em reais." }, "currency": { "type": "string", "const": "BRL" }, "description": { "type": [ "string", "null" ], "maxLength": 80 }, "passFee": { "type": "boolean" }, "pixCode": { "type": [ "string", "null" ] }, "qrCode": { "type": [ "string", "null" ], "description": "Imagem retornada na criação/consulta individual; não incluída na lista." }, "validityMinutes": { "type": "integer", "enum": [ 30, 60, 360, 1440, 2880, 10080 ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "paidAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "CreatePayment": { "type": "object", "additionalProperties": false, "required": [ "amount" ], "properties": { "amount": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000, "multipleOf": 0.01, "description": "Em reais. O total com taxas deve ser de até R$ 1.000 e o líquido deve ser positivo." }, "currency": { "type": "string", "enum": [ "BRL" ], "default": "BRL" }, "description": { "type": "string", "maxLength": 80, "default": "" }, "passFee": { "type": "boolean", "default": false }, "validityMinutes": { "type": "integer", "enum": [ 30, 60, 360, 1440, 2880, 10080 ], "default": 30 } } }, "Balance": { "type": "object", "required": [ "availableBalance", "currency" ], "properties": { "availableBalance": { "type": "number", "minimum": 0, "description": "Saldo disponível da carteira da loja, em reais." }, "currency": { "type": "string", "const": "BRL" } } }, "Status": { "type": "object", "required": [ "authenticated", "permissions", "withdrawalsEnabled" ], "properties": { "authenticated": { "type": "boolean", "const": true }, "permissions": { "type": "array", "items": { "type": "string" } }, "withdrawalsEnabled": { "type": "boolean", "const": false } } }, "Pagination": { "type": "object", "required": [ "page", "limit", "total" ], "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 1000 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "total": { "type": "integer", "minimum": 0 } } }, "PaymentEvent": { "type": "object", "required": [ "id", "type", "createdAt", "storeId", "data" ], "properties": { "id": { "type": "string", "description": "ID idempotente do evento." }, "type": { "type": "string", "enum": [ "payment.created", "payment.approved", "payment.expired", "payment.failed" ] }, "createdAt": { "type": "string", "format": "date-time" }, "storeId": { "type": "string" }, "data": { "type": "object", "required": [ "paymentId", "source", "status" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "CREATING", "PENDING", "PAID", "EXPIRED", "FAILED" ] }, "amount": { "type": "number", "description": "Valor em reais." }, "requestedAmount": { "type": "number", "description": "Valor em reais." }, "fee": { "type": "number", "description": "Valor em reais." }, "netAmount": { "type": "number", "description": "Valor em reais." }, "currency": { "type": "string", "const": "BRL" }, "description": { "type": [ "string", "null" ], "maxLength": 80 }, "passFee": { "type": "boolean" }, "validityMinutes": { "type": "integer", "enum": [ 30, 60, 360, 1440, 2880, 10080 ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "paidAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "paymentId": { "type": "string" }, "source": { "type": "string", "const": "api" } } } } } } }, "webhooks": { "paymentEvents": { "post": { "summary": "Evento entregue pela Mivy ao seu endpoint HTTPS", "security": [], "description": "Cadastre seu próprio endpoint no painel Webhooks. HMAC-SHA256 sobre timestamp.corpo_original. Persistir e deduplicar pelo identificador de entrega antes de responder 2xx. A Mivy não envia Authorization: Bearer neste canal.", "parameters": [ { "name": "X-Mivy-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Nome do evento." }, { "name": "X-Mivy-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "ID preservado em reenvios." }, { "name": "X-Mivy-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=TIMESTAMP,v1=HMAC_SHA256_HEXADECIMAL" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentEvent" } } } }, "responses": { "204": { "description": "Entrega verificada e persistida." }, "401": { "description": "Assinatura inválida." }, "500": { "description": "Falha ao persistir; a Mivy pode tentar novamente." } } } } }, "x-mivy-websocket": { "url": "wss://api.mivy.com.br/api/realtime/ws", "authentication": { "op": "auth", "token": "mivy_ws_SEU_TOKEN" }, "authTimeoutSeconds": 10, "heartbeatSeconds": 20, "resume": "Envie after com a última sequência processada e persistida, como string.", "reference": "/docs/websocket" } }