{ "openapi": "3.1.0", "info": { "title": "WeetPay API", "version": "1.0.0", "description": "API pública da WeetPay para receber pagamentos PIX (cash-in), enviar PIX (cash-out), consultar transações e saldo. Valores sempre em **reais** (`10.50` = R$ 10,50). Autentique com o client ID e o client secret gerados no painel, em **Desenvolvedores**.", "contact": { "name": "WeetPay", "url": "https://docs.weetpay.com" } }, "servers": [ { "url": "https://api.weetpay.com", "description": "Produção" } ], "security": [ { "clientId": [], "clientSecret": [] }, { "basicAuth": [] } ], "tags": [ { "name": "Cash-in", "description": "Cobranças PIX (QR Code dinâmico)" }, { "name": "Cash-out", "description": "Saques e pagamentos PIX" }, { "name": "Transações", "description": "Consulta de cobranças e saques" }, { "name": "Conta", "description": "Saldo da carteira" } ], "paths": { "/api/v1/gateway/request-qrcode": { "post": { "operationId": "requestQrcode", "tags": [ "Cash-in" ], "summary": "Gerar cobrança PIX", "description": "Gera um PIX copia e cola (QR Code dinâmico) para o seu cliente pagar. A cobrança nasce `WAITING_FOR_APPROVAL` e passa a `PAID_OUT` quando é paga — nesse momento o valor entra no seu saldo (menos a tarifa) e a WeetPay faz um `POST` no `callbackUrl`. O QR expira no prazo definido pela plataforma (padrão 1 hora).\n\n`requestNumber` é o identificador do pedido no seu sistema e **não pode se repetir** na mesma conta (repetir devolve `400 requestNumber já utilizado`). Parâmetros UTM na query string (`utm_source`, `utm_campaign`, `utm_medium`, `utm_content`, `utm_term`) ficam salvos na cobrança.", "parameters": [ { "name": "utm_source", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 300 }, "description": "Rastreamento de campanha (opcional), salvo na cobrança" }, { "name": "utm_campaign", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 300 }, "description": "Rastreamento de campanha (opcional), salvo na cobrança" }, { "name": "utm_medium", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 300 }, "description": "Rastreamento de campanha (opcional), salvo na cobrança" }, { "name": "utm_content", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 300 }, "description": "Rastreamento de campanha (opcional), salvo na cobrança" }, { "name": "utm_term", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 300 }, "description": "Rastreamento de campanha (opcional), salvo na cobrança" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestQrcode" }, "example": { "requestNumber": "pedido-12345", "amount": 49.9, "callbackUrl": "https://sualoja.com.br/webhooks/weetpay", "client": { "name": "Maria da Silva", "document": "12345678909", "email": "maria@email.com", "phoneNumber": "11999998888" }, "products": [ { "description": "Camiseta básica", "quantity": 1, "value": 49.9 } ] } } } }, "responses": { "200": { "description": "Cobrança criada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestQrcodeResponse" }, "example": { "idTransaction": "cmh1x2y3z0001ab12cd34ef56", "paymentCode": "00020101021226850014br.gov.bcb.pix2563qrcode.exemplo.com.br/pix/v2/cobv/9d36b84f...5204000053039865406149.905802BR5913WEETPAY6009SAO PAULO62070503***6304ABCD", "paymentCodeBase64": "iVBORw0KGgoAAAANSUhEUgAA...", "response": "OK", "status": "WAITING_FOR_APPROVAL" } } } }, "400": { "description": "Erro", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "response": "ERROR", "message": "requestNumber já utilizado" } } } }, "401": { "description": "Erro", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "response": "ERROR", "message": "Credenciais inválidas" } } } }, "403": { "description": "Conta bloqueada, verificação de identidade pendente ou operação não liberada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "response": "ERROR", "message": "Verificação de identidade pendente", "code": "KYC_REQUIRED" } } } }, "429": { "description": "Limite de requisições atingido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "response": "ERROR", "message": "Limite de requisições por minuto atingido", "code": "RATE_LIMITED" } } } }, "500": { "description": "Erro", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "response": "ERROR", "message": "Erro interno" } } } } } } }, "/api/v1/gateway/pix-payment": { "post": { "operationId": "pixPayment", "tags": [ "Cash-out" ], "summary": "Enviar PIX (saque)", "description": "Envia um PIX do seu saldo para uma chave. O valor e a tarifa de saque são debitados na hora; o saque fica `processing` até a confirmação e o resultado chega no `callbackUrl` (`sucess` ou `not paid`, com estorno automático do valor e da tarifa).\n\n**Antes de usar:** libere o saque pela API em **Desenvolvedores** (exige o PIN). Sem liberação da WeetPay para pagar terceiros, o saque só pode ir para a chave CPF/CNPJ do próprio titular da conta. Acima do valor configurado pela plataforma, o saque passa por aprovação manual antes do envio.\n\n**Idempotência:** envie o cabeçalho `Idempotency-Key` (ou `requestNumber` no corpo). A mesma chave sempre devolve o mesmo saque (resposta com `Idempotent-Replayed: true`) e nunca debita de novo; a mesma chave com outro valor ou outra chave PIX é recusada com `409`. Sem chave, o mesmo valor para a mesma chave PIX em menos de 1 minuto devolve o saque anterior.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 100 }, "example": "saque-2026-10-30-0001", "description": "Chave única do pedido no seu sistema (também aceita `x-idempotency-key`). Máximo 100 caracteres." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixPayment" }, "example": { "amount": 150, "key": "12345678909", "typeKey": "CPF", "document": "12345678909", "callbackUrl": "https://sualoja.com.br/webhooks/weetpay-saques", "requestNumber": "saque-0001" } } } }, "responses": { "200": { "description": "Saque registrado (ou o mesmo saque, numa repetição idempotente)", "headers": { "Idempotent-Replayed": { "schema": { "type": "string", "enum": [ "true" ] }, "description": "Presente quando a resposta é de um saque que já existia" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixPaymentResponse" }, "example": { "id": "cmh1x9k2m0004ab12xy98zt76", "status": "processing" } } } }, "400": { "description": "Erro", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "response": "ERROR", "message": "insufficient balance" } } } }, "401": { "description": "Erro", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "response": "ERROR", "message": "Credenciais inválidas" } } } }, "403": { "description": "Erro", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "response": "ERROR", "message": "Saque pela API não está liberado nesta conta. Ative em Desenvolvedores." } } } }, "409": { "description": "Erro", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "response": "ERROR", "message": "Esta chave de idempotência já foi usada em outro saque" } } } }, "429": { "description": "Limite de requisições atingido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "response": "ERROR", "message": "Limite de requisições por minuto atingido", "code": "RATE_LIMITED" } } } }, "500": { "description": "Erro", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "response": "ERROR", "message": "Erro interno" } } } } } } }, "/api/v1/gateway/walletTransaction": { "post": { "operationId": "walletTransaction", "tags": [ "Transações" ], "summary": "Consultar transação", "description": "Consulta uma cobrança (`PIX_IN`) ou um saque (`PIX_OUT`) da sua conta. Informe **um** dos identificadores: `requestNumber` (o seu, da cobrança), `idTransaction` (o da WeetPay) ou `endToEnd` (o E2E do PIX). Saques são encontrados por `idTransaction` ou `endToEnd`.\n\nCobranças pendentes são conferidas no banco a cada consulta (no máximo a cada 10 s), então a consulta também serve de contingência caso um callback se perca. Mesmo assim, prefira o callback: não consulte em loop.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTransaction" }, "example": { "requestNumber": "pedido-12345" } } } }, "responses": { "200": { "description": "Transação encontrada", "content": { "application/json": { "schema": { "type": "object", "required": [ "transaction" ], "properties": { "transaction": { "$ref": "#/components/schemas/Transaction" } } }, "example": { "transaction": { "id": "cmh1x2y3z0001ab12cd34ef56", "created_at": "2026-10-30T13:02:11.000Z", "approvedDate": "2026-10-30T13:03:40.000Z", "transactionType": "PIX_IN", "destination": null, "destinationBank": null, "processingStatus": "PAID_OUT", "idTransaction": "cmh1x2y3z0001ab12cd34ef56", "idTransactionProvider": "E18236120202610301303s0123456789", "callbackUrl": "https://sualoja.com.br/webhooks/weetpay", "userSplit": null, "porcentageSplit": null, "amount": "49.90", "requestNumber": "pedido-12345", "account_id": 100123, "debtorName": "MARIA DA SILVA", "debtorDocument": "***.456.789-**", "pixCopiaECola": null, "endToEnd": "E18236120202610301303s0123456789" } } } } }, "400": { "description": "Erro", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "response": "ERROR", "message": "Informe requestNumber, idTransaction ou endToEnd" } } } }, "401": { "description": "Erro", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "response": "ERROR", "message": "Credenciais inválidas" } } } }, "403": { "description": "Conta bloqueada, verificação de identidade pendente ou operação não liberada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "response": "ERROR", "message": "Verificação de identidade pendente", "code": "KYC_REQUIRED" } } } }, "404": { "description": "Erro", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "response": "ERROR", "message": "Transação não encontrada" } } } }, "429": { "description": "Limite de requisições atingido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "response": "ERROR", "message": "Limite de requisições por minuto atingido", "code": "RATE_LIMITED" } } } }, "500": { "description": "Erro", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "response": "ERROR", "message": "Erro interno" } } } } } } }, "/api/v1/gateway/walletBalance": { "get": { "operationId": "walletBalance", "tags": [ "Conta" ], "summary": "Consultar saldo", "description": "Saldo disponível da conta, em reais, como string com duas casas decimais. É o valor que pode ser sacado agora (cobranças pagas já líquidas da tarifa, menos saques em andamento).", "responses": { "200": { "description": "Saldo", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" }, "example": { "currentBalance": "397.70" } } } }, "401": { "description": "Erro", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "response": "ERROR", "message": "Credenciais inválidas" } } } }, "403": { "description": "Conta bloqueada, verificação de identidade pendente ou operação não liberada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "response": "ERROR", "message": "Verificação de identidade pendente", "code": "KYC_REQUIRED" } } } }, "429": { "description": "Limite de requisições atingido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "response": "ERROR", "message": "Limite de requisições por minuto atingido", "code": "RATE_LIMITED" } } } }, "500": { "description": "Erro", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "response": "ERROR", "message": "Erro interno" } } } } } } } }, "components": { "securitySchemes": { "clientId": { "type": "apiKey", "in": "header", "name": "vspi", "description": "Client ID (ex.: `weetpay-100123`). Também aceito como `x-client-id`." }, "clientSecret": { "type": "apiKey", "in": "header", "name": "vsps", "description": "Client secret. Também aceito como `x-client-secret`. Nunca exponha no front-end." }, "basicAuth": { "type": "http", "scheme": "basic", "description": "Alternativa: `Authorization: Basic base64(client_id:client_secret)`" } }, "schemas": { "Error": { "type": "object", "required": [ "response", "message" ], "properties": { "response": { "type": "string", "enum": [ "ERROR" ] }, "message": { "type": "string", "description": "Motivo, em português, pronto para log" }, "code": { "type": "string", "enum": [ "RATE_LIMITED", "ACCOUNT_BLOCKED", "KYC_REQUIRED" ], "description": "Presente em alguns erros de autenticação" } } }, "Money": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "Valor em reais, maior que zero, até 2 casas decimais. Número (`10.5`) ou string (`\"10.50\"` ou `\"10,50\"`).", "examples": [ 10.5 ] }, "RequestQrcode": { "type": "object", "required": [ "requestNumber", "amount", "client" ], "properties": { "requestNumber": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Identificador do pedido no seu sistema. Único por conta." }, "amount": { "$ref": "#/components/schemas/Money" }, "callbackUrl": { "type": [ "string", "null" ], "format": "uri", "maxLength": 500, "description": "URL http(s) que recebe o aviso de pagamento ([Callbacks](/docs/webhooks)). Precisa ser pública." }, "client": { "type": "object", "required": [ "name", "document" ], "description": "Quem vai pagar", "properties": { "name": { "type": "string", "minLength": 3, "description": "Nome completo" }, "document": { "type": "string", "description": "CPF (11) ou CNPJ (14) válido; pontuação é removida" }, "email": { "type": [ "string", "null" ], "format": "email" }, "phoneNumber": { "type": [ "string", "null" ], "description": "Só dígitos são aproveitados" }, "address": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Livre, salvo na cobrança" } } }, "products": { "type": [ "array", "null" ], "maxItems": 100, "description": "Itens do pedido. As descrições compõem a descrição da cobrança (até 140 caracteres).", "items": { "type": "object", "required": [ "description" ], "additionalProperties": true, "properties": { "description": { "type": "string", "maxLength": 200 }, "quantity": { "type": "number" }, "value": { "type": "number", "description": "Valor unitário em reais" } } } }, "split": { "type": [ "object", "null" ], "required": [ "account", "percentageSplit" ], "description": "Divide o valor recebido com outra conta WeetPay. Só para contas com split liberado pelo Compliance.", "properties": { "account": { "oneOf": [ { "type": "string" }, { "type": "integer" } ], "description": "Número da conta WeetPay de destino (aprovada e ativa)" }, "percentageSplit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Percentual (inteiro) que vai para a conta de destino" } } } } }, "RequestQrcodeResponse": { "type": "object", "required": [ "idTransaction", "paymentCode", "paymentCodeBase64", "response", "status" ], "properties": { "idTransaction": { "type": "string", "description": "ID da cobrança na WeetPay" }, "paymentCode": { "type": "string", "description": "PIX copia e cola (BR Code)" }, "paymentCodeBase64": { "type": "string", "description": "Imagem PNG do QR Code em base64 (sem o prefixo `data:`)" }, "response": { "type": "string", "enum": [ "OK" ] }, "status": { "type": "string", "enum": [ "WAITING_FOR_APPROVAL" ] } } }, "PixPayment": { "type": "object", "required": [ "amount", "key", "typeKey", "document" ], "properties": { "amount": { "$ref": "#/components/schemas/Money" }, "key": { "type": "string", "description": "Chave PIX de destino" }, "typeKey": { "type": "string", "enum": [ "CPF", "CNPJ", "EMAIL", "PHONE", "EVP" ], "description": "Tipo da chave. `EVP` = chave aleatória." }, "document": { "type": "string", "description": "CPF/CNPJ do titular da chave. Para chave CPF/CNPJ, precisa ser o mesmo da chave." }, "callbackUrl": { "type": [ "string", "null" ], "format": "uri", "maxLength": 500, "description": "URL que recebe o resultado do saque" }, "requestNumber": { "type": [ "string", "null" ], "maxLength": 100, "description": "Sua referência; funciona como chave de idempotência quando não há o cabeçalho `Idempotency-Key`" }, "automaticWithdraw": { "type": "boolean", "description": "Aceito por compatibilidade e ignorado: o envio automático segue os limites da plataforma" } } }, "PixPaymentResponse": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string", "description": "ID do saque (use em `idTransaction` na consulta)" }, "status": { "type": "string", "enum": [ "processing" ] } } }, "WalletTransaction": { "type": "object", "description": "Informe pelo menos um dos campos", "properties": { "requestNumber": { "type": "string", "description": "Seu identificador da cobrança" }, "idTransaction": { "type": "string", "description": "ID da WeetPay (cobrança ou saque)" }, "endToEnd": { "type": "string", "description": "End-to-End ID do PIX" } } }, "Transaction": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "approvedDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando foi pago" }, "transactionType": { "type": "string", "enum": [ "PIX_IN", "PIX_OUT" ] }, "destination": { "type": [ "string", "null" ], "description": "Chave PIX de destino (saques)" }, "destinationBank": { "type": "null" }, "processingStatus": { "type": "string", "enum": [ "WAITING_FOR_APPROVAL", "PAID_OUT", "EXPIRED", "CANCELED", "REFUNDED", "PROCESSING", "NOT_PAID" ], "description": "Veja a tabela de status em Transações" }, "idTransaction": { "type": "string" }, "idTransactionProvider": { "type": [ "string", "null" ], "description": "End-to-End do PIX, quando houver" }, "callbackUrl": { "type": [ "string", "null" ] }, "userSplit": { "type": [ "string", "null" ], "description": "Conta que recebeu o split" }, "porcentageSplit": { "type": [ "integer", "null" ] }, "amount": { "type": "string", "description": "Valor em reais, duas casas", "examples": [ "49.90" ] }, "requestNumber": { "type": [ "string", "null" ] }, "account_id": { "type": "integer", "description": "Número da sua conta WeetPay" }, "debtorName": { "type": [ "string", "null" ], "description": "Pagador (cobranças pagas)" }, "debtorDocument": { "type": [ "string", "null" ] }, "pixCopiaECola": { "type": [ "string", "null" ], "description": "Só enquanto a cobrança está pendente" }, "endToEnd": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ], "description": "Motivo da falha (saques `NOT_PAID`)" } } }, "Balance": { "type": "object", "required": [ "currentBalance" ], "properties": { "currentBalance": { "type": "string", "description": "Saldo disponível em reais", "examples": [ "397.70" ] } } } } } }