{ "openapi": "3.1.0", "info": { "title": "API Wavewhite", "version": "1.0.0", "description": "API pública da Wavewhite para cobranças Pix. Autenticação por chave de API (`Authorization: Bearer `). Valores sempre em centavos (string decimal na resposta). Mutações financeiras exigem `Idempotency-Key`. Documentação: https://docs.wavewhite.com" }, "servers": [ { "url": "https://api.wavewhite.com", "description": "Produção" } ], "tags": [ { "name": "Cobranças Pix" }, { "name": "Saldo e extrato" }, { "name": "Saques" }, { "name": "Repasses" }, { "name": "Webhooks" }, { "name": "Chave de API" } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Chave de API gerada no painel Wavewhite (Desenvolvedores > Chaves de API)." } } }, "paths": { "/v1/pix/charges": { "post": { "operationId": "createCharge", "summary": "Criar cobrança Pix", "description": "Cria uma cobrança Pix e devolve o QR Code e o código copia e cola. Envie sempre os quatro dados do pagador (nome, CPF/CNPJ, e-mail e telefone): a emissão do Pix exige esses dados. Quando `status` vier `created` sem `pix`, o resultado da emissão ainda não é conhecido: consulte a cobrança depois e não crie outro pedido.", "tags": [ "Cobranças Pix" ], "security": [ { "apiKey": [] } ], "x-scopes": [ "charges:write" ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "minLength": 8, "maxLength": 200, "pattern": "^[\\x21-\\x7e]+$", "type": "string" }, "description": "Chave única por operação (8 a 200 caracteres ASCII visíveis). Repetir com o mesmo corpo devolve o mesmo resultado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "title": "CreateChargeRequest", "type": "object", "required": [ "order_reference", "amount_cents" ], "properties": { "order_reference": { "minLength": 1, "maxLength": 120, "type": "string", "description": "Identificador do pedido no seu sistema. Único por conta: não pode ser reutilizado em outra cobrança." }, "amount_cents": { "anyOf": [ { "minimum": 0, "maximum": 9007199254740991, "type": "integer" }, { "pattern": "^[0-9]{1,18}$", "type": "string" } ], "description": "Valor da cobrança em centavos, inteiro positivo (número JSON ou string decimal). `15990` = R$ 159,90." }, "currency": { "type": "string", "enum": [ "BRL" ], "description": "Moeda. Só `BRL`; pode ser omitida." }, "description": { "maxLength": 500, "type": "string", "description": "Descrição exibida para você no painel. Até 500 caracteres." }, "payer": { "additionalProperties": false, "type": "object", "properties": { "name": { "maxLength": 200, "type": "string", "description": "Nome completo do pagador (até 200 caracteres)." }, "document": { "pattern": "^([0-9]{11}|[0-9]{14})$", "type": "string", "description": "CPF (11 dígitos) ou CNPJ (14 dígitos) do pagador, só números." }, "email": { "maxLength": 254, "pattern": "^[^\\s@]{1,64}@[^\\s@]{1,190}\\.[^\\s@]{2,63}$", "type": "string", "description": "E-mail do pagador. Usado só para emitir o Pix; a Wavewhite não o grava." }, "phone": { "pattern": "^\\+?[0-9]{10,13}$", "type": "string", "description": "Telefone com DDD, só dígitos, com ou sem `+55` (ex.: `11987654321`). Usado só para emitir o Pix; a Wavewhite não o grava." } }, "description": "Dados do pagador. Exigidos para emitir o Pix: sem eles a emissão pode ser recusada." }, "expires_in_seconds": { "minimum": 60, "maximum": 604800, "type": "integer", "description": "Validade do QR em segundos, de 60 (1 minuto) a 604800 (7 dias). Padrão: 86400 (24 horas)." }, "metadata": { "maxProperties": 20, "type": "object", "additionalProperties": { "maxLength": 500, "type": "string" }, "description": "Até 20 pares chave/valor de texto para o seu controle (chave até 60 e valor até 500 caracteres)." } } } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "title": "Charge", "type": "object", "required": [ "id", "gateway_id", "environment", "order_reference", "amount_cents", "currency", "description", "status", "fee_percent_bps", "fee_fixed_cents", "fee_cents", "net_cents", "reserve_cents", "refunded_cents", "expires_at", "paid_at", "late_payment", "is_simulated", "created_at", "updated_at", "pix", "end_to_end_id", "payments_count", "failure_message" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador da cobrança na Wavewhite." }, "gateway_id": { "format": "uuid", "type": "string", "description": "Identificador da sua conta na Wavewhite." }, "environment": { "anyOf": [ { "type": "string", "enum": [ "sandbox" ] }, { "type": "string", "enum": [ "production" ] } ], "description": "Ambiente da cobrança: `production` (`sandbox` está reservado para o ambiente de testes, em preparação)." }, "order_reference": { "type": "string", "description": "Identificador do pedido enviado por você." }, "amount_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor bruto da cobrança, em centavos (string decimal: \"15990\" = R$ 159,90)." }, "currency": { "type": "string", "enum": [ "BRL" ], "description": "Moeda (`BRL`)." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Descrição enviada na criação." }, "status": { "anyOf": [ { "type": "string", "enum": [ "created" ] }, { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "paid" ] }, { "type": "string", "enum": [ "partially_refunded" ] }, { "type": "string", "enum": [ "refunded" ] }, { "type": "string", "enum": [ "expired" ] }, { "type": "string", "enum": [ "cancelled" ] }, { "type": "string", "enum": [ "failed" ] } ], "description": "Estado da cobrança. Veja Estados da cobrança." }, "fee_percent_bps": { "type": "integer", "description": "Parte percentual da tarifa vigente na criação, em pontos-base (`200` = 2,00%)." }, "fee_fixed_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Parte fixa da tarifa por transação, em centavos." }, "fee_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Tarifa da Wavewhite sobre a venda, em centavos. `null` até o pagamento." }, "net_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Valor líquido da venda (bruto − tarifa), em centavos. `null` até o pagamento." }, "reserve_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Parte do líquido retida como reserva contratual, em centavos. `null` até o pagamento." }, "refunded_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Total já devolvido ao pagador, em centavos." }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Fim da validade do QR." }, "paid_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Momento do pagamento confirmado." }, "late_payment": { "type": "boolean", "description": "`true` quando o pagamento chegou depois da expiração (pagamento tardio)." }, "is_simulated": { "type": "boolean", "description": "`false` em produção. `true` fica reservado para cobranças do ambiente de testes (em preparação), sem dinheiro real." }, "created_at": { "format": "date-time", "type": "string", "description": "Criação da cobrança." }, "updated_at": { "format": "date-time", "type": "string", "description": "Última alteração." }, "pix": { "anyOf": [ { "type": "object", "required": [ "qr_code_payload", "txid", "expires_at" ], "properties": { "qr_code_payload": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Código Pix copia e cola (BR Code). Gere a imagem do QR Code a partir dele." }, "txid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador da transação Pix, quando a rede de processamento o informa. Pode vir `null` mesmo com o Pix emitido corretamente: não use este campo para decidir se a cobrança foi criada. Para isso, confira `status` e `pix.qr_code_payload`; para identificar a cobrança, use `id` ou `order_reference`." }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Fim da validade deste QR." } } }, { "type": "null" } ], "description": "QR vigente. `null` enquanto a emissão não terminou ou quando a cobrança foi recusada." }, "end_to_end_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador fim a fim (E2E) do Pix recebido. Preenchido quando paga." }, "payments_count": { "type": "integer", "description": "Quantidade de pagamentos recebidos para esta cobrança (inclui duplicados)." }, "failure_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Quando `status` é `failed`: motivo da recusa em texto fixo da Wavewhite, próprio para exibir (ex.: `Emissão recusada pela análise de risco.`). Os textos possíveis estão em Estados da cobrança. `null` nos demais estados." } } } } } }, "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "title": "Charge", "type": "object", "required": [ "id", "gateway_id", "environment", "order_reference", "amount_cents", "currency", "description", "status", "fee_percent_bps", "fee_fixed_cents", "fee_cents", "net_cents", "reserve_cents", "refunded_cents", "expires_at", "paid_at", "late_payment", "is_simulated", "created_at", "updated_at", "pix", "end_to_end_id", "payments_count", "failure_message" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador da cobrança na Wavewhite." }, "gateway_id": { "format": "uuid", "type": "string", "description": "Identificador da sua conta na Wavewhite." }, "environment": { "anyOf": [ { "type": "string", "enum": [ "sandbox" ] }, { "type": "string", "enum": [ "production" ] } ], "description": "Ambiente da cobrança: `production` (`sandbox` está reservado para o ambiente de testes, em preparação)." }, "order_reference": { "type": "string", "description": "Identificador do pedido enviado por você." }, "amount_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor bruto da cobrança, em centavos (string decimal: \"15990\" = R$ 159,90)." }, "currency": { "type": "string", "enum": [ "BRL" ], "description": "Moeda (`BRL`)." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Descrição enviada na criação." }, "status": { "anyOf": [ { "type": "string", "enum": [ "created" ] }, { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "paid" ] }, { "type": "string", "enum": [ "partially_refunded" ] }, { "type": "string", "enum": [ "refunded" ] }, { "type": "string", "enum": [ "expired" ] }, { "type": "string", "enum": [ "cancelled" ] }, { "type": "string", "enum": [ "failed" ] } ], "description": "Estado da cobrança. Veja Estados da cobrança." }, "fee_percent_bps": { "type": "integer", "description": "Parte percentual da tarifa vigente na criação, em pontos-base (`200` = 2,00%)." }, "fee_fixed_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Parte fixa da tarifa por transação, em centavos." }, "fee_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Tarifa da Wavewhite sobre a venda, em centavos. `null` até o pagamento." }, "net_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Valor líquido da venda (bruto − tarifa), em centavos. `null` até o pagamento." }, "reserve_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Parte do líquido retida como reserva contratual, em centavos. `null` até o pagamento." }, "refunded_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Total já devolvido ao pagador, em centavos." }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Fim da validade do QR." }, "paid_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Momento do pagamento confirmado." }, "late_payment": { "type": "boolean", "description": "`true` quando o pagamento chegou depois da expiração (pagamento tardio)." }, "is_simulated": { "type": "boolean", "description": "`false` em produção. `true` fica reservado para cobranças do ambiente de testes (em preparação), sem dinheiro real." }, "created_at": { "format": "date-time", "type": "string", "description": "Criação da cobrança." }, "updated_at": { "format": "date-time", "type": "string", "description": "Última alteração." }, "pix": { "anyOf": [ { "type": "object", "required": [ "qr_code_payload", "txid", "expires_at" ], "properties": { "qr_code_payload": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Código Pix copia e cola (BR Code). Gere a imagem do QR Code a partir dele." }, "txid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador da transação Pix, quando a rede de processamento o informa. Pode vir `null` mesmo com o Pix emitido corretamente: não use este campo para decidir se a cobrança foi criada. Para isso, confira `status` e `pix.qr_code_payload`; para identificar a cobrança, use `id` ou `order_reference`." }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Fim da validade deste QR." } } }, { "type": "null" } ], "description": "QR vigente. `null` enquanto a emissão não terminou ou quando a cobrança foi recusada." }, "end_to_end_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador fim a fim (E2E) do Pix recebido. Preenchido quando paga." }, "payments_count": { "type": "integer", "description": "Quantidade de pagamentos recebidos para esta cobrança (inclui duplicados)." }, "failure_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Quando `status` é `failed`: motivo da recusa em texto fixo da Wavewhite, próprio para exibir (ex.: `Emissão recusada pela análise de risco.`). Os textos possíveis estão em Estados da cobrança. `null` nos demais estados." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "409": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "422": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "503": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } }, "get": { "operationId": "listCharges", "summary": "Listar cobranças", "description": "Lista as cobranças da conta, das mais recentes para as mais antigas, com filtros e paginação por cursor.", "tags": [ "Cobranças Pix" ], "security": [ { "apiKey": [] } ], "x-scopes": [ "charges:read" ], "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "created" ] }, { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "paid" ] }, { "type": "string", "enum": [ "partially_refunded" ] }, { "type": "string", "enum": [ "refunded" ] }, { "type": "string", "enum": [ "expired" ] }, { "type": "string", "enum": [ "cancelled" ] }, { "type": "string", "enum": [ "failed" ] } ] }, "description": "Filtra pelo estado da cobrança." }, { "in": "query", "name": "order_reference", "required": false, "schema": { "maxLength": 120, "type": "string" }, "description": "Filtra pelo seu identificador do pedido (valor exato)." }, { "in": "query", "name": "created_from", "required": false, "schema": { "format": "date-time", "type": "string" }, "description": "Criadas a partir deste instante (inclusivo, ISO-8601)." }, { "in": "query", "name": "created_to", "required": false, "schema": { "format": "date-time", "type": "string" }, "description": "Criadas antes deste instante (exclusivo, ISO-8601)." }, { "in": "query", "name": "q", "required": false, "schema": { "minLength": 1, "maxLength": 120, "type": "string" }, "description": "Busca por referência do pedido, id da cobrança, txid, E2E, nome ou documento do pagador." }, { "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 2000, "type": "string" }, "description": "Cursor devolvido em `next_cursor` da página anterior." }, { "in": "query", "name": "limit", "required": false, "schema": { "minimum": 1, "maximum": 200, "type": "integer" }, "description": "Itens por página." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "title": "Charge", "type": "object", "required": [ "id", "gateway_id", "environment", "order_reference", "amount_cents", "currency", "description", "status", "fee_percent_bps", "fee_fixed_cents", "fee_cents", "net_cents", "reserve_cents", "refunded_cents", "expires_at", "paid_at", "late_payment", "is_simulated", "created_at", "updated_at", "pix", "end_to_end_id", "payments_count", "failure_message" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador da cobrança na Wavewhite." }, "gateway_id": { "format": "uuid", "type": "string", "description": "Identificador da sua conta na Wavewhite." }, "environment": { "anyOf": [ { "type": "string", "enum": [ "sandbox" ] }, { "type": "string", "enum": [ "production" ] } ], "description": "Ambiente da cobrança: `production` (`sandbox` está reservado para o ambiente de testes, em preparação)." }, "order_reference": { "type": "string", "description": "Identificador do pedido enviado por você." }, "amount_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor bruto da cobrança, em centavos (string decimal: \"15990\" = R$ 159,90)." }, "currency": { "type": "string", "enum": [ "BRL" ], "description": "Moeda (`BRL`)." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Descrição enviada na criação." }, "status": { "anyOf": [ { "type": "string", "enum": [ "created" ] }, { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "paid" ] }, { "type": "string", "enum": [ "partially_refunded" ] }, { "type": "string", "enum": [ "refunded" ] }, { "type": "string", "enum": [ "expired" ] }, { "type": "string", "enum": [ "cancelled" ] }, { "type": "string", "enum": [ "failed" ] } ], "description": "Estado da cobrança. Veja Estados da cobrança." }, "fee_percent_bps": { "type": "integer", "description": "Parte percentual da tarifa vigente na criação, em pontos-base (`200` = 2,00%)." }, "fee_fixed_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Parte fixa da tarifa por transação, em centavos." }, "fee_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Tarifa da Wavewhite sobre a venda, em centavos. `null` até o pagamento." }, "net_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Valor líquido da venda (bruto − tarifa), em centavos. `null` até o pagamento." }, "reserve_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Parte do líquido retida como reserva contratual, em centavos. `null` até o pagamento." }, "refunded_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Total já devolvido ao pagador, em centavos." }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Fim da validade do QR." }, "paid_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Momento do pagamento confirmado." }, "late_payment": { "type": "boolean", "description": "`true` quando o pagamento chegou depois da expiração (pagamento tardio)." }, "is_simulated": { "type": "boolean", "description": "`false` em produção. `true` fica reservado para cobranças do ambiente de testes (em preparação), sem dinheiro real." }, "created_at": { "format": "date-time", "type": "string", "description": "Criação da cobrança." }, "updated_at": { "format": "date-time", "type": "string", "description": "Última alteração." }, "pix": { "anyOf": [ { "type": "object", "required": [ "qr_code_payload", "txid", "expires_at" ], "properties": { "qr_code_payload": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Código Pix copia e cola (BR Code). Gere a imagem do QR Code a partir dele." }, "txid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador da transação Pix, quando a rede de processamento o informa. Pode vir `null` mesmo com o Pix emitido corretamente: não use este campo para decidir se a cobrança foi criada. Para isso, confira `status` e `pix.qr_code_payload`; para identificar a cobrança, use `id` ou `order_reference`." }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Fim da validade deste QR." } } }, { "type": "null" } ], "description": "QR vigente. `null` enquanto a emissão não terminou ou quando a cobrança foi recusada." }, "end_to_end_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador fim a fim (E2E) do Pix recebido. Preenchido quando paga." }, "payments_count": { "type": "integer", "description": "Quantidade de pagamentos recebidos para esta cobrança (inclui duplicados)." }, "failure_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Quando `status` é `failed`: motivo da recusa em texto fixo da Wavewhite, próprio para exibir (ex.: `Emissão recusada pela análise de risco.`). Os textos possíveis estão em Estados da cobrança. `null` nos demais estados." } } }, "description": "Itens da página." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor da próxima página; `null` quando não há mais itens." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "422": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/pix/charges/{id}": { "get": { "operationId": "getCharge", "summary": "Consultar cobrança", "description": "Devolve a cobrança com o estado atual, o QR vigente e, quando paga, a tarifa e o valor líquido. Use esta consulta para confirmar um pagamento recebido por webhook.", "tags": [ "Cobranças Pix" ], "security": [ { "apiKey": [] } ], "x-scopes": [ "charges:read" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "Identificador da cobrança." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "title": "Charge", "type": "object", "required": [ "id", "gateway_id", "environment", "order_reference", "amount_cents", "currency", "description", "status", "fee_percent_bps", "fee_fixed_cents", "fee_cents", "net_cents", "reserve_cents", "refunded_cents", "expires_at", "paid_at", "late_payment", "is_simulated", "created_at", "updated_at", "pix", "end_to_end_id", "payments_count", "failure_message" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador da cobrança na Wavewhite." }, "gateway_id": { "format": "uuid", "type": "string", "description": "Identificador da sua conta na Wavewhite." }, "environment": { "anyOf": [ { "type": "string", "enum": [ "sandbox" ] }, { "type": "string", "enum": [ "production" ] } ], "description": "Ambiente da cobrança: `production` (`sandbox` está reservado para o ambiente de testes, em preparação)." }, "order_reference": { "type": "string", "description": "Identificador do pedido enviado por você." }, "amount_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor bruto da cobrança, em centavos (string decimal: \"15990\" = R$ 159,90)." }, "currency": { "type": "string", "enum": [ "BRL" ], "description": "Moeda (`BRL`)." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Descrição enviada na criação." }, "status": { "anyOf": [ { "type": "string", "enum": [ "created" ] }, { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "paid" ] }, { "type": "string", "enum": [ "partially_refunded" ] }, { "type": "string", "enum": [ "refunded" ] }, { "type": "string", "enum": [ "expired" ] }, { "type": "string", "enum": [ "cancelled" ] }, { "type": "string", "enum": [ "failed" ] } ], "description": "Estado da cobrança. Veja Estados da cobrança." }, "fee_percent_bps": { "type": "integer", "description": "Parte percentual da tarifa vigente na criação, em pontos-base (`200` = 2,00%)." }, "fee_fixed_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Parte fixa da tarifa por transação, em centavos." }, "fee_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Tarifa da Wavewhite sobre a venda, em centavos. `null` até o pagamento." }, "net_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Valor líquido da venda (bruto − tarifa), em centavos. `null` até o pagamento." }, "reserve_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Parte do líquido retida como reserva contratual, em centavos. `null` até o pagamento." }, "refunded_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Total já devolvido ao pagador, em centavos." }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Fim da validade do QR." }, "paid_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Momento do pagamento confirmado." }, "late_payment": { "type": "boolean", "description": "`true` quando o pagamento chegou depois da expiração (pagamento tardio)." }, "is_simulated": { "type": "boolean", "description": "`false` em produção. `true` fica reservado para cobranças do ambiente de testes (em preparação), sem dinheiro real." }, "created_at": { "format": "date-time", "type": "string", "description": "Criação da cobrança." }, "updated_at": { "format": "date-time", "type": "string", "description": "Última alteração." }, "pix": { "anyOf": [ { "type": "object", "required": [ "qr_code_payload", "txid", "expires_at" ], "properties": { "qr_code_payload": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Código Pix copia e cola (BR Code). Gere a imagem do QR Code a partir dele." }, "txid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador da transação Pix, quando a rede de processamento o informa. Pode vir `null` mesmo com o Pix emitido corretamente: não use este campo para decidir se a cobrança foi criada. Para isso, confira `status` e `pix.qr_code_payload`; para identificar a cobrança, use `id` ou `order_reference`." }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Fim da validade deste QR." } } }, { "type": "null" } ], "description": "QR vigente. `null` enquanto a emissão não terminou ou quando a cobrança foi recusada." }, "end_to_end_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador fim a fim (E2E) do Pix recebido. Preenchido quando paga." }, "payments_count": { "type": "integer", "description": "Quantidade de pagamentos recebidos para esta cobrança (inclui duplicados)." }, "failure_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Quando `status` é `failed`: motivo da recusa em texto fixo da Wavewhite, próprio para exibir (ex.: `Emissão recusada pela análise de risco.`). Os textos possíveis estão em Estados da cobrança. `null` nos demais estados." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "404": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/pix/charges/{id}/refunds": { "post": { "operationId": "requestRefund", "summary": "Solicitar devolução", "description": "Devolve ao pagador todo ou parte do valor de uma cobrança paga. O valor é bloqueado do seu saldo na hora e a devolução é processada em seguida; acompanhe pelo caso devolvido (`status`, `execution_status`) ou pelos eventos `case.resolved` e `charge.refunded`.", "tags": [ "Cobranças Pix" ], "security": [ { "apiKey": [] } ], "x-scopes": [ "refunds:write" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "Identificador da cobrança paga." }, { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "minLength": 8, "maxLength": 200, "pattern": "^[\\x21-\\x7e]+$", "type": "string" }, "description": "Chave única por operação (8 a 200 caracteres ASCII visíveis). Repetir com o mesmo corpo devolve o mesmo resultado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "title": "RefundRequest", "type": "object", "required": [ "amount_cents", "reason" ], "properties": { "amount_cents": { "anyOf": [ { "minimum": 0, "maximum": 9007199254740991, "type": "integer" }, { "pattern": "^[0-9]{1,18}$", "type": "string" } ], "description": "Valor a devolver em centavos. Pode ser parcial; a soma das devoluções não passa do valor pago." }, "reason": { "minLength": 3, "maxLength": 300, "type": "string", "description": "Motivo da devolução (3 a 300 caracteres)." } } } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "title": "Case", "type": "object", "required": [ "id", "gateway_id", "environment", "case_type", "status", "med_stage", "charge_id", "amount_cents", "held_cents", "shortfall_cents", "origin", "reason", "liability", "execution_status", "resolution", "resolution_note", "resolved_amount_cents", "opened_at", "due_at", "resolved_at" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador do caso." }, "gateway_id": { "format": "uuid", "type": "string", "description": "Identificador da sua conta na Wavewhite." }, "environment": { "anyOf": [ { "type": "string", "enum": [ "sandbox" ] }, { "type": "string", "enum": [ "production" ] } ], "description": "Ambiente: `production` (`sandbox` está reservado para o ambiente de testes, em preparação)." }, "case_type": { "type": "string", "description": "Tipo: `refund` (devolução), `med` (contestação Pix pelo Mecanismo Especial de Devolução), `precautionary_block` (bloqueio preventivo) ou outro tipo operacional (`contractual_retention`, `compensation`, `dispute`, `accounting_adjustment`)." }, "status": { "type": "string", "description": "Situação do caso: `open`, `in_review`, `awaiting_partner` (aguardando a rede de processamento), `resolved` ou `cancelled`." }, "med_stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Etapa da contestação MED (`notified`, `confirmed`, `returned`, `net_loss`, `dismissed`); `null` nos demais tipos." }, "charge_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Cobrança a que o caso se refere." }, "amount_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor do caso, em centavos." }, "held_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Quanto do seu saldo está bloqueado por este caso, em centavos." }, "shortfall_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Parte que não pôde ser bloqueada por falta de saldo, em centavos." }, "origin": { "type": "string", "description": "Quem originou o caso: `gateway` (você), `payer` (pagador, via MED), `koku`, `partner` (rede de processamento) ou `regulator`." }, "reason": { "type": "string", "description": "Motivo informado na abertura." }, "liability": { "type": "string", "description": "Quem responde pelo valor do caso: `gateway`, `koku`, `partner` ou `undetermined` (ainda não definido)." }, "execution_status": { "type": "string", "description": "Andamento da devolução: `none`, `queued`, `submitted`, `unknown`, `completed`, `failed`." }, "resolution": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resultado quando resolvido (ex.: `refunded`)." }, "resolution_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Observação da resolução: texto escrito pela equipe Wavewhite ao decidir o caso, ou um texto fixo quando a devolução não pôde ser executada. `null` quando não há observação." }, "resolved_amount_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Valor efetivamente devolvido, em centavos." }, "opened_at": { "format": "date-time", "type": "string", "description": "Abertura do caso." }, "due_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Prazo do caso, quando houver." }, "resolved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Resolução do caso." } } } } } }, "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "title": "Case", "type": "object", "required": [ "id", "gateway_id", "environment", "case_type", "status", "med_stage", "charge_id", "amount_cents", "held_cents", "shortfall_cents", "origin", "reason", "liability", "execution_status", "resolution", "resolution_note", "resolved_amount_cents", "opened_at", "due_at", "resolved_at" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador do caso." }, "gateway_id": { "format": "uuid", "type": "string", "description": "Identificador da sua conta na Wavewhite." }, "environment": { "anyOf": [ { "type": "string", "enum": [ "sandbox" ] }, { "type": "string", "enum": [ "production" ] } ], "description": "Ambiente: `production` (`sandbox` está reservado para o ambiente de testes, em preparação)." }, "case_type": { "type": "string", "description": "Tipo: `refund` (devolução), `med` (contestação Pix pelo Mecanismo Especial de Devolução), `precautionary_block` (bloqueio preventivo) ou outro tipo operacional (`contractual_retention`, `compensation`, `dispute`, `accounting_adjustment`)." }, "status": { "type": "string", "description": "Situação do caso: `open`, `in_review`, `awaiting_partner` (aguardando a rede de processamento), `resolved` ou `cancelled`." }, "med_stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Etapa da contestação MED (`notified`, `confirmed`, `returned`, `net_loss`, `dismissed`); `null` nos demais tipos." }, "charge_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Cobrança a que o caso se refere." }, "amount_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor do caso, em centavos." }, "held_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Quanto do seu saldo está bloqueado por este caso, em centavos." }, "shortfall_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Parte que não pôde ser bloqueada por falta de saldo, em centavos." }, "origin": { "type": "string", "description": "Quem originou o caso: `gateway` (você), `payer` (pagador, via MED), `koku`, `partner` (rede de processamento) ou `regulator`." }, "reason": { "type": "string", "description": "Motivo informado na abertura." }, "liability": { "type": "string", "description": "Quem responde pelo valor do caso: `gateway`, `koku`, `partner` ou `undetermined` (ainda não definido)." }, "execution_status": { "type": "string", "description": "Andamento da devolução: `none`, `queued`, `submitted`, `unknown`, `completed`, `failed`." }, "resolution": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resultado quando resolvido (ex.: `refunded`)." }, "resolution_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Observação da resolução: texto escrito pela equipe Wavewhite ao decidir o caso, ou um texto fixo quando a devolução não pôde ser executada. `null` quando não há observação." }, "resolved_amount_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Valor efetivamente devolvido, em centavos." }, "opened_at": { "format": "date-time", "type": "string", "description": "Abertura do caso." }, "due_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Prazo do caso, quando houver." }, "resolved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Resolução do caso." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "404": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "409": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "422": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/pix/charges/{id}/cases": { "get": { "operationId": "listChargeCases", "summary": "Devoluções e contestações da cobrança", "description": "Lista os casos ligados a uma cobrança: devoluções pedidas por você, contestações Pix (MED) e pagamentos retidos para devolução (duplicados ou tardios).", "tags": [ "Cobranças Pix" ], "security": [ { "apiKey": [] } ], "x-scopes": [ "charges:read", "statement:read" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "Identificador da cobrança." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "title": "Case", "type": "object", "required": [ "id", "gateway_id", "environment", "case_type", "status", "med_stage", "charge_id", "amount_cents", "held_cents", "shortfall_cents", "origin", "reason", "liability", "execution_status", "resolution", "resolution_note", "resolved_amount_cents", "opened_at", "due_at", "resolved_at" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador do caso." }, "gateway_id": { "format": "uuid", "type": "string", "description": "Identificador da sua conta na Wavewhite." }, "environment": { "anyOf": [ { "type": "string", "enum": [ "sandbox" ] }, { "type": "string", "enum": [ "production" ] } ], "description": "Ambiente: `production` (`sandbox` está reservado para o ambiente de testes, em preparação)." }, "case_type": { "type": "string", "description": "Tipo: `refund` (devolução), `med` (contestação Pix pelo Mecanismo Especial de Devolução), `precautionary_block` (bloqueio preventivo) ou outro tipo operacional (`contractual_retention`, `compensation`, `dispute`, `accounting_adjustment`)." }, "status": { "type": "string", "description": "Situação do caso: `open`, `in_review`, `awaiting_partner` (aguardando a rede de processamento), `resolved` ou `cancelled`." }, "med_stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Etapa da contestação MED (`notified`, `confirmed`, `returned`, `net_loss`, `dismissed`); `null` nos demais tipos." }, "charge_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Cobrança a que o caso se refere." }, "amount_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor do caso, em centavos." }, "held_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Quanto do seu saldo está bloqueado por este caso, em centavos." }, "shortfall_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Parte que não pôde ser bloqueada por falta de saldo, em centavos." }, "origin": { "type": "string", "description": "Quem originou o caso: `gateway` (você), `payer` (pagador, via MED), `koku`, `partner` (rede de processamento) ou `regulator`." }, "reason": { "type": "string", "description": "Motivo informado na abertura." }, "liability": { "type": "string", "description": "Quem responde pelo valor do caso: `gateway`, `koku`, `partner` ou `undetermined` (ainda não definido)." }, "execution_status": { "type": "string", "description": "Andamento da devolução: `none`, `queued`, `submitted`, `unknown`, `completed`, `failed`." }, "resolution": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resultado quando resolvido (ex.: `refunded`)." }, "resolution_note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Observação da resolução: texto escrito pela equipe Wavewhite ao decidir o caso, ou um texto fixo quando a devolução não pôde ser executada. `null` quando não há observação." }, "resolved_amount_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Valor efetivamente devolvido, em centavos." }, "opened_at": { "format": "date-time", "type": "string", "description": "Abertura do caso." }, "due_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Prazo do caso, quando houver." }, "resolved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Resolução do caso." } } }, "description": "Itens da página." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "404": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/balance": { "get": { "operationId": "getBalance", "summary": "Consultar saldo", "description": "Mostra a sua posição na Wavewhite: o que está pendente de liquidação, o que já está disponível, reservas, bloqueios e quanto você tem a receber.", "tags": [ "Saldo e extrato" ], "security": [ { "apiKey": [] } ], "x-scopes": [ "balance:read" ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "title": "Balance", "type": "object", "required": [ "currency", "pending_cents", "available_cents", "contract_reserve_cents", "blocked_cents", "payout_reserved_cents", "total_cents", "owed_to_koku_cents", "payouts_suspended", "suspension_reasons", "payouts_by_koku", "payouts_by_koku_message", "available_for_payout_cents", "to_receive_cents", "as_of" ], "properties": { "currency": { "type": "string", "enum": [ "BRL" ], "description": "Moeda (`BRL`)." }, "pending_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Vendas pagas ainda não liberadas para saque (adquirente que libera só depois da liquidação conciliada), em centavos." }, "available_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor liberado para saque (na hora ou depois da liquidação, conforme a adquirente), em centavos." }, "contract_reserve_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Reserva contratual (continua sendo sua; é liberada conforme o contrato), em centavos." }, "blocked_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Bloqueado por devolução, contestação ou pagamento retido, em centavos." }, "payout_reserved_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Reservado para saques pedidos e ainda não pagos, em centavos." }, "total_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Soma das posições acima, em centavos." }, "owed_to_koku_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor devido à Wavewhite (por exemplo, devolução maior que o saldo), em centavos." }, "payouts_suspended": { "type": "boolean", "description": "`true` quando os repasses estão suspensos (veja `suspension_reasons`)." }, "suspension_reasons": { "type": "array", "items": { "type": "string" }, "description": "Motivos da suspensão dos repasses." }, "payouts_by_koku": { "type": "boolean", "description": "`true` quando os repasses são feitos pela Wavewhite conforme o contrato: você pede o saque pelo painel ou pela API, a qualquer hora, e a Wavewhite aprova e transfere." }, "payouts_by_koku_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Mensagem para exibir quando os repasses são feitos pela Wavewhite." }, "available_for_payout_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Quanto você pode pedir de saque agora (o disponível), em centavos." }, "to_receive_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Total a receber da Wavewhite: pendente + disponível + reserva contratual (sem o bloqueado), em centavos." }, "as_of": { "format": "date-time", "type": "string", "description": "Momento da leitura do saldo." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/statement": { "get": { "operationId": "getStatement", "summary": "Consultar extrato", "description": "Lista os lançamentos que movimentaram o seu saldo. Cada venda traz bruto, tarifa e líquido; cada devolução ou contestação traz o caso e o pedido a que se refere.", "tags": [ "Saldo e extrato" ], "security": [ { "apiKey": [] } ], "x-scopes": [ "statement:read" ], "parameters": [ { "in": "query", "name": "from", "required": false, "schema": { "format": "date-time", "type": "string" }, "description": "Início do período (inclusivo, ISO-8601). Padrão: 30 dias antes de `to`." }, { "in": "query", "name": "to", "required": false, "schema": { "format": "date-time", "type": "string" }, "description": "Fim do período (exclusivo, ISO-8601). Padrão: agora." }, { "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 2000, "type": "string" }, "description": "Cursor devolvido em `next_cursor` da página anterior." }, { "in": "query", "name": "limit", "required": false, "schema": { "minimum": 1, "maximum": 500, "type": "integer" }, "description": "Itens por página." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_cursor", "as_of" ], "properties": { "items": { "type": "array", "items": { "title": "StatementEntry", "type": "object", "required": [ "journal_id", "line_no", "event_type", "description", "economic_at", "posted_at", "position", "amount_cents", "source_type", "source_id", "is_reversal", "sale", "payout", "financial_case" ], "properties": { "journal_id": { "format": "uuid", "type": "string", "description": "Identificador do lançamento contábil (vários itens podem compartilhar o mesmo)." }, "line_no": { "type": "integer", "description": "Linha dentro do lançamento." }, "event_type": { "type": "string", "description": "Fato que gerou o lançamento. Os mais comuns: `charge.paid` (venda paga), `gateway.funds_available` (líquido da venda liberado para saque), `gateway.external_payout` (repasse feito pela Wavewhite para a sua conta bancária), `case.hold` e `refund.completed` (devolução). A lista completa está em Saldo e extrato." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Descrição em texto fixo da Wavewhite para o tipo de lançamento (ex.: `Repasse feito pela Wavewhite (E2E...)`). Use `event_type` para decidir no código." }, "economic_at": { "format": "date-time", "type": "string", "description": "Data econômica do fato (é a data usada no filtro `from`/`to`)." }, "posted_at": { "format": "date-time", "type": "string", "description": "Momento do registro." }, "position": { "type": "string", "description": "Posição do saldo afetada: `pending`, `available`, `contract_reserve`, `case_hold`, `payout_reserved` ou `receivable`." }, "amount_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Efeito na posição, em centavos: positivo aumenta, negativo reduz." }, "source_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tipo do objeto de origem: `charge` (cobrança e venda), `financial_case` (caso), `gateway` (lançamento da conta como um todo, como o repasse feito pela Wavewhite ou a compensação de valor devido; `source_id` é o id da sua conta), `gateway_receivable` ou `payout`. Use `event_type` para saber o que aconteceu." }, "source_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador do objeto de origem." }, "is_reversal": { "type": "boolean", "description": "`true` em estorno de lançamento." }, "sale": { "anyOf": [ { "type": "object", "required": [ "payment_id", "charge_id", "order_reference", "classification", "end_to_end_id", "paid_at", "gross_cents", "fee_cents", "net_cents", "reserve_cents", "payable_cents" ], "properties": { "payment_id": { "format": "uuid", "type": "string", "description": "Identificador do pagamento." }, "charge_id": { "format": "uuid", "type": "string", "description": "Cobrança da venda." }, "order_reference": { "type": "string", "description": "Seu identificador do pedido." }, "classification": { "type": "string", "description": "`primary` (venda) ou `late` (pagamento tardio)." }, "end_to_end_id": { "type": "string", "description": "Identificador fim a fim do Pix." }, "paid_at": { "format": "date-time", "type": "string", "description": "Momento do pagamento." }, "gross_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor bruto pago, em centavos." }, "fee_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Tarifa da Wavewhite, em centavos." }, "net_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Líquido da venda (bruto − tarifa), em centavos." }, "reserve_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Reserva contratual retida da venda, em centavos." }, "payable_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Quanto da venda vai para o seu saldo (líquido − reserva), em centavos." } } }, { "type": "null" } ], "description": "Venda a que o lançamento se refere (quando houver)." }, "payout": { "anyOf": [ { "type": "object", "required": [ "payout_id", "requested_cents", "fee_cents", "amount_cents" ], "properties": { "payout_id": { "format": "uuid", "type": "string", "description": "Identificador do saque." }, "requested_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor pedido, em centavos." }, "fee_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Taxa de saque, em centavos." }, "amount_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor enviado (pedido − taxa), em centavos." } } }, { "type": "null" } ], "description": "Saque pedido (pelo painel ou pela API): valor pedido, taxa de saque e valor enviado. `null` nos demais lançamentos." }, "financial_case": { "anyOf": [ { "type": "object", "required": [ "case_id", "case_type", "reason", "charge_id", "order_reference" ], "properties": { "case_id": { "format": "uuid", "type": "string", "description": "Identificador do caso." }, "case_type": { "type": "string", "description": "Tipo do caso." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Código do motivo (`duplicate_payment`, `unmatched_payment`, `late_payment_review`) ou `null`." }, "charge_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "description": "Cobrança do caso." }, "order_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Seu identificador do pedido." } } }, { "type": "null" } ], "description": "Caso (devolução, contestação MED ou bloqueio) a que o lançamento se refere." } } }, "description": "Lançamentos do período, do mais recente para o mais antigo." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor da próxima página; `null` quando não há mais." }, "as_of": { "format": "date-time", "type": "string", "description": "Momento da leitura." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "422": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/beneficiaries": { "get": { "operationId": "listBeneficiaries", "summary": "Listar contas de destino", "description": "Lista as contas bancárias da sua empresa cadastradas para receber saques, com os dados mascarados. Só uma conta com `status = \"verified\"` (titularidade conferida pela Wavewhite) pode receber saque; use o `id` dela em `beneficiary_account_id` ao pedir o saque. O cadastro de contas é feito pelo painel, em **Configurações → Dados bancários**.", "tags": [ "Saques" ], "security": [ { "apiKey": [] } ], "x-scopes": [ "beneficiaries:read" ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "title": "Beneficiary", "type": "object", "required": [ "id", "label", "version", "holder_name", "holder_document_masked", "pix_key_masked", "bank_ispb", "status", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador da conta de destino. Use em `beneficiary_account_id` ao pedir o saque." }, "label": { "type": "string", "description": "Nome dado à conta no painel." }, "version": { "type": "integer", "description": "Versão do cadastro (alterar os dados cria uma nova versão)." }, "holder_name": { "type": "string", "description": "Nome do titular. Sempre a sua própria empresa." }, "holder_document_masked": { "type": "string", "description": "CNPJ do titular, mascarado (só os últimos dígitos)." }, "pix_key_masked": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Chave Pix da conta, mascarada; `null` quando a conta não tem chave Pix cadastrada." }, "bank_ispb": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Código ISPB do banco; `null` quando a conta não tem dados bancários (agência e conta) cadastrados." }, "status": { "type": "string", "description": "Situação da conta: `pending_verification` (aguardando a Wavewhite conferir a titularidade), `verified` (pode receber saques), `rejected` ou `disabled`." }, "created_at": { "format": "date-time", "type": "string", "description": "Cadastro da conta." } } }, "description": "Itens da página." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/payouts/policy": { "get": { "operationId": "getPayoutPolicy", "summary": "Consultar as condições de saque", "description": "Mostra a taxa de saque do seu contrato, o menor valor que pode ser pedido, o limite por saque e quanto já foi pedido hoje e no mês. `manual_approval` é sempre `true` para a chave de API: cada pedido feito pela API é analisado por uma pessoa da Wavewhite antes da transferência.", "tags": [ "Saques" ], "security": [ { "apiKey": [] } ], "x-scopes": [ "payouts:read" ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "title": "PayoutPolicyInfo", "type": "object", "required": [ "payout_fee_cents", "minimum_request_cents", "execution_channel", "manual_approval", "usage", "per_payout_max_cents", "koku_per_payout_max_cents" ], "properties": { "payout_fee_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Taxa de saque do seu contrato, em centavos, descontada do valor pedido. `null` enquanto não há tarifa contratada." }, "minimum_request_cents": { "anyOf": [ { "pattern": "^-?[0-9]+$", "type": "string" }, { "type": "null" } ], "description": "Menor valor que pode ser pedido, em centavos (a taxa de saque mais um centavo)." }, "execution_channel": { "type": "string", "description": "Como o saque é pago: `manual_transfer` (transferência feita pela Wavewhite depois da aprovação) ou `partner` (envio automático pela rede de processamento, depois da aprovação)." }, "manual_approval": { "type": "boolean", "description": "`true` quando cada pedido aguarda a análise de uma pessoa da Wavewhite. Para a chave de API é sempre `true`." }, "usage": { "type": "object", "required": [ "today_cents", "month_cents" ], "properties": { "today_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor pedido hoje, em centavos." }, "month_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor pedido no mês, em centavos." } }, "description": "Quanto já foi pedido hoje e no mês (sem os saques recusados, cancelados ou falhos)." }, "per_payout_max_cents": { "pattern": "^[0-9]+$", "type": "string", "description": "Limite por saque em vigor para a sua conta, em centavos (o menor entre o teto da Wavewhite e o limite do seu contrato)." }, "koku_per_payout_max_cents": { "pattern": "^[0-9]+$", "type": "string", "description": "Teto da Wavewhite por saque, em centavos (R$ 15.000,00). Você pode fazer quantos saques quiser conforme o saldo." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/payouts/quote": { "post": { "operationId": "quotePayout", "summary": "Simular um saque", "description": "Calcula, sem reservar nada, a taxa de saque e o valor que chegaria à conta para um valor pedido, e diz se o saldo disponível cobre o pedido e se algum limite seria ultrapassado. Use antes de [Pedir um saque](/referencia/pedir-saque/) para mostrar a prévia ao seu financeiro.", "tags": [ "Saques" ], "security": [ { "apiKey": [] } ], "x-scopes": [ "payouts:read" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "type": "object", "required": [ "amount_cents" ], "properties": { "amount_cents": { "anyOf": [ { "minimum": 0, "maximum": 9007199254740991, "type": "integer" }, { "pattern": "^[0-9]{1,18}$", "type": "string" } ], "description": "Valor que você pretende pedir, em centavos (inteiro ou string decimal)." } } } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "title": "PayoutQuote", "type": "object", "required": [ "currency", "requested_cents", "fee_cents", "net_cents", "available_cents", "sufficient_funds", "limit_exceeded", "per_payout_max_cents", "manual_approval", "quoted_at" ], "properties": { "currency": { "type": "string", "enum": [ "BRL" ], "description": "Moeda (`BRL`)." }, "requested_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor pedido, em centavos." }, "fee_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Taxa de saque que seria descontada, em centavos." }, "net_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor que chegaria à conta (pedido − taxa), em centavos." }, "available_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Saldo disponível para saque no momento da simulação, em centavos." }, "sufficient_funds": { "type": "boolean", "description": "`true` quando o saldo disponível cobre o valor pedido." }, "limit_exceeded": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Limite que o pedido ultrapassaria e que faria a Wavewhite recusá-lo com `422`: `per_payout`, `daily` ou `monthly`. `null` quando cabe nos limites." }, "per_payout_max_cents": { "pattern": "^[0-9]+$", "type": "string", "description": "Limite por saque em vigor, em centavos." }, "manual_approval": { "type": "boolean", "description": "`true` quando o pedido aguardaria a análise de uma pessoa da Wavewhite (sempre, para a chave de API)." }, "quoted_at": { "format": "date-time", "type": "string", "description": "Momento da simulação." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "409": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "422": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/payouts": { "post": { "operationId": "requestPayout", "summary": "Pedir um saque", "description": "Pede a transferência de parte do saldo disponível para uma conta de destino verificada da sua empresa. O valor pedido (`amount_cents`) sai do disponível na hora e fica reservado; a taxa de saque é descontada dele e a resposta mostra `requested_cents` (pedido), `fee_cents` (taxa) e `amount_cents` (o que chega à conta). O pedido nasce com `approval_status = \"pending\"`: a Wavewhite analisa, aprova e transfere, e você acompanha por [Consultar um saque](/referencia/consultar-saque/) ou pelos eventos `payout.approved`, `payout.rejected` e `payout.paid`. Pode ser pedido a qualquer hora, inclusive em fins de semana e feriados; cada saque vai até R$ 15.000,00 (para valores maiores, faça mais de um pedido).", "tags": [ "Saques" ], "security": [ { "apiKey": [] } ], "x-scopes": [ "payouts:write" ], "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "minLength": 8, "maxLength": 200, "pattern": "^[\\x21-\\x7e]+$", "type": "string" }, "description": "Chave única por operação (8 a 200 caracteres ASCII visíveis). Repetir com o mesmo corpo devolve o mesmo resultado." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "title": "PayoutRequest", "type": "object", "required": [ "amount_cents", "beneficiary_account_id" ], "properties": { "amount_cents": { "anyOf": [ { "minimum": 0, "maximum": 9007199254740991, "type": "integer" }, { "pattern": "^[0-9]{1,18}$", "type": "string" } ], "description": "Valor pedido, em centavos (inteiro ou string decimal). Sai do saldo disponível; a taxa de saque é descontada dele. Precisa ser maior que a taxa e, no máximo, o limite por saque." }, "beneficiary_account_id": { "format": "uuid", "type": "string", "description": "Conta de destino verificada da sua empresa (veja Listar contas de destino)." } } } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "title": "Payout", "type": "object", "required": [ "id", "gateway_id", "environment", "requested_cents", "fee_cents", "amount_cents", "currency", "beneficiary_account_id", "destination", "approval_status", "approval_mode", "approval_reason", "approval_decided_at", "execution_status", "scheduled_for", "submitted_at", "confirmed_at", "end_to_end_id", "failure_reason", "awaiting_second_approval", "waiting_reason", "next_attempt_at", "execution_channel", "transfer_reference", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador do saque." }, "gateway_id": { "format": "uuid", "type": "string", "description": "Identificador da sua conta na Wavewhite." }, "environment": { "anyOf": [ { "type": "string", "enum": [ "sandbox" ] }, { "type": "string", "enum": [ "production" ] } ], "description": "Ambiente: `production` (`sandbox` está reservado para o ambiente de testes, em preparação)." }, "requested_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor pedido, em centavos. É o que saiu do saldo disponível." }, "fee_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Taxa de saque descontada do valor pedido, em centavos." }, "amount_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor enviado à conta de destino (pedido − taxa), em centavos." }, "currency": { "type": "string", "enum": [ "BRL" ], "description": "Moeda (`BRL`)." }, "beneficiary_account_id": { "format": "uuid", "type": "string", "description": "Conta de destino do saque." }, "destination": { "type": "object", "required": [ "holder_name", "holder_document_masked", "pix_key_masked", "bank_ispb" ], "properties": { "holder_name": { "type": "string", "description": "Nome do titular da conta de destino." }, "holder_document_masked": { "type": "string", "description": "CNPJ do titular, mascarado." }, "pix_key_masked": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Chave Pix de destino, mascarada; `null` quando a conta não tem chave Pix cadastrada." }, "bank_ispb": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Código ISPB do banco de destino; `null` quando a conta não tem dados bancários cadastrados." } }, "description": "Dados da conta de destino no momento do pedido (mudar o cadastro depois não altera o saque)." }, "approval_status": { "type": "string", "description": "Análise da Wavewhite: `pending` (aguardando), `approved` ou `rejected`. Um saque que você cancelou antes da análise continua `pending` aqui: use `execution_status = \"cancelled\"` para saber que ele foi encerrado." }, "approval_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Como foi decidido: `manual` (uma pessoa da Wavewhite) ou `automatic`. `null` enquanto pendente." }, "approval_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Observação da Wavewhite na decisão (por exemplo, o motivo da recusa). `null` enquanto pendente." }, "approval_decided_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Momento da decisão. `null` enquanto pendente." }, "execution_status": { "type": "string", "description": "Situação da transferência: `reserved` (valor reservado, aguardando a análise), `queued` (aprovado, aguardando a transferência da Wavewhite), `submitted`, `processing`, `unknown`, `paid`, `failed` ou `cancelled` (recusado ou cancelado: o valor voltou ao disponível)." }, "scheduled_for": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Quando o envio está agendado, se houver agendamento. `null` nos saques pagos por transferência da Wavewhite." }, "submitted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Momento em que o envio automático foi encaminhado, quando houver. `null` nos saques pagos por transferência da Wavewhite." }, "confirmed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Momento em que o saque foi pago." }, "end_to_end_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador fim a fim do Pix, quando o envio é automático. Nos saques pagos por transferência da Wavewhite, use `transfer_reference`." }, "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Por que o saque foi encerrado sem pagamento: o motivo que você informou ao cancelar (ou um texto padrão), o motivo da recusa da Wavewhite ou, no envio automático, um texto fixo da Wavewhite. `null` enquanto o saque segue em andamento ou foi pago." }, "awaiting_second_approval": { "type": "boolean", "description": "`true` quando o valor exige uma segunda aprovação na Wavewhite e a primeira já foi dada." }, "waiting_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Saque aprovado e ainda não pago: por que está esperando. `awaiting_manual_transfer` (a Wavewhite vai fazer a transferência), `in_review` (transferência em análise), `outside_window`, `daily_limit_reached` ou `monthly_limit_reached`. `null` nos demais estados." }, "next_attempt_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Quando o saque em espera será reavaliado, quando houver previsão." }, "execution_channel": { "type": "string", "description": "Como o saque é pago: `manual_transfer` (transferência feita pela Wavewhite) ou `partner` (envio automático)." }, "transfer_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Saque pago por transferência da Wavewhite: identificador da transferência (por exemplo, o fim a fim do Pix). A mesma referência aparece no extrato em `payout.paid`." }, "created_at": { "format": "date-time", "type": "string", "description": "Momento do pedido." } } } } } }, "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "title": "Payout", "type": "object", "required": [ "id", "gateway_id", "environment", "requested_cents", "fee_cents", "amount_cents", "currency", "beneficiary_account_id", "destination", "approval_status", "approval_mode", "approval_reason", "approval_decided_at", "execution_status", "scheduled_for", "submitted_at", "confirmed_at", "end_to_end_id", "failure_reason", "awaiting_second_approval", "waiting_reason", "next_attempt_at", "execution_channel", "transfer_reference", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador do saque." }, "gateway_id": { "format": "uuid", "type": "string", "description": "Identificador da sua conta na Wavewhite." }, "environment": { "anyOf": [ { "type": "string", "enum": [ "sandbox" ] }, { "type": "string", "enum": [ "production" ] } ], "description": "Ambiente: `production` (`sandbox` está reservado para o ambiente de testes, em preparação)." }, "requested_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor pedido, em centavos. É o que saiu do saldo disponível." }, "fee_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Taxa de saque descontada do valor pedido, em centavos." }, "amount_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor enviado à conta de destino (pedido − taxa), em centavos." }, "currency": { "type": "string", "enum": [ "BRL" ], "description": "Moeda (`BRL`)." }, "beneficiary_account_id": { "format": "uuid", "type": "string", "description": "Conta de destino do saque." }, "destination": { "type": "object", "required": [ "holder_name", "holder_document_masked", "pix_key_masked", "bank_ispb" ], "properties": { "holder_name": { "type": "string", "description": "Nome do titular da conta de destino." }, "holder_document_masked": { "type": "string", "description": "CNPJ do titular, mascarado." }, "pix_key_masked": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Chave Pix de destino, mascarada; `null` quando a conta não tem chave Pix cadastrada." }, "bank_ispb": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Código ISPB do banco de destino; `null` quando a conta não tem dados bancários cadastrados." } }, "description": "Dados da conta de destino no momento do pedido (mudar o cadastro depois não altera o saque)." }, "approval_status": { "type": "string", "description": "Análise da Wavewhite: `pending` (aguardando), `approved` ou `rejected`. Um saque que você cancelou antes da análise continua `pending` aqui: use `execution_status = \"cancelled\"` para saber que ele foi encerrado." }, "approval_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Como foi decidido: `manual` (uma pessoa da Wavewhite) ou `automatic`. `null` enquanto pendente." }, "approval_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Observação da Wavewhite na decisão (por exemplo, o motivo da recusa). `null` enquanto pendente." }, "approval_decided_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Momento da decisão. `null` enquanto pendente." }, "execution_status": { "type": "string", "description": "Situação da transferência: `reserved` (valor reservado, aguardando a análise), `queued` (aprovado, aguardando a transferência da Wavewhite), `submitted`, `processing`, `unknown`, `paid`, `failed` ou `cancelled` (recusado ou cancelado: o valor voltou ao disponível)." }, "scheduled_for": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Quando o envio está agendado, se houver agendamento. `null` nos saques pagos por transferência da Wavewhite." }, "submitted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Momento em que o envio automático foi encaminhado, quando houver. `null` nos saques pagos por transferência da Wavewhite." }, "confirmed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Momento em que o saque foi pago." }, "end_to_end_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador fim a fim do Pix, quando o envio é automático. Nos saques pagos por transferência da Wavewhite, use `transfer_reference`." }, "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Por que o saque foi encerrado sem pagamento: o motivo que você informou ao cancelar (ou um texto padrão), o motivo da recusa da Wavewhite ou, no envio automático, um texto fixo da Wavewhite. `null` enquanto o saque segue em andamento ou foi pago." }, "awaiting_second_approval": { "type": "boolean", "description": "`true` quando o valor exige uma segunda aprovação na Wavewhite e a primeira já foi dada." }, "waiting_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Saque aprovado e ainda não pago: por que está esperando. `awaiting_manual_transfer` (a Wavewhite vai fazer a transferência), `in_review` (transferência em análise), `outside_window`, `daily_limit_reached` ou `monthly_limit_reached`. `null` nos demais estados." }, "next_attempt_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Quando o saque em espera será reavaliado, quando houver previsão." }, "execution_channel": { "type": "string", "description": "Como o saque é pago: `manual_transfer` (transferência feita pela Wavewhite) ou `partner` (envio automático)." }, "transfer_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Saque pago por transferência da Wavewhite: identificador da transferência (por exemplo, o fim a fim do Pix). A mesma referência aparece no extrato em `payout.paid`." }, "created_at": { "format": "date-time", "type": "string", "description": "Momento do pedido." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "404": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "409": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "422": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } }, "get": { "operationId": "listPayouts", "summary": "Listar saques", "description": "Lista os saques pedidos pela sua empresa (pelo painel ou pela API), dos mais recentes para os mais antigos, com paginação por cursor. Os repasses que a Wavewhite fez sem pedido ficam em [Listar repasses feitos pela Wavewhite](/referencia/listar-repasses/).", "tags": [ "Saques" ], "security": [ { "apiKey": [] } ], "x-scopes": [ "payouts:read" ], "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 2000, "type": "string" }, "description": "Cursor devolvido em `next_cursor` da página anterior." }, { "in": "query", "name": "limit", "required": false, "schema": { "minimum": 1, "maximum": 200, "type": "integer" }, "description": "Itens por página." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "title": "Payout", "type": "object", "required": [ "id", "gateway_id", "environment", "requested_cents", "fee_cents", "amount_cents", "currency", "beneficiary_account_id", "destination", "approval_status", "approval_mode", "approval_reason", "approval_decided_at", "execution_status", "scheduled_for", "submitted_at", "confirmed_at", "end_to_end_id", "failure_reason", "awaiting_second_approval", "waiting_reason", "next_attempt_at", "execution_channel", "transfer_reference", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador do saque." }, "gateway_id": { "format": "uuid", "type": "string", "description": "Identificador da sua conta na Wavewhite." }, "environment": { "anyOf": [ { "type": "string", "enum": [ "sandbox" ] }, { "type": "string", "enum": [ "production" ] } ], "description": "Ambiente: `production` (`sandbox` está reservado para o ambiente de testes, em preparação)." }, "requested_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor pedido, em centavos. É o que saiu do saldo disponível." }, "fee_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Taxa de saque descontada do valor pedido, em centavos." }, "amount_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor enviado à conta de destino (pedido − taxa), em centavos." }, "currency": { "type": "string", "enum": [ "BRL" ], "description": "Moeda (`BRL`)." }, "beneficiary_account_id": { "format": "uuid", "type": "string", "description": "Conta de destino do saque." }, "destination": { "type": "object", "required": [ "holder_name", "holder_document_masked", "pix_key_masked", "bank_ispb" ], "properties": { "holder_name": { "type": "string", "description": "Nome do titular da conta de destino." }, "holder_document_masked": { "type": "string", "description": "CNPJ do titular, mascarado." }, "pix_key_masked": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Chave Pix de destino, mascarada; `null` quando a conta não tem chave Pix cadastrada." }, "bank_ispb": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Código ISPB do banco de destino; `null` quando a conta não tem dados bancários cadastrados." } }, "description": "Dados da conta de destino no momento do pedido (mudar o cadastro depois não altera o saque)." }, "approval_status": { "type": "string", "description": "Análise da Wavewhite: `pending` (aguardando), `approved` ou `rejected`. Um saque que você cancelou antes da análise continua `pending` aqui: use `execution_status = \"cancelled\"` para saber que ele foi encerrado." }, "approval_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Como foi decidido: `manual` (uma pessoa da Wavewhite) ou `automatic`. `null` enquanto pendente." }, "approval_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Observação da Wavewhite na decisão (por exemplo, o motivo da recusa). `null` enquanto pendente." }, "approval_decided_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Momento da decisão. `null` enquanto pendente." }, "execution_status": { "type": "string", "description": "Situação da transferência: `reserved` (valor reservado, aguardando a análise), `queued` (aprovado, aguardando a transferência da Wavewhite), `submitted`, `processing`, `unknown`, `paid`, `failed` ou `cancelled` (recusado ou cancelado: o valor voltou ao disponível)." }, "scheduled_for": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Quando o envio está agendado, se houver agendamento. `null` nos saques pagos por transferência da Wavewhite." }, "submitted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Momento em que o envio automático foi encaminhado, quando houver. `null` nos saques pagos por transferência da Wavewhite." }, "confirmed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Momento em que o saque foi pago." }, "end_to_end_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador fim a fim do Pix, quando o envio é automático. Nos saques pagos por transferência da Wavewhite, use `transfer_reference`." }, "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Por que o saque foi encerrado sem pagamento: o motivo que você informou ao cancelar (ou um texto padrão), o motivo da recusa da Wavewhite ou, no envio automático, um texto fixo da Wavewhite. `null` enquanto o saque segue em andamento ou foi pago." }, "awaiting_second_approval": { "type": "boolean", "description": "`true` quando o valor exige uma segunda aprovação na Wavewhite e a primeira já foi dada." }, "waiting_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Saque aprovado e ainda não pago: por que está esperando. `awaiting_manual_transfer` (a Wavewhite vai fazer a transferência), `in_review` (transferência em análise), `outside_window`, `daily_limit_reached` ou `monthly_limit_reached`. `null` nos demais estados." }, "next_attempt_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Quando o saque em espera será reavaliado, quando houver previsão." }, "execution_channel": { "type": "string", "description": "Como o saque é pago: `manual_transfer` (transferência feita pela Wavewhite) ou `partner` (envio automático)." }, "transfer_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Saque pago por transferência da Wavewhite: identificador da transferência (por exemplo, o fim a fim do Pix). A mesma referência aparece no extrato em `payout.paid`." }, "created_at": { "format": "date-time", "type": "string", "description": "Momento do pedido." } } }, "description": "Itens da página." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor da próxima página; `null` quando não há mais itens." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "422": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/payouts/{id}": { "get": { "operationId": "getPayout", "summary": "Consultar um saque", "description": "Devolve o saque com a situação atual da análise (`approval_status`) e da transferência (`execution_status`). Quando pago, `transfer_reference` traz o identificador da transferência feita pela Wavewhite.", "tags": [ "Saques" ], "security": [ { "apiKey": [] } ], "x-scopes": [ "payouts:read" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "Identificador do saque." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "title": "Payout", "type": "object", "required": [ "id", "gateway_id", "environment", "requested_cents", "fee_cents", "amount_cents", "currency", "beneficiary_account_id", "destination", "approval_status", "approval_mode", "approval_reason", "approval_decided_at", "execution_status", "scheduled_for", "submitted_at", "confirmed_at", "end_to_end_id", "failure_reason", "awaiting_second_approval", "waiting_reason", "next_attempt_at", "execution_channel", "transfer_reference", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador do saque." }, "gateway_id": { "format": "uuid", "type": "string", "description": "Identificador da sua conta na Wavewhite." }, "environment": { "anyOf": [ { "type": "string", "enum": [ "sandbox" ] }, { "type": "string", "enum": [ "production" ] } ], "description": "Ambiente: `production` (`sandbox` está reservado para o ambiente de testes, em preparação)." }, "requested_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor pedido, em centavos. É o que saiu do saldo disponível." }, "fee_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Taxa de saque descontada do valor pedido, em centavos." }, "amount_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor enviado à conta de destino (pedido − taxa), em centavos." }, "currency": { "type": "string", "enum": [ "BRL" ], "description": "Moeda (`BRL`)." }, "beneficiary_account_id": { "format": "uuid", "type": "string", "description": "Conta de destino do saque." }, "destination": { "type": "object", "required": [ "holder_name", "holder_document_masked", "pix_key_masked", "bank_ispb" ], "properties": { "holder_name": { "type": "string", "description": "Nome do titular da conta de destino." }, "holder_document_masked": { "type": "string", "description": "CNPJ do titular, mascarado." }, "pix_key_masked": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Chave Pix de destino, mascarada; `null` quando a conta não tem chave Pix cadastrada." }, "bank_ispb": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Código ISPB do banco de destino; `null` quando a conta não tem dados bancários cadastrados." } }, "description": "Dados da conta de destino no momento do pedido (mudar o cadastro depois não altera o saque)." }, "approval_status": { "type": "string", "description": "Análise da Wavewhite: `pending` (aguardando), `approved` ou `rejected`. Um saque que você cancelou antes da análise continua `pending` aqui: use `execution_status = \"cancelled\"` para saber que ele foi encerrado." }, "approval_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Como foi decidido: `manual` (uma pessoa da Wavewhite) ou `automatic`. `null` enquanto pendente." }, "approval_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Observação da Wavewhite na decisão (por exemplo, o motivo da recusa). `null` enquanto pendente." }, "approval_decided_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Momento da decisão. `null` enquanto pendente." }, "execution_status": { "type": "string", "description": "Situação da transferência: `reserved` (valor reservado, aguardando a análise), `queued` (aprovado, aguardando a transferência da Wavewhite), `submitted`, `processing`, `unknown`, `paid`, `failed` ou `cancelled` (recusado ou cancelado: o valor voltou ao disponível)." }, "scheduled_for": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Quando o envio está agendado, se houver agendamento. `null` nos saques pagos por transferência da Wavewhite." }, "submitted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Momento em que o envio automático foi encaminhado, quando houver. `null` nos saques pagos por transferência da Wavewhite." }, "confirmed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Momento em que o saque foi pago." }, "end_to_end_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador fim a fim do Pix, quando o envio é automático. Nos saques pagos por transferência da Wavewhite, use `transfer_reference`." }, "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Por que o saque foi encerrado sem pagamento: o motivo que você informou ao cancelar (ou um texto padrão), o motivo da recusa da Wavewhite ou, no envio automático, um texto fixo da Wavewhite. `null` enquanto o saque segue em andamento ou foi pago." }, "awaiting_second_approval": { "type": "boolean", "description": "`true` quando o valor exige uma segunda aprovação na Wavewhite e a primeira já foi dada." }, "waiting_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Saque aprovado e ainda não pago: por que está esperando. `awaiting_manual_transfer` (a Wavewhite vai fazer a transferência), `in_review` (transferência em análise), `outside_window`, `daily_limit_reached` ou `monthly_limit_reached`. `null` nos demais estados." }, "next_attempt_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Quando o saque em espera será reavaliado, quando houver previsão." }, "execution_channel": { "type": "string", "description": "Como o saque é pago: `manual_transfer` (transferência feita pela Wavewhite) ou `partner` (envio automático)." }, "transfer_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Saque pago por transferência da Wavewhite: identificador da transferência (por exemplo, o fim a fim do Pix). A mesma referência aparece no extrato em `payout.paid`." }, "created_at": { "format": "date-time", "type": "string", "description": "Momento do pedido." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "404": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/payouts/{id}/cancel": { "post": { "operationId": "cancelPayout", "summary": "Cancelar um saque", "description": "Cancela um saque que ainda aguarda a análise da Wavewhite: o valor pedido volta ao saldo disponível na hora (lançamento `payout.released`) e o evento `payout.failed` é enviado com o motivo que você informou. Depois de aprovado, o saque está com a Wavewhite para transferência e não pode mais ser cancelado.", "tags": [ "Saques" ], "security": [ { "apiKey": [] } ], "x-scopes": [ "payouts:write" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "Identificador do saque que aguarda análise." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "additionalProperties": false, "type": "object", "properties": { "reason": { "maxLength": 500, "type": "string", "description": "Motivo do cancelamento, para o seu controle (até 500 caracteres). Opcional." } } }, { "type": "null" } ] } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "title": "Payout", "type": "object", "required": [ "id", "gateway_id", "environment", "requested_cents", "fee_cents", "amount_cents", "currency", "beneficiary_account_id", "destination", "approval_status", "approval_mode", "approval_reason", "approval_decided_at", "execution_status", "scheduled_for", "submitted_at", "confirmed_at", "end_to_end_id", "failure_reason", "awaiting_second_approval", "waiting_reason", "next_attempt_at", "execution_channel", "transfer_reference", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador do saque." }, "gateway_id": { "format": "uuid", "type": "string", "description": "Identificador da sua conta na Wavewhite." }, "environment": { "anyOf": [ { "type": "string", "enum": [ "sandbox" ] }, { "type": "string", "enum": [ "production" ] } ], "description": "Ambiente: `production` (`sandbox` está reservado para o ambiente de testes, em preparação)." }, "requested_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor pedido, em centavos. É o que saiu do saldo disponível." }, "fee_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Taxa de saque descontada do valor pedido, em centavos." }, "amount_cents": { "pattern": "^-?[0-9]+$", "type": "string", "description": "Valor enviado à conta de destino (pedido − taxa), em centavos." }, "currency": { "type": "string", "enum": [ "BRL" ], "description": "Moeda (`BRL`)." }, "beneficiary_account_id": { "format": "uuid", "type": "string", "description": "Conta de destino do saque." }, "destination": { "type": "object", "required": [ "holder_name", "holder_document_masked", "pix_key_masked", "bank_ispb" ], "properties": { "holder_name": { "type": "string", "description": "Nome do titular da conta de destino." }, "holder_document_masked": { "type": "string", "description": "CNPJ do titular, mascarado." }, "pix_key_masked": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Chave Pix de destino, mascarada; `null` quando a conta não tem chave Pix cadastrada." }, "bank_ispb": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Código ISPB do banco de destino; `null` quando a conta não tem dados bancários cadastrados." } }, "description": "Dados da conta de destino no momento do pedido (mudar o cadastro depois não altera o saque)." }, "approval_status": { "type": "string", "description": "Análise da Wavewhite: `pending` (aguardando), `approved` ou `rejected`. Um saque que você cancelou antes da análise continua `pending` aqui: use `execution_status = \"cancelled\"` para saber que ele foi encerrado." }, "approval_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Como foi decidido: `manual` (uma pessoa da Wavewhite) ou `automatic`. `null` enquanto pendente." }, "approval_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Observação da Wavewhite na decisão (por exemplo, o motivo da recusa). `null` enquanto pendente." }, "approval_decided_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Momento da decisão. `null` enquanto pendente." }, "execution_status": { "type": "string", "description": "Situação da transferência: `reserved` (valor reservado, aguardando a análise), `queued` (aprovado, aguardando a transferência da Wavewhite), `submitted`, `processing`, `unknown`, `paid`, `failed` ou `cancelled` (recusado ou cancelado: o valor voltou ao disponível)." }, "scheduled_for": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Quando o envio está agendado, se houver agendamento. `null` nos saques pagos por transferência da Wavewhite." }, "submitted_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Momento em que o envio automático foi encaminhado, quando houver. `null` nos saques pagos por transferência da Wavewhite." }, "confirmed_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Momento em que o saque foi pago." }, "end_to_end_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador fim a fim do Pix, quando o envio é automático. Nos saques pagos por transferência da Wavewhite, use `transfer_reference`." }, "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Por que o saque foi encerrado sem pagamento: o motivo que você informou ao cancelar (ou um texto padrão), o motivo da recusa da Wavewhite ou, no envio automático, um texto fixo da Wavewhite. `null` enquanto o saque segue em andamento ou foi pago." }, "awaiting_second_approval": { "type": "boolean", "description": "`true` quando o valor exige uma segunda aprovação na Wavewhite e a primeira já foi dada." }, "waiting_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Saque aprovado e ainda não pago: por que está esperando. `awaiting_manual_transfer` (a Wavewhite vai fazer a transferência), `in_review` (transferência em análise), `outside_window`, `daily_limit_reached` ou `monthly_limit_reached`. `null` nos demais estados." }, "next_attempt_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Quando o saque em espera será reavaliado, quando houver previsão." }, "execution_channel": { "type": "string", "description": "Como o saque é pago: `manual_transfer` (transferência feita pela Wavewhite) ou `partner` (envio automático)." }, "transfer_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Saque pago por transferência da Wavewhite: identificador da transferência (por exemplo, o fim a fim do Pix). A mesma referência aparece no extrato em `payout.paid`." }, "created_at": { "format": "date-time", "type": "string", "description": "Momento do pedido." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "404": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "409": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/payouts/by-koku": { "get": { "operationId": "listPayoutsByKoku", "summary": "Listar repasses feitos pela Wavewhite", "description": "Lista os repasses que a Wavewhite fez para a sua conta bancária sem pedido de saque, conforme o contrato, com a referência da transferência. Cada repasse já foi descontado do saldo disponível. Os saques que você pede (pelo painel ou pela API) aparecem em [Listar saques](/referencia/listar-saques/), no extrato (`payout.reserved` e `payout.paid`) e nos eventos `payout.*`.", "tags": [ "Repasses" ], "security": [ { "apiKey": [] } ], "x-scopes": [ "payouts:read" ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "amount_cents", "external_reference", "paid_at" ], "properties": { "id": { "type": "string", "description": "Identificador do repasse." }, "amount_cents": { "type": "string", "description": "Valor repassado, em centavos." }, "external_reference": { "type": "string", "description": "Referência da transferência (por exemplo, o identificador fim a fim do Pix)." }, "paid_at": { "type": "string", "description": "Data da transferência." } } }, "description": "Repasses feitos pela Wavewhite, do mais recente para o mais antigo." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/webhooks/event-types": { "get": { "operationId": "listEventTypes", "summary": "Listar tipos de evento", "description": "Devolve a versão do formato dos eventos, os tipos disponíveis e como a assinatura é calculada.", "tags": [ "Webhooks" ], "security": [ { "apiKey": [] } ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "version", "event_types", "signature" ], "properties": { "version": { "type": "string", "description": "Versão do formato dos eventos." }, "event_types": { "type": "array", "items": { "type": "string" }, "description": "Tipos de evento disponíveis." }, "signature": { "type": "object", "required": [ "header", "scheme", "extra_headers" ], "properties": { "header": { "type": "string", "description": "Cabeçalho com a assinatura." }, "scheme": { "type": "string", "description": "Formato e cálculo da assinatura." }, "extra_headers": { "type": "array", "items": { "type": "string" }, "description": "Outros cabeçalhos enviados em cada entrega." } }, "description": "Como a assinatura é enviada." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/webhooks/endpoints": { "post": { "operationId": "registerWebhookEndpoint", "summary": "Cadastrar endpoint de webhook", "description": "Cadastra a URL que vai receber os eventos. O segredo de assinatura (`signing_secret`) é devolvido uma única vez: guarde-o em local seguro.", "tags": [ "Webhooks" ], "security": [ { "apiKey": [] } ], "x-scopes": [ "webhooks:write" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "title": "WebhookEndpointRequest", "type": "object", "required": [ "url" ], "properties": { "url": { "minLength": 10, "maxLength": 2000, "type": "string", "description": "URL HTTPS pública que vai receber os eventos (até 2000 caracteres). Redes privadas e endereços locais são recusados." }, "event_types": { "maxItems": 30, "type": "array", "items": { "maxLength": 60, "type": "string" }, "description": "Tipos de evento a receber. Vazio ou omitido = todos." } } } } } }, "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "signing_secret" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador do endpoint." }, "signing_secret": { "type": "string", "description": "Segredo de assinatura. Exibido uma única vez: guarde-o em local seguro." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "409": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "422": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } }, "get": { "operationId": "listWebhookEndpoints", "summary": "Listar endpoints de webhook", "description": "Lista os endpoints cadastrados, com a situação de cada um e as falhas seguidas mais recentes.", "tags": [ "Webhooks" ], "security": [ { "apiKey": [] } ], "x-scopes": [ "webhooks:read" ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "title": "WebhookEndpoint", "type": "object", "required": [ "id", "url", "event_types", "status", "secret_last4", "created_at", "consecutive_failures", "paused_until" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador do endpoint." }, "url": { "type": "string", "description": "URL cadastrada." }, "event_types": { "type": "array", "items": { "type": "string" }, "description": "Tipos de evento assinados (vazio = todos)." }, "status": { "type": "string", "description": "Situação: `active` ou `disabled`." }, "secret_last4": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Últimos 4 caracteres do segredo, para conferência." }, "created_at": { "format": "date-time", "type": "string", "description": "Cadastro do endpoint." }, "consecutive_failures": { "type": "integer", "description": "Falhas técnicas seguidas nas últimas entregas (0 = saudável)." }, "paused_until": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Entregas pausadas até este horário depois de falhas seguidas (`null` = sem pausa)." } } }, "description": "Itens da página." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/webhooks/endpoints/{id}": { "delete": { "operationId": "disableWebhookEndpoint", "summary": "Desabilitar endpoint de webhook", "description": "Desabilita um endpoint: ele deixa de receber eventos. Os eventos continuam disponíveis em Listar eventos.", "tags": [ "Webhooks" ], "security": [ { "apiKey": [] } ], "x-scopes": [ "webhooks:write" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" }, "description": "Identificador do endpoint." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean", "enum": [ true ], "description": "Sempre `true` quando a operação foi aplicada." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "404": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/webhooks/events": { "get": { "operationId": "listEvents", "summary": "Listar eventos", "description": "Lista os eventos emitidos para a sua conta, com o mesmo conteúdo enviado por webhook. A consulta não depende da entrega: use-a para conferir o que pode ter se perdido.", "tags": [ "Webhooks" ], "security": [ { "apiKey": [] } ], "x-scopes": [ "webhooks:read" ], "parameters": [ { "in": "query", "name": "type", "required": false, "schema": { "maxLength": 60, "type": "string" }, "description": "Filtra pelo tipo de evento (ex.: `charge.paid`)." }, { "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 2000, "type": "string" }, "description": "Cursor devolvido em `next_cursor` da página anterior." }, { "in": "query", "name": "limit", "required": false, "schema": { "minimum": 1, "maximum": 200, "type": "integer" }, "description": "Itens por página." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "title": "Event", "type": "object", "required": [ "id", "type", "version", "environment", "object_type", "object_id", "created_at", "data" ], "properties": { "id": { "type": "string", "description": "Identificador do evento (`evt_...`). É o mesmo em todas as tentativas de entrega: use-o para não processar duas vezes." }, "type": { "type": "string", "description": "Tipo do evento (ex.: `charge.paid`)." }, "version": { "type": "string", "description": "Versão do formato do evento (`v1`)." }, "environment": { "anyOf": [ { "type": "string", "enum": [ "sandbox" ] }, { "type": "string", "enum": [ "production" ] } ], "description": "Ambiente: `production` (`sandbox` está reservado para o ambiente de testes, em preparação)." }, "object_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tipo do objeto do evento (ex.: `charge`)." }, "object_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Identificador do objeto." }, "created_at": { "format": "date-time", "type": "string", "description": "Momento do fato." }, "data": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Dados do evento. O formato de cada tipo está em Eventos e payloads." } } }, "description": "Itens da página." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor da próxima página; `null` quando não há mais itens." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "422": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/webhooks/deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "Listar entregas", "description": "Mostra o resultado técnico de cada tentativa de entrega aos seus endpoints. Uma falha de entrega nunca altera cobrança, saldo ou extrato.", "tags": [ "Webhooks" ], "security": [ { "apiKey": [] } ], "x-scopes": [ "webhooks:read" ], "parameters": [ { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "type": "string", "enum": [ "pending" ] }, { "type": "string", "enum": [ "delivered" ] }, { "type": "string", "enum": [ "failed" ] }, { "type": "string", "enum": [ "dead_letter" ] } ] }, "description": "Filtra pelo resultado técnico da entrega." }, { "in": "query", "name": "endpoint_id", "required": false, "schema": { "format": "uuid", "type": "string" }, "description": "Filtra por endpoint." }, { "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 2000, "type": "string" }, "description": "Cursor devolvido em `next_cursor` da página anterior." }, { "in": "query", "name": "limit", "required": false, "schema": { "minimum": 1, "maximum": 200, "type": "integer" }, "description": "Itens por página." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "next_cursor" ], "properties": { "items": { "type": "array", "items": { "title": "WebhookDelivery", "type": "object", "required": [ "id", "endpoint_id", "endpoint_url", "event_id", "event_type", "status", "attempts", "last_response_status", "last_response_ms", "last_error", "last_attempt_at", "next_attempt_at", "delivered_at", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador da entrega." }, "endpoint_id": { "format": "uuid", "type": "string", "description": "Endpoint de destino." }, "endpoint_url": { "type": "string", "description": "URL do endpoint." }, "event_id": { "type": "string", "description": "Evento entregue." }, "event_type": { "type": "string", "description": "Tipo do evento." }, "status": { "type": "string", "description": "Resultado técnico: `pending`, `delivered`, `failed` ou `dead_letter` (tentativas esgotadas)." }, "attempts": { "type": "integer", "description": "Tentativas feitas." }, "last_response_status": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Status HTTP da última resposta do seu endpoint." }, "last_response_ms": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Tempo da última resposta, em milissegundos." }, "last_error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Último erro técnico (ex.: tempo esgotado)." }, "last_attempt_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Última tentativa." }, "next_attempt_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Próxima tentativa agendada." }, "delivered_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Entrega confirmada (resposta 2xx)." }, "created_at": { "format": "date-time", "type": "string", "description": "Criação da entrega." } } }, "description": "Itens da página." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor da próxima página; `null` quando não há mais itens." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "403": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "422": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } }, "/v1/api-keys/current": { "get": { "operationId": "currentApiKey", "summary": "Dados da chave atual", "description": "Devolve os dados da chave usada na requisição (nunca o segredo). Útil para conferir ambiente e escopos na subida da integração.", "tags": [ "Chave de API" ], "security": [ { "apiKey": [] } ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "name", "prefix", "gateway_id", "environment", "scopes", "expires_at", "created_at" ], "properties": { "id": { "format": "uuid", "type": "string", "description": "Identificador da chave." }, "name": { "type": "string", "description": "Nome dado à chave no painel." }, "prefix": { "type": "string", "description": "Prefixo público da chave (o segredo nunca é devolvido)." }, "gateway_id": { "format": "uuid", "type": "string", "description": "Identificador da sua conta na Wavewhite." }, "environment": { "anyOf": [ { "type": "string", "enum": [ "sandbox" ] }, { "type": "string", "enum": [ "production" ] } ], "description": "Ambiente da chave: `production` (`sandbox` está reservado para o ambiente de testes, em preparação)." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Escopos concedidos." }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Expiração da chave (`null` = sem expiração)." }, "created_at": { "format": "date-time", "type": "string", "description": "Criação da chave." } } } } } }, "401": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "429": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } }, "500": { "description": "Erro (ver `error.code`)", "content": { "application/json": { "schema": { "title": "Error", "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "correlation_id" ], "properties": { "code": { "type": "string", "description": "Código estável do erro (veja Erros)." }, "message": { "type": "string", "description": "Mensagem em português para exibição. Não use para decidir no código." }, "details": { "additionalProperties": true, "type": "object", "properties": {}, "description": "Detalhes. `reason` identifica a regra; `fields` lista os campos inválidos." }, "correlation_id": { "type": "string", "description": "Identificador da requisição. Informe à Wavewhite ao pedir ajuda." } }, "description": "Objeto de erro." } } } } } } } } } } }