{ "openapi": "3.0.0", "info": { "version": "1.0.0", "title": "API Conta Digital", "description": "API completa para operações de pagamento PIX, TED, transferências internas e gerenciamento de conta digital." }, "servers": [ { "url": "https://pix.payzu.io/v1" } ], "tags": [ { "name": "Depósitos", "description": "Receba pagamentos instantâneos via PIX. Gere QR Codes, acompanhe transações e configure webhooks para notificações em tempo real." }, { "name": "Saques", "description": "Envie dinheiro instantaneamente via PIX. Transfira usando chaves PIX, QR Codes ou dados bancários completos." }, { "name": "Gestão de Conta", "description": "Gerencie sua conta PayZu. Consulte saldos, extratos, métricas de performance e informações da conta." } ], "paths": { "/pix": { "post": { "summary": "Criar Cobrança PIX", "description": "Cria uma nova cobrança PIX para recebimento de pagamento.", "operationId": "createPixCharge", "tags": [ "Depósitos" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "number", "description": "Valor em BRL. Deve ser \u003E= 1.", "minimum": 1, "example": 150.5 }, "callbackUrl": { "type": "string", "description": "URL para receber webhooks de atualização da transação.", "example": "https://webhook.cool/" }, "generatedName": { "type": "string", "description": "Nome completo do pagador. Apenas letras e espaços.", "pattern": "^[a-zA-ZÀ-ÿ\\s]+$", "example": "John Doe" }, "generatedEmail": { "type": "string", "format": "email", "description": "Email do pagador (opcional).", "example": "john.doe@example.com" }, "generatedDocument": { "type": "string", "description": "CPF (11 dígitos) ou CNPJ (14 dígitos) do pagador, sem pontuação.", "pattern": "^[0-9]{11}$|^[0-9]{14}$", "example": "12345678901" }, "expiresIn": { "type": "number", "description": "Segundos até o QR Code expirar. Padrão: 600.", "example": 600 }, "description": { "type": "string", "description": "Descrição da transação.", "example": "Pagamento pedido #12345" }, "clientReference": { "type": "string", "description": "Referência externa (pedido, fatura, etc.).", "example": "order_12345" } } } } } }, "responses": { "200": { "description": "Cobrança criada com sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } } } }, "get": { "summary": "Consultar Transação", "description": "Acompanhe o status de suas transações PIX em tempo real. Consulte detalhes completos incluindo dados do pagador, valores, taxas e timestamps.", "operationId": "getPixTransaction", "tags": [ "Depósitos" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "id", "required": true, "description": "Id da transação", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transação encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } } } } }, "/withdraw": { "post": { "summary": "Transferir via Chave PIX", "description": "Realize transferências instantâneas usando qualquer tipo de chave PIX. Suporta CPF, CNPJ, e-mail, telefone ou chaves aleatórias (EVP).", "operationId": "createWithdraw", "tags": [ "Saques" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "pixKey", "pixType" ], "properties": { "amount": { "type": "number", "description": "Valor da transação em reais, deve ser maior do que 1" }, "pixKey": { "type": "string", "description": "Chave Pix do destinatário que receberá o valor", "example": "pix@payzu.com.br" }, "pixType": { "type": "string", "enum": [ "cpf", "cnpj", "phone", "email", "evp" ], "description": "Tipo da chave Pix fornecida", "example": "email" }, "callbackUrl": { "type": "string", "description": "Url na qual será enviado notificações sobre mudanças no status da transação" }, "description": { "type": "string", "description": "Descrição da transação" }, "clientReference": { "type": "string", "description": "Referência externa (pedido, fatura, etc.)", "example": "order_12346" } } } } } }, "responses": { "200": { "description": "Transferência iniciada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } } } } }, "/withdraw/qrcode": { "post": { "summary": "Transferir via QR Code", "description": "Pague instantaneamente escaneando ou colando um QR Code PIX. Ideal para pagamentos em estabelecimentos ou transferências rápidas.", "operationId": "createWithdrawQrCode", "tags": [ "Saques" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "qrCode" ], "properties": { "amount": { "type": "number", "description": "Valor da transação em reais, deve ser maior do que 1" }, "qrCode": { "type": "string", "description": "String do QR Code PIX do destinatário", "example": "00020126870014br.gov.bcb.pix2565qrcode.payzu.com.br/dynamic/d7790b91-3979-4ad5-9d96-ee941e5a42765204000053" }, "callbackUrl": { "type": "string", "description": "Url na qual será enviado notificações sobre mudanças no status da transação" }, "description": { "type": "string", "description": "Descrição da transação" }, "clientReference": { "type": "string", "description": "Referência externa (pedido, fatura, etc.)", "example": "order_12347" } } } } } }, "responses": { "200": { "description": "Transferência iniciada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } } } } }, "/withdraw/bank-data": { "post": { "summary": "Transferir via Dados Bancários", "description": "Envie PIX usando dados bancários completos do destinatário. Suporta bancos tradicionais e instituições de pagamento.", "operationId": "createWithdrawBankData", "tags": [ "Saques" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "receiverName", "receiverDocument", "receiverBankBranch", "receiverBankAccount", "receiverBankAccountDigit" ], "properties": { "amount": { "type": "number", "description": "Valor da transação em reais, deve ser maior do que 1", "example": 1 }, "receiverName": { "type": "string", "description": "Nome completo do recebedor", "example": "John Doe" }, "receiverDocument": { "type": "string", "description": "CPF ou CNPJ do recebedor (somente números)", "example": "12345678901" }, "receiverInstitutionBank": { "type": "string", "description": "Código do banco do recebedor (obrigatório se receiverInstitutionIspb não for informado)", "example": "450" }, "receiverInstitutionIspb": { "type": "string", "description": "Código ISPB para instituições de pagamento indiretas (obrigatório se receiverInstitutionBank não for informado)", "pattern": "^[0-9]{8}$", "example": "12345678" }, "receiverBankBranch": { "type": "string", "description": "Agência do banco do recebedor", "example": "0001" }, "receiverBankAccount": { "type": "string", "description": "Número da conta do recebedor", "example": "9249847337" }, "receiverBankAccountDigit": { "type": "string", "description": "Dígito verificador da conta", "example": "1" }, "clientReference": { "type": "string", "description": "Referência externa (pedido, fatura, etc.)", "example": "order_12348" }, "callbackUrl": { "type": "string", "description": "URL para receber webhooks de atualização da transação", "example": "https://webhook.example.com/callback" }, "description": { "type": "string", "description": "Descrição da transação" } } } } } }, "responses": { "200": { "description": "Transferência iniciada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } } } } }, "/pix/refund/{id}": { "post": { "summary": "Estornar Transação", "description": "Devolva valores recebidos via PIX de forma rápida e segura. O estorno é processado instantaneamente para a conta de origem.", "operationId": "refundPixTransaction", "tags": [ "Depósitos" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "Transaction ID.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "Descrição do reembolso" }, "callbackUrl": { "type": "string", "description": "Url de callback" }, "clientReference": { "type": "string", "description": "Referência externa (pedido, fatura, etc.)", "example": "order_12348" } } } } } }, "responses": { "200": { "description": "Estorno iniciado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } } } } }, "/ted": { "post": { "summary": "Transferir via TED", "description": "Envie dinheiro via TED (Transferência Eletrônica Disponível) para contas em outros bancos. Processamento em até 1 dia útil.", "operationId": "createWithdrawTed", "tags": [ "Saques" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "receiverName", "receiverDocument", "receiverBank", "receiverBankBranch", "receiverBankAccount", "receiverBankAccountDigit" ], "properties": { "amount": { "type": "number", "description": "Valor da transferência em reais", "minimum": 1, "example": 10 }, "receiverName": { "type": "string", "description": "Nome completo do recebedor", "example": "PAYZU PAGAMENTOS LTDA" }, "receiverDocument": { "type": "string", "description": "CPF ou CNPJ do recebedor (somente números)", "example": "50600904000126" }, "receiverBank": { "type": "string", "description": "Código do banco do recebedor", "example": "077" }, "receiverBankBranch": { "type": "string", "description": "Agência do banco do recebedor", "example": "0001" }, "receiverBankAccount": { "type": "string", "description": "Número da conta do recebedor", "example": "29074338" }, "receiverBankAccountDigit": { "type": "string", "description": "Dígito verificador da conta", "example": "9" }, "clientReference": { "type": "string", "description": "Referência externa (pedido, fatura, etc.)", "example": "order_12350" }, "callbackUrl": { "type": "string", "description": "URL para receber webhooks de atualização da transação", "example": "https://webhook.example.com/callback" }, "description": { "type": "string", "description": "Descrição da transferência" } } } } } }, "responses": { "200": { "description": "Transferência TED iniciada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } } } } }, "/internal-transfer": { "post": { "summary": "Transferência Interna", "description": "Realiza transferências instantâneas entre contas PayZu. Ideal para movimentações entre contas da mesma plataforma, com taxas reduzidas e processamento imediato.", "operationId": "createInternalTransfer", "tags": [ "Saques" ], "security": [ { "BearerAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "receiverDocument" ], "properties": { "amount": { "type": "number", "description": "Valor da transferência em reais", "minimum": 1, "example": 5 }, "receiverDocument": { "type": "string", "description": "CPF ou CNPJ do destinatário (somente números)", "pattern": "^[0-9]{11}$|^[0-9]{14}$", "example": "03338960174" }, "description": { "type": "string", "description": "Descrição da transferência", "example": "Transferência interna" }, "clientReference": { "type": "string", "description": "Referência externa (pedido, fatura, etc.)", "example": "order_12349" } } } } } }, "responses": { "200": { "description": "Transferência iniciada com sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } } } } }, "/proof/{id}": { "get": { "summary": "Baixar Comprovante", "description": "Baixe comprovantes oficiais de suas transações PIX. Disponível em PDF para impressão ou Base64 para integrações automáticas.", "operationId": "getTransactionProof", "tags": [ "Depósitos", "Saques" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "Id da transação", "schema": { "type": "string" } }, { "in": "query", "name": "type", "required": false, "description": "Tipo que o comprovante será retornado", "schema": { "type": "string", "enum": [ "base64", "pdf" ], "default": "pdf" } } ], "responses": { "200": { "description": "Comprovante obtido com sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "base64": { "type": "string" } } } }, "application/pdf": { "schema": { "type": "string", "format": "binary" } } } } } } }, "/user": { "get": { "summary": "Informações da Conta", "description": "Acesse dados completos da sua conta PayZu incluindo limites operacionais, taxas configuradas, chave PIX vinculada e permissões ativas.", "operationId": "getUser", "tags": [ "Gestão de Conta" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Dados da conta obtidos com sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } } } } }, "/user/balance": { "get": { "summary": "Consultar Saldos", "description": "Verifique em tempo real seus saldos disponíveis, bloqueados e liberados para saque. Ideal para controle financeiro e conciliação.", "operationId": "getUserBalance", "tags": [ "Gestão de Conta" ], "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Saldo obtido com sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "balanceAvailable": { "type": "number", "description": "Saldo disponível na conta" }, "balanceBlocked": { "type": "number", "description": "Saldo bloqueado" }, "balanceAvailableWithdraw": { "type": "number", "description": "Saldo disponível para saque" } } } } } } } } }, "/user/transactions": { "get": { "summary": "Extrato de Transações", "description": "Acesse o histórico completo de movimentações da sua conta. Filtre por período, tipo, status ou valor. Suporta paginação e exportação.", "operationId": "getUserTransactions", "tags": [ "Gestão de Conta" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "dateFrom", "required": false, "description": "Data inicial do período", "schema": { "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00.000Z" } }, { "in": "query", "name": "dateTo", "required": false, "description": "Data final do período", "schema": { "type": "string", "format": "date-time", "example": "2025-01-31T23:59:59.999Z" } }, { "in": "query", "name": "limit", "required": false, "description": "Limite de itens por página. (Máximo 1000)", "schema": { "type": "number", "default": 10 } }, { "in": "query", "name": "page", "required": false, "description": "Número da página", "schema": { "type": "number", "default": 1 } }, { "in": "query", "name": "id", "required": false, "description": "ID da transação", "schema": { "type": "string" } }, { "in": "query", "name": "status", "required": false, "description": "Status da transação", "schema": { "type": "string" } }, { "in": "query", "name": "type", "required": false, "description": "Tipo da transação", "schema": { "type": "string" } }, { "in": "query", "name": "amount", "required": false, "description": "Valor da transação", "schema": { "type": "number" } }, { "in": "query", "name": "document", "required": false, "description": "CPF/CNPJ para filtrar transações", "schema": { "type": "string" } }, { "in": "query", "name": "name", "required": false, "description": "Nome para filtrar transações", "schema": { "type": "string" } }, { "in": "query", "name": "endToEndId", "required": false, "description": "ID end-to-end da transação", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lista de transações", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "number" }, "pages": { "type": "number" }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } } } } } } } } } }, "/user/summary": { "get": { "summary": "Relatório de Performance", "description": "Analise métricas detalhadas do seu negócio. Visualize volumes transacionados, taxas de conversão e tendências por período.", "operationId": "getUserSummary", "tags": [ "Gestão de Conta" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "in": "query", "name": "dateFrom", "required": false, "description": "Data inicial do período", "schema": { "type": "string", "format": "date-time", "example": "2025-01-01T00:00:00.000Z" } }, { "in": "query", "name": "dateTo", "required": false, "description": "Data final do período", "schema": { "type": "string", "format": "date-time", "example": "2025-01-31T23:59:59.999Z" } }, { "in": "query", "name": "groupBy", "required": false, "description": "Formato de agrupamento das transações", "schema": { "type": "string", "enum": [ "day", "hour" ], "default": "day" } }, { "in": "query", "name": "grouped", "required": false, "description": "Se deve retornar transações agrupadas", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Métricas obtidas com sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Summary" } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "Transaction": { "type": "object", "properties": { "id": { "type": "string", "example": "PAYZU20250817215911F49RDOBJ" }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "CANCELED", "WAITING_FOR_REFUND", "REFUNDED", "EXPIRED", "ERROR" ] }, "amount": { "type": "number", "example": "150.50" }, "type": { "type": "string", "enum": [ "DEPOSIT", "WITHDRAW", "COMMISSION", "LIQUIDATION", "INTERNAL_TRANSFER" ] }, "qrCodeText": { "type": "string", "nullable": true, "example": "00020126870014br.gov.bcb.pix2565qrcode.payzu.com.br/dynamic/d7790b91-3979-4ad5-9d96-ee941e5a42765204000053" }, "qrCodeBase64": { "type": "string", "nullable": true }, "qrCodeUrl": { "type": "string", "nullable": true }, "generatedName": { "type": "string", "nullable": true }, "generatedDocument": { "type": "string", "nullable": true }, "generatedEmail": { "type": "string", "nullable": true }, "payerName": { "type": "string", "nullable": true }, "payerDocument": { "type": "string", "nullable": true }, "payerInstitutionIspb": { "type": "string", "nullable": true }, "payerInstitutionName": { "type": "string", "nullable": true }, "serviceFeeCharged": { "type": "number", "example": "0.50" }, "withdrawPixKey": { "type": "string", "nullable": true, "example": "pix@payzu.com.br" }, "withdrawPixType": { "type": "string", "nullable": true, "enum": [ "cpf", "cnpj", "phone", "email", "evp" ], "example": "email" }, "receiverName": { "type": "string", "nullable": true }, "receiverDocument": { "type": "string", "nullable": true }, "receiverInstitutionIspb": { "type": "string", "nullable": true }, "receiverInstitutionName": { "type": "string", "nullable": true }, "endToEndId": { "type": "string", "nullable": true }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "paidAt": { "type": "string", "nullable": true }, "refundEndToEndId": { "type": "string", "nullable": true }, "refundId": { "type": "string", "nullable": true }, "refundedAt": { "type": "string", "nullable": true }, "clientReference": { "type": "string", "nullable": true }, "refundedAmount": { "type": "number", "nullable": true, "example": "150.50" }, "errorReason": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true }, "method": { "type": "string", "nullable": true, "enum": [ "PIX", "BANK_SLIP", "TED" ], "example": "TED" }, "receiverInstitutionBank": { "type": "string", "nullable": true, "example": "077" }, "payerInstitutionBank": { "type": "string", "nullable": true, "example": "450" }, "payerBankBranch": { "type": "string", "nullable": true, "example": "0001" }, "payerAccountNumber": { "type": "string", "nullable": true, "example": "9249868686" }, "payerAccountDigit": { "type": "string", "nullable": true, "example": "3" }, "receiverBankBranch": { "type": "string", "nullable": true, "example": "0001" }, "receiverAccountNumber": { "type": "string", "nullable": true, "example": "29074338" }, "receiverAccountDigit": { "type": "string", "nullable": true, "example": "9" }, "refundCallbackUrl": { "type": "string", "nullable": true }, "callbackUrl": { "type": "string", "nullable": true, "example": "https://webhook.cool/" }, "payerAccountType": { "type": "number", "nullable": true, "enum": [0, 1, 2, 3], "example": "0", "description": "0: Corrente, 1: Salário, 2: Poupança, 3: Pagamento" }, "receiverAccountType": { "type": "number", "nullable": true, "enum": [0, 1, 2, 3], "example": "0", "description": "0: Corrente, 1: Salário, 2: Poupança, 3: Pagamento" }, "withdrawQrCodeText": { "type": "string", "nullable": true, "description": "QR Code usado no saque", "example": "0020126870014br.gov.bcb.pix2565qrcode.payzu.com.br/dynamic/d7790b91-3979-4ad5-9d" } } }, "User": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "balanceAvailable": { "type": "number" }, "balanceBlocked": { "type": "number" }, "status": { "type": "string" }, "allowWithdraw": { "type": "boolean" }, "allowDeposit": { "type": "boolean" }, "allowInfraction": { "type": "boolean" }, "cashInTicketMin": { "type": "number" }, "cashInTicketMax": { "type": "number" }, "cashOutTicketMin": { "type": "number" }, "cashOutTicketMax": { "type": "number" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "account": { "type": "object", "properties": { "number": { "type": "string" }, "digit": { "type": "string" }, "branch": { "type": "string" }, "document": { "type": "string" }, "bank": { "type": "object", "properties": { "code": { "type": "string" }, "ispb": { "type": "string" }, "name": { "type": "string" } } } } }, "ServiceFee": { "type": "object", "properties": { "cashInMinimum": { "type": "number" }, "cashInFixed": { "type": "number" }, "cashInPercent": { "type": "number" }, "cashOutMinimum": { "type": "number" }, "cashOutFixed": { "type": "number" }, "cashOutPercent": { "type": "number" } } } } }, "Summary": { "type": "object", "properties": { "totalTransactions": { "type": "number" }, "deposit": { "type": "object", "properties": { "totalAmount": { "type": "number" }, "totalTransactions": { "type": "number" }, "statuses": { "type": "object" }, "grouped": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "amount": { "type": "number" } } } } } }, "withdraw": { "type": "object", "properties": { "totalAmount": { "type": "number" }, "totalTransactions": { "type": "number" }, "statuses": { "type": "object" }, "grouped": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "amount": { "type": "number" } } } } } }, "liquidation": { "type": "object", "properties": { "totalAmount": { "type": "number" }, "totalTransactions": { "type": "number" }, "statuses": { "type": "object" } } }, "balancesLogAdmin": { "type": "object", "properties": { "increments": { "type": "number" }, "decrements": { "type": "number" } } }, "creditCard": { "type": "object", "properties": { "statuses": { "type": "object" }, "chargebacks": { "type": "number" }, "preChargebacks": { "type": "number" } } } } } } } }