{ "openapi": "3.1.0", "info": { "title": "PagzPay API", "version": "1.0.0", "x-logo": { "url": "./assets/brand/logo-light.png", "altText": "PagzPay" }, "description": "# Bem-vindo à API PagzPay\n\nA **PagzPay** é uma plataforma de pagamentos focada no mercado brasileiro.\nCom nossa API você pode receber pagamentos via **PIX** e **cartão de crédito** (Pagar.me),\nrealizar **transferências PIX**, consultar seu **saldo**, configurar **split de pagamentos** e\n**webhooks** para notificações em tempo real.\n\n## Como começar\n\n1. Acesse o [Dashboard](https://app.pagzpay.com) e gere suas credenciais em **Configurações → API Keys**\n2. Autentique-se enviando `API Key:API Secret` (Basic Auth) para `POST /api/auth`\n3. Use o **Bearer token** retornado em todas as requisições\n\n## Base URL\n\n```\nhttps://api.pagzpay.com\n```\n\n## Valores monetários\n\nTodos os valores são em **centavos (inteiros)**.\n\n| Valor real | Em centavos |\n|------------|-------------|\n| R$ 1,00 | `100` |\n| R$ 10,50 | `1050` |\n| R$ 150,00 | `15000` |\n\n## Idempotência\n\nPara transferências PIX, envie o header `x-idempotency-key` com um valor único por operação.\nIsso garante que em caso de retry a operação não seja duplicada.\n", "contact": { "name": "Suporte PagzPay", "email": "suporte@pagzpay.com", "url": "https://app.pagzpay.com" } }, "servers": [ { "url": "https://api.pagzpay.com", "description": "API PagzPay" } ], "tags": [ { "name": "Autenticação", "description": "Geração de tokens de acesso via API Key.\n\nUse suas credenciais (`client_id` e `client_secret`) com **Basic Auth** para obter um JWT Bearer token.\nO token é necessário em todas as demais rotas.\n" }, { "name": "PIX IN", "description": "Receba pagamentos instantâneos via QR Code PIX.\n\nCrie um QR Code e exiba para o seu cliente pagar. Ao receber o pagamento, você será\nnotificado via webhook (se configurado).\n" }, { "name": "Cartão", "description": "Cobranças com **cartão de crédito** via adquirente **Pagar.me**.\n\nExige `customer.billingAddress` e adquirente de cartão configurada no admin (`cardAdquirenceId`).\nPrefira enviar `card.token` (tokenização no browser) em vez de PAN completo.\n\n### Tokenização (Pagar.me — fora da PagzPay)\n\nA PagzPay **não** expõe endpoint de tokenização. No browser, chame:\n\n```\nPOST https://api.pagar.me/core/v5/tokens?appId={PUBLIC_KEY}\n```\n\nUse a chave pública Pagar.me (`pk_test_…` / `pk_…`) da conta ligada à adquirente de cartão.\nEnvie o `id` retornado (`token_…`) em `card.token` no `POST /api/v1/card`.\n\nNo **checkout hospedado**, habilite cartão nos métodos aceitos — a página tokeniza com a\nchave pública Pagar.me e chama `POST /checkout/{token}/pay/card`.\n" }, { "name": "Transações", "description": "Consulta de cobranças (PIX, cartão, etc.) pelo `id` retornado na criação.\n\nUse `GET .../status` para polling leve (apenas o status).\n" }, { "name": "PIX OUT", "description": "Envie transferências PIX para qualquer chave PIX.\n\nSuporta chaves do tipo CPF, CNPJ, e-mail, telefone e chave aleatória (EVP).\nRequer o header `x-idempotency-key` para evitar duplicações.\n" }, { "name": "Saldo", "description": "Consulte os saldos das carteiras da sua conta em tempo real.\n\nOs valores são retornados em **reais** (string com 2 casas decimais).\n\n| Campo | Descrição |\n|-------|-----------|\n| `pix.balance` | Saldo disponível para uso |\n| `pixBlocked.balance` | Saldo bloqueado (cautelar / MED) |\n| `reserve.balance` | Valor em reserva |\n" }, { "name": "Webhooks", "description": "Receba notificações em tempo real sobre eventos da sua conta.\n\nConfigure uma URL e escolha quais eventos deseja monitorar.\nO PagzPay enviará um `POST` com o payload do evento para a URL configurada.\n\nAlém dos webhooks cadastrados em `/api/v1/webhook`, quando uma cobrança ou\ntransferência é criada com `postbackUrl`, o mesmo callback também é enviado para\nessa URL.\n\n### Eventos disponíveis\n\nUse os eventos abaixo no campo `events` ao criar um webhook.\n\n| Fluxo | Evento | Quando é enviado |\n|-------|--------|------------------|\n| PIX IN | `transaction_created` | Cobrança PIX criada |\n| PIX IN | `transaction_paid` | Cobrança PIX paga |\n| PIX IN | `transaction_refunded` | Cobrança PIX estornada |\n| PIX IN | `transaction_updated` | Cobrança PIX atualizada com outro status |\n| PIX IN | `infraction` | Infração/MED criada ou atualizada para uma cobrança PIX |\n| PIX OUT | `transfer_created` | Transferência PIX criada |\n| PIX OUT | `transfer_updated` | Transferência PIX atualizada com outro status |\n| PIX OUT | `transfer_completed` | Transferência PIX concluída |\n| PIX OUT | `transfer_canceled` | Transferência PIX cancelada ou recusada |\n\n### Headers enviados no callback\n\n| Header | Valor |\n|--------|-------|\n| `Content-Type` | `application/json` |\n| `User-Agent` | `PagzPay` |\n| `PagzPay-Signature` | Assinatura HMAC-SHA256 no formato `t={timestamp},v1={hash}` quando o webhook possui `signatureSecret` |\n\n### Payload de PIX IN\n\nEnviado nos eventos `transaction_created`, `transaction_paid`, `transaction_refunded`\ne `transaction_updated`.\n\n```json\n{\n \"id\": \"8d0f3b8f-5c2f-4a10-8dd6-8bbf5e9b1d11\",\n \"type\": \"transaction\",\n \"event\": \"transaction_paid\",\n \"scope\": \"user\",\n \"transaction\": {\n \"id\": \"transaction_abc123\",\n \"amount\": 5000,\n \"status\": \"paid\",\n \"pix\": {\n \"endToEndId\": \"E1234567820241231000000000000001\",\n \"payerInfo\": {\n \"name\": \"Joao Silva\",\n \"document\": \"11122233344\"\n }\n }\n }\n}\n```\n\n### Payload de PIX OUT\n\nEnviado nos eventos `transfer_created`, `transfer_updated`, `transfer_completed`\ne `transfer_canceled`.\n\n```json\n{\n \"id\": \"5f9e0c94-60a4-4df8-bb81-7f6efc6f61b0\",\n \"type\": \"transfer\",\n \"event\": \"transfer_completed\",\n \"scope\": \"user\",\n \"transfer\": {\n \"id\": \"transfer_abc123\",\n \"amount\": 10000,\n \"status\": \"paid\",\n \"pix\": {\n \"endToEndId\": \"E1234567820241231000000000000002\",\n \"creditorAccount\": {\n \"name\": \"Fornecedor Exemplo\",\n \"document\": \"12345678000199\"\n }\n }\n }\n}\n```\n\n### Payload de infração PIX IN\n\nEnviado no evento `infraction`.\n\n```json\n{\n \"id\": \"3db3ac40-a069-45e6-8cb8-6d55d09f516d\",\n \"type\": \"infraction\",\n \"event\": \"infraction\",\n \"scope\": \"user\",\n \"infraction\": {\n \"id\": \"infraction_abc123\",\n \"amount\": 5000,\n \"status\": \"OPEN\",\n \"pix\": {\n \"endToEndId\": \"E1234567820241231000000000000001\"\n }\n },\n \"transaction\": {\n \"id\": \"transaction_abc123\",\n \"amount\": 5000,\n \"status\": \"infraction\",\n \"pix\": {\n \"endToEndId\": \"E1234567820241231000000000000001\",\n \"payerInfo\": {\n \"name\": \"Joao Silva\",\n \"document\": \"11122233344\"\n }\n }\n }\n}\n```\n" }, { "name": "Formato dos Webhooks", "description": "Exemplos dos payloads enviados pelo PagzPay nos callbacks.\n\nEsta seção é apenas referência de formato. Os callbacks são enviados via `POST`\npara a URL configurada no webhook ou no `postbackUrl`.\n" } ], "paths": { "/api/auth": { "post": { "tags": [ "Autenticação" ], "summary": "Gerar token de acesso", "operationId": "auth-generate-token", "description": "Gera um **token JWT** para autenticar as demais requisições da API.\n\n### Como montar o header Basic Auth\n\nConcatene `API Key:API Secret` (gerados no Dashboard em **Configurações → API Keys**)\ne codifique em **Base64**:\n\n```bash\necho -n \"SUA_API_KEY:SEU_API_SECRET\" | base64\n# → U1VBX0FQSV9LRVk6U0VVX0FQSV9TRUNSRVQ=\n```\n\nEntão envie no header:\n```\nAuthorization: Basic U1VBX0FQSV9LRVk6U0VVX0FQSV9TRUNSRVQ=\n```\n\n> Esta rota **não exige body** — envie apenas o header `Authorization`.\n> Body vazio com `Content-Type: application/json` (axios) ou\n> `application/x-www-form-urlencoded` (PHP `CURLOPT_POST`) é aceito.\n\n### Token retornado\n\nUse o `token` retornado como Bearer em todas as outras rotas:\n```\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIs...\n```\n", "security": [ { "basicAuth": [] } ], "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://api.pagzpay.com/api/auth' \\\n -H 'Authorization: Basic SEU_BASIC_AUTH_AQUI'\n" }, { "lang": "JavaScript", "label": "Node.js", "source": "const credentials = Buffer.from('SUA_API_KEY:SEU_API_SECRET').toString('base64')\n\nconst response = await fetch('https://api.pagzpay.com/api/auth', {\n method: 'POST',\n headers: {\n 'Authorization': `Basic ${credentials}`\n }\n})\n\nconst { token } = await response.json()\n" }, { "lang": "Python", "label": "Python", "source": "import requests\nimport base64\n\ncredentials = base64.b64encode(b'SUA_API_KEY:SEU_API_SECRET').decode()\n\nresponse = requests.post(\n 'https://api.pagzpay.com/api/auth',\n headers={'Authorization': f'Basic {credentials}'}\n)\n\ntoken = response.json()['token']\n" }, { "lang": "PHP", "label": "PHP", "source": "$credentials = base64_encode('SUA_API_KEY:SEU_API_SECRET');\n\n$ch = curl_init('https://api.pagzpay.com/api/auth');\ncurl_setopt($ch, CURLOPT_POST, true);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\n 'Authorization: Basic ' . $credentials,\n 'Accept: application/json'\n]);\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n\n$response = json_decode(curl_exec($ch), true);\n$token = $response['token'];\n" } ], "responses": { "200": { "description": "Token gerado com sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "token": { "type": "string", "description": "JWT Bearer token — use em todas as próximas requisições", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOnsiY29tcGFueSI6eyJpZCI6ImNseDFhYmMifX19..." }, "tokenType": { "type": "string", "example": "Bearer" }, "expiresIn": { "type": "integer", "description": "Tempo de expiração em milissegundos", "example": 60000 } } }, "example": { "success": true, "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "tokenType": "Bearer", "expiresIn": 60000 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/pix/in/qrcode": { "post": { "tags": [ "PIX IN" ], "summary": "Criar QR Code PIX", "operationId": "pix-in-create-qrcode", "description": "Cria um **QR Code PIX** para receber um pagamento imediato.\n\nRetorna o **código EMV** (copia e cola) e a **imagem Base64** do QR Code,\nprontos para exibir ao seu cliente.\n\n### Fluxo completo\n\n```\n1. Sua aplicação chama POST /api/v1/pix/in/qrcode\n2. PagzPay retorna emv + qrCode (Base64)\n3. Você exibe o QR Code ao cliente\n4. Cliente paga no app do banco\n5. PagzPay envia notificação no postbackUrl (se informado)\n```\n\n### Recebendo a confirmação\n\nConfigure `postbackUrl` para receber uma notificação automática quando o pagamento\nfor confirmado, sem precisar fazer polling.\n\n### Dados do produto (compliance) — opcionais, recomendados\n\nA adquirente pede informações sobre o que está sendo vendido para análise de\ncompliance. Todos os campos abaixo são **opcionais**: se não forem enviados a\ncobrança funciona normalmente. Quando enviados, o PagzPay repassa à adquirente.\n\n| Campo | O que é |\n|-------|---------|\n| `items[].title` | Nome real do produto |\n| `items[].imageUrl` | URL pública da foto real do produto |\n| `salesSiteUrl` | URL do site onde o produto é vendido |\n| `checkoutUrl` | URL da página de checkout onde o pagamento foi feito |\n| `supportContact` | Contato de suporte do vendedor (`email`, `phone`, `whatsapp` e/ou `url`) |\n", "security": [ { "bearerAuth": [] } ], "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://api.pagzpay.com/api/v1/pix/in/qrcode' \\\n -H 'Authorization: Bearer SEU_TOKEN_AQUI' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"amountInCents\": 5000,\n \"description\": \"Pagamento de serviços\",\n \"postbackUrl\": \"https://exemplo.com.br/webhook\",\n \"trackingParameters\": {\n \"src\": \"facebook\",\n \"sck\": \"sck-exemplo\",\n \"utm_source\": \"meta\",\n \"utm_campaign\": \"campanha-exemplo\",\n \"utm_medium\": \"cpc\",\n \"utm_content\": \"criativo-1\",\n \"utm_term\": \"tenis\",\n \"fbclid\": \"fbclid-exemplo\",\n \"gclid\": \"gclid-exemplo\",\n \"ttclid\": \"ttclid-exemplo\",\n \"xcod\": \"xcod-exemplo\"\n },\n \"customer\": {\n \"name\": \"João Silva\",\n \"email\": \"joao@exemplo.com\",\n \"documentType\": \"cpf\",\n \"document\": \"11122233344\",\n \"phone\": \"(11) 91234-5678\"\n }\n }'\n" }, { "lang": "JavaScript", "label": "Node.js", "source": "const response = await fetch('https://api.pagzpay.com/api/v1/pix/in/qrcode', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer SEU_TOKEN_AQUI',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n amountInCents: 5000,\n description: 'Pagamento de serviços',\n postbackUrl: 'https://exemplo.com.br/webhook',\n trackingParameters: {\n src: 'facebook',\n sck: 'sck-exemplo',\n utm_source: 'meta',\n utm_campaign: 'campanha-exemplo',\n utm_medium: 'cpc',\n utm_content: 'criativo-1',\n utm_term: 'tenis',\n fbclid: 'fbclid-exemplo',\n gclid: 'gclid-exemplo',\n ttclid: 'ttclid-exemplo',\n xcod: 'xcod-exemplo'\n },\n customer: {\n name: 'João Silva',\n email: 'joao@exemplo.com',\n documentType: 'cpf',\n document: '11122233344',\n phone: '(11) 91234-5678'\n }\n })\n})\n\nconst { data } = await response.json()\nconsole.log(data.pix.emv) // código copia e cola\nconsole.log(data.pix.qrCode) // imagem Base64\n" }, { "lang": "Python", "label": "Python", "source": "import requests\n\nresponse = requests.post(\n 'https://api.pagzpay.com/api/v1/pix/in/qrcode',\n headers={\n 'Authorization': 'Bearer SEU_TOKEN_AQUI',\n 'Content-Type': 'application/json'\n },\n json={\n 'amountInCents': 5000,\n 'description': 'Pagamento de servicos',\n 'postbackUrl': 'https://exemplo.com.br/webhook',\n 'trackingParameters': {\n 'src': 'facebook',\n 'sck': 'sck-exemplo',\n 'utm_source': 'meta',\n 'utm_campaign': 'campanha-exemplo',\n 'utm_medium': 'cpc',\n 'utm_content': 'criativo-1',\n 'utm_term': 'tenis',\n 'fbclid': 'fbclid-exemplo',\n 'gclid': 'gclid-exemplo',\n 'ttclid': 'ttclid-exemplo',\n 'xcod': 'xcod-exemplo'\n },\n 'customer': {\n 'name': 'Joao Silva',\n 'email': 'joao@exemplo.com',\n 'documentType': 'cpf',\n 'document': '11122233344',\n 'phone': '(11) 91234-5678'\n }\n }\n)\n\ndata = response.json()['data']\nprint(data['pix']['emv'])\n" }, { "lang": "PHP", "label": "PHP", "source": "$payload = json_encode([\n 'amountInCents' => 5000,\n 'description' => 'Pagamento de servicos',\n 'postbackUrl' => 'https://exemplo.com.br/webhook',\n 'trackingParameters' => [\n 'src' => 'facebook',\n 'sck' => 'sck-exemplo',\n 'utm_source' => 'meta',\n 'utm_campaign' => 'campanha-exemplo',\n 'utm_medium' => 'cpc',\n 'utm_content' => 'criativo-1',\n 'utm_term' => 'tenis',\n 'fbclid' => 'fbclid-exemplo',\n 'gclid' => 'gclid-exemplo',\n 'ttclid' => 'ttclid-exemplo',\n 'xcod' => 'xcod-exemplo'\n ],\n 'customer' => [\n 'name' => 'Joao Silva',\n 'email' => 'joao@exemplo.com',\n 'documentType' => 'cpf',\n 'document' => '11122233344',\n 'phone' => '(11) 91234-5678'\n ]\n]);\n\n$ch = curl_init('https://api.pagzpay.com/api/v1/pix/in/qrcode');\ncurl_setopt($ch, CURLOPT_POST, true);\ncurl_setopt($ch, CURLOPT_POSTFIELDS, $payload);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\n 'Authorization: Bearer SEU_TOKEN_AQUI',\n 'Content-Type: application/json'\n]);\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n\n$response = json_decode(curl_exec($ch), true);\n" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amountInCents", "customer" ], "properties": { "amountInCents": { "type": "integer", "minimum": 100, "description": "Valor da cobrança em centavos (mínimo R$ 1,00)", "example": 5000 }, "description": { "type": "string", "maxLength": 140, "description": "Descrição que aparecerá no extrato do pagador", "example": "Pagamento de serviços" }, "postbackUrl": { "type": "string", "format": "uri", "description": "URL para receber notificação quando o pagamento for confirmado.\nPode incluir UTMs na query; o PagzPay faz merge com trackingParameters.\n", "example": "https://exemplo.com.br/webhook" }, "trackingParameters": { "$ref": "#/components/schemas/TrackingParameters" }, "salesSiteUrl": { "$ref": "#/components/schemas/SalesSiteUrl" }, "checkoutUrl": { "$ref": "#/components/schemas/CheckoutUrl" }, "supportContact": { "$ref": "#/components/schemas/SupportContact" }, "customer": { "$ref": "#/components/schemas/Customer" }, "items": { "type": "array", "description": "Itens do pedido (opcional)", "items": { "type": "object", "required": [ "title", "tangible", "quantity", "amountInCents" ], "properties": { "title": { "type": "string", "description": "Nome real do produto", "example": "Produto A" }, "imageUrl": { "type": "string", "format": "uri", "description": "URL pública da foto real do produto (opcional, compliance)", "example": "https://minhaloja.com.br/img/produto-a.jpg" }, "tangible": { "type": "boolean", "example": true }, "quantity": { "type": "integer", "example": 2 }, "amountInCents": { "type": "integer", "example": 2500 }, "shippingAddress": { "$ref": "#/components/schemas/Address" } } } }, "splits": { "type": "array", "description": "Distribui automaticamente parte do valor líquido para outras empresas PagzPay.\nA soma dos percentuais não pode ultrapassar 100%.\nO split é executado no momento em que o pagamento é confirmado.\n", "items": { "$ref": "#/components/schemas/SplitItem" } } } }, "examples": { "minimo": { "summary": "Cobrança mínima", "value": { "amountInCents": 5000, "customer": { "name": "João Silva", "email": "joao@exemplo.com", "documentType": "cpf", "document": "11122233344", "phone": "(11) 91234-5678" } } }, "completo": { "summary": "Cobrança com itens e webhook", "value": { "amountInCents": 15000, "description": "Pedido #1234", "postbackUrl": "https://exemplo.com.br/webhook", "customer": { "name": "Maria Souza", "email": "maria@exemplo.com", "documentType": "cpf", "document": "99988877766", "phone": "(21) 98765-4321" }, "items": [ { "title": "Produto A", "tangible": true, "quantity": 2, "amountInCents": 5000 }, { "title": "Produto B", "tangible": true, "quantity": 1, "amountInCents": 5000 } ], "trackingParameters": { "src": "facebook", "sck": "sck-exemplo", "utm_source": "meta", "utm_campaign": "campanha-exemplo", "utm_medium": "cpc", "utm_content": "criativo-1", "utm_term": "tenis", "fbclid": "fbclid-exemplo", "gclid": "gclid-exemplo", "ttclid": "ttclid-exemplo", "xcod": "xcod-exemplo" } } }, "comDadosDoProduto": { "summary": "Cobrança com dados do produto (compliance)", "value": { "amountInCents": 9790, "description": "Pedido #4321", "postbackUrl": "https://exemplo.com.br/webhook", "customer": { "name": "Ana Lima", "email": "ana@exemplo.com", "documentType": "cpf", "document": "12345678909", "phone": "(11) 98888-7777" }, "items": [ { "title": "Tênis Corrida Pro", "imageUrl": "https://minhaloja.com.br/img/tenis-corrida-pro.jpg", "tangible": true, "quantity": 1, "amountInCents": 9790 } ], "salesSiteUrl": "https://minhaloja.com.br", "checkoutUrl": "https://minhaloja.com.br/checkout/4321", "supportContact": { "email": "suporte@minhaloja.com.br", "whatsapp": "(11) 99999-0000" }, "trackingParameters": { "src": "facebook", "sck": "sck-exemplo", "utm_source": "meta", "utm_campaign": "campanha-exemplo", "utm_medium": "cpc", "utm_content": "criativo-1", "utm_term": "tenis", "fbclid": "fbclid-exemplo", "gclid": "gclid-exemplo", "ttclid": "ttclid-exemplo", "xcod": "xcod-exemplo" } } }, "comSplit": { "summary": "Cobrança com split entre parceiros", "value": { "amountInCents": 20000, "description": "Venda marketplace #5678", "postbackUrl": "https://exemplo.com.br/webhook", "customer": { "name": "Carlos Ferreira", "email": "carlos@exemplo.com", "documentType": "cpf", "document": "33344455566", "phone": "(31) 97777-8888" }, "splits": [ { "email": "parceiro1@empresa.com", "percentage": 30 }, { "email": "parceiro2@empresa.com", "percentage": 15 } ] } } } } } }, "responses": { "200": { "description": "QR Code PIX criado com sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixQRCodeResponse" }, "example": { "success": true, "message": "Transação criada com sucesso", "data": { "id": "trx_1a2b3c4d5e6f7g8h9i0j", "pix": { "emv": "00020126580014br.gov.bcb.pix0136...", "qrCode": "iVBORw0KGgo..." }, "status": "pending", "fees": 0 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/pix/in/qrcode/{transactionId}": { "get": { "tags": [ "PIX IN" ], "summary": "Consultar QR Code PIX", "operationId": "pix-in-get-qrcode", "description": "Consulta uma cobrança PIX criada anteriormente e retorna o **EMV** e a\n**imagem Base64** do QR Code.\n\nUse o `id` retornado na criação do QR Code.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "description": "ID da transação retornado na criação do QR Code", "schema": { "type": "string", "example": "trx_1a2b3c4d5e6f7g8h9i0j" } } ], "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X GET 'https://api.pagzpay.com/api/v1/pix/in/qrcode/trx_1a2b3c4d5e6f7g8h9i0j' \\\n -H 'Authorization: Bearer SEU_TOKEN_AQUI'\n" }, { "lang": "JavaScript", "label": "Node.js", "source": "const transactionId = 'trx_1a2b3c4d5e6f7g8h9i0j'\n\nconst response = await fetch(\n `https://api.pagzpay.com/api/v1/pix/in/qrcode/${transactionId}`,\n {\n headers: { 'Authorization': 'Bearer SEU_TOKEN_AQUI' }\n }\n)\n\nconst { data } = await response.json()\nconsole.log(data.pix.emv)\nconsole.log(data.pix.qrCode)\n" }, { "lang": "Python", "label": "Python", "source": "import requests\n\ntransaction_id = 'trx_1a2b3c4d5e6f7g8h9i0j'\nresponse = requests.get(\n f'https://api.pagzpay.com/api/v1/pix/in/qrcode/{transaction_id}',\n headers={'Authorization': 'Bearer SEU_TOKEN_AQUI'}\n)\n\ndata = response.json()['data']\nprint(data['pix']['emv'])\n" }, { "lang": "PHP", "label": "PHP", "source": "$transactionId = 'trx_1a2b3c4d5e6f7g8h9i0j';\n\n$ch = curl_init(\"https://api.pagzpay.com/api/v1/pix/in/qrcode/{$transactionId}\");\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\n 'Authorization: Bearer SEU_TOKEN_AQUI'\n]);\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n\n$response = json_decode(curl_exec($ch), true);\n" } ], "responses": { "200": { "description": "QR Code PIX encontrado com sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixQRCodeResponse" }, "example": { "success": true, "message": "QR Code PIX encontrado com sucesso", "data": { "id": "trx_1a2b3c4d5e6f7g8h9i0j", "pix": { "emv": "00020126580014br.gov.bcb.pix0136...", "qrCode": "iVBORw0KGgo..." }, "status": "pending", "fees": 0 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "QR Code PIX não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "NOT_FOUND", "message": "QR Code PIX não encontrado" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/card": { "post": { "tags": [ "Cartão" ], "summary": "Criar cobrança com cartão de crédito", "operationId": "card-create-charge", "description": "Cria uma cobrança com **cartão de crédito** (adquirente Pagar.me).\n\n**`customer.billingAddress` é obrigatório.** Prefira enviar `card.token` (tokenização\nPagar.me no browser) em vez de PAN completo.\n\n**Tokenização:** `POST https://api.pagar.me/core/v5/tokens?appId={PUBLIC_KEY}` com body\n`{ \"type\": \"card\", \"card\": { \"number\", \"holder_name\", \"exp_month\", \"exp_year\", \"cvv\" } }`.\nA resposta traz `{ \"id\": \"token_…\" }` para usar em `card.token`.\n\n**Consulta:** após criar, use `GET /api/v1/transactions/{id}` ou `GET .../status`.\n\n**Dados do produto (compliance):** opcionalmente envie `items[].title` e\n`items[].imageUrl` (nome e foto real do produto), `salesSiteUrl`, `checkoutUrl` e\n`supportContact`. São repassados à adquirente para análise de compliance — mesma\nregra do PIX (`POST /api/v1/pix/in/qrcode`).\n", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amountInCents", "customer", "card" ], "properties": { "amountInCents": { "type": "integer", "minimum": 100 }, "description": { "type": "string" }, "postbackUrl": { "type": "string", "format": "uri" }, "customer": { "type": "object" }, "card": { "type": "object" }, "items": { "type": "array", "description": "Itens do pedido (opcional) — use `title` e `imageUrl` para nome e foto do produto", "items": { "$ref": "#/components/schemas/Item" } }, "salesSiteUrl": { "$ref": "#/components/schemas/SalesSiteUrl" }, "checkoutUrl": { "$ref": "#/components/schemas/CheckoutUrl" }, "supportContact": { "$ref": "#/components/schemas/SupportContact" }, "trackingParameters": { "$ref": "#/components/schemas/TrackingParameters" } } }, "example": { "amountInCents": 5000, "postbackUrl": "https://exemplo.com.br/webhook", "trackingParameters": { "src": "facebook", "sck": "sck-exemplo", "utm_source": "meta", "utm_campaign": "campanha-exemplo", "utm_medium": "cpc", "utm_content": "criativo-1", "utm_term": "tenis", "fbclid": "fbclid-exemplo", "gclid": "gclid-exemplo", "ttclid": "ttclid-exemplo", "xcod": "xcod-exemplo" }, "customer": { "name": "João Silva", "email": "joao@exemplo.com", "documentType": "cpf", "document": "11122233344", "billingAddress": { "street": "Av. Paulista", "number": "1000", "neighborhood": "Bela Vista", "city": "São Paulo", "state": "SP", "zipCode": "01310100" } }, "card": { "token": "tok_xxxxxxxx", "holderName": "JOAO SILVA", "installments": 1 } } } } }, "responses": { "201": { "description": "Cobrança criada" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/transactions/{transactionId}": { "get": { "tags": [ "Transações", "Cartão" ], "summary": "Consultar transação (cartão, PIX, etc.)", "operationId": "transactions-get-by-id", "description": "Retorna os detalhes da cobrança pelo `id` retornado na criação\n(`POST /api/v1/card`, `POST /api/v1/pix/in/qrcode`, etc.).\n\nInclui `paymentMethod`, `status`, valores, taxas, cliente e dados PIX quando aplicável.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "description": "ID da transação (ex. retornado em `POST /api/v1/card`)", "schema": { "type": "string", "example": "trx_1a2b3c4d5e6f7g8h9i0j" } } ], "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X GET 'https://api.pagzpay.com/api/v1/transactions/trx_1a2b3c4d5e6f7g8h9i0j' \\\n -H 'Authorization: Bearer SEU_TOKEN_AQUI'\n" } ], "responses": { "200": { "description": "Transação encontrada", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "paymentMethod": { "type": "string", "example": "credit_card" }, "status": { "type": "string", "example": "paid" }, "amount": { "type": "number" }, "netAmount": { "type": "number" }, "fees": { "type": "number" } } } } }, "example": { "success": true, "data": { "id": "trx_1a2b3c4d5e6f7g8h9i0j", "paymentMethod": "credit_card", "status": "paid", "amount": 10000, "netAmount": 9500, "fees": 500 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/transactions/{transactionId}/status": { "get": { "tags": [ "Transações", "Cartão" ], "summary": "Consultar status da transação", "operationId": "transactions-get-status", "description": "Retorna apenas o status — útil para **polling** após `POST /api/v1/card`\n(ex. aguardar sair de `pending`).\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string", "example": "trx_1a2b3c4d5e6f7g8h9i0j" } } ], "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X GET 'https://api.pagzpay.com/api/v1/transactions/trx_1a2b3c4d5e6f7g8h9i0j/status' \\\n -H 'Authorization: Bearer SEU_TOKEN_AQUI'\n" } ], "responses": { "200": { "description": "Status retornado", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "string", "example": "paid" } } }, "example": { "success": true, "status": "paid" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Transação não encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/pix/out/pixkey": { "post": { "tags": [ "PIX OUT" ], "summary": "Enviar transferência PIX", "operationId": "pix-out-send-pixkey", "description": "Realiza uma **transferência PIX** para qualquer chave PIX.\n\n### Tipos de chave PIX aceitos\n\n| Tipo | Formato | Exemplo |\n|------|---------|---------|\n| CPF | Apenas dígitos | `11122233344` |\n| CNPJ | Apenas dígitos | `11222333000181` |\n| E-mail | Email válido | `destino@email.com` |\n| Telefone | Com `+55` | `+5511999999999` |\n| Chave aleatória | UUID | `123e4567-e89b-12d3-a456-426614174000` |\n\n### Idempotência obrigatória\n\nEnvie um **UUID único** no header `x-idempotency-key` para cada nova transferência.\nSe a requisição falhar, reuse o mesmo UUID no retry — isso garante que a transferência\nnão seja duplicada.\n\n```\nx-idempotency-key: 550e8400-e29b-41d4-a716-446655440000\n```\n\n> ⚠️ A transferência é irreversível após processamento. Verifique a chave PIX antes de enviar.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "x-idempotency-key", "in": "header", "required": true, "description": "UUID único para garantir que a transferência não seja duplicada em caso de retry", "schema": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://api.pagzpay.com/api/v1/pix/out/pixkey' \\\n -H 'Authorization: Bearer SEU_TOKEN_AQUI' \\\n -H 'Content-Type: application/json' \\\n -H 'x-idempotency-key: 550e8400-e29b-41d4-a716-446655440000' \\\n -d '{\n \"pixKey\": \"fornecedor@exemplo.com\",\n \"amount\": 10000,\n \"currency\": \"BRL\",\n \"description\": \"Pagamento de fornecedor\",\n \"postbackUrl\": \"https://exemplo.com.br/webhook/pix-out\"\n }'\n" }, { "lang": "JavaScript", "label": "Node.js", "source": "const { randomUUID } = require('crypto')\n\nconst response = await fetch('https://api.pagzpay.com/api/v1/pix/out/pixkey', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer SEU_TOKEN_AQUI',\n 'Content-Type': 'application/json',\n 'x-idempotency-key': randomUUID()\n },\n body: JSON.stringify({\n pixKey: 'fornecedor@exemplo.com',\n amount: 10000,\n currency: 'BRL',\n description: 'Pagamento de fornecedor',\n postbackUrl: 'https://exemplo.com.br/webhook/pix-out'\n })\n})\n\nconst { data } = await response.json()\nconsole.log(data.status) // 'queued'\n" }, { "lang": "Python", "label": "Python", "source": "import requests\nimport uuid\n\nresponse = requests.post(\n 'https://api.pagzpay.com/api/v1/pix/out/pixkey',\n headers={\n 'Authorization': 'Bearer SEU_TOKEN_AQUI',\n 'Content-Type': 'application/json',\n 'x-idempotency-key': str(uuid.uuid4())\n },\n json={\n 'pixKey': 'fornecedor@exemplo.com',\n 'amount': 10000,\n 'currency': 'BRL',\n 'description': 'Pagamento de fornecedor',\n 'postbackUrl': 'https://exemplo.com.br/webhook/pix-out'\n }\n)\n\ndata = response.json()['data']\nprint(data['status'])\n" }, { "lang": "PHP", "label": "PHP", "source": "$payload = json_encode([\n 'pixKey' => 'fornecedor@exemplo.com',\n 'amount' => 10000,\n 'currency' => 'BRL',\n 'description' => 'Pagamento de fornecedor',\n 'postbackUrl' => 'https://exemplo.com.br/webhook/pix-out'\n]);\n\n$ch = curl_init('https://api.pagzpay.com/api/v1/pix/out/pixkey');\ncurl_setopt($ch, CURLOPT_POST, true);\ncurl_setopt($ch, CURLOPT_POSTFIELDS, $payload);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\n 'Authorization: Bearer SEU_TOKEN_AQUI',\n 'Content-Type: application/json',\n 'x-idempotency-key: ' . sprintf('%04x%04x-%04x-%04x-%04x-%04x%04x%04x',\n mt_rand(0, 0xffff), mt_rand(0, 0xffff), mt_rand(0, 0xffff),\n mt_rand(0, 0x0fff) | 0x4000, mt_rand(0, 0x3fff) | 0x8000,\n mt_rand(0, 0xffff), mt_rand(0, 0xffff), mt_rand(0, 0xffff))\n]);\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n\n$response = json_decode(curl_exec($ch), true);\n" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pixKey", "amount" ], "properties": { "pixKey": { "type": "string", "description": "Chave PIX de destino (CPF, CNPJ, email, telefone ou chave aleatória)", "example": "fornecedor@exemplo.com" }, "amount": { "type": "integer", "minimum": 1, "description": "Valor da transferência em centavos", "example": 10000 }, "currency": { "type": "string", "description": "Moeda (apenas BRL aceito)", "default": "BRL", "example": "BRL" }, "description": { "type": "string", "maxLength": 140, "description": "Descrição da transferência", "example": "Pagamento de fornecedor" }, "postbackUrl": { "type": "string", "format": "uri", "description": "URL para receber notificação de status da transferência", "example": "https://exemplo.com.br/webhook/pix-out" } } }, "examples": { "email": { "summary": "Transferência para e-mail", "value": { "pixKey": "fornecedor@exemplo.com", "amount": 10000, "currency": "BRL", "description": "Pagamento de fornecedor", "postbackUrl": "https://exemplo.com.br/webhook/pix-out" } }, "cpf": { "summary": "Transferência para CPF", "value": { "pixKey": "11122233344", "amount": 5000, "currency": "BRL", "description": "Reembolso" } }, "chaveAleatoria": { "summary": "Chave aleatória", "value": { "pixKey": "123e4567-e89b-12d3-a456-426614174000", "amount": 25000, "currency": "BRL" } } } } } }, "responses": { "200": { "description": "Transferência iniciada com sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixTransferResponse" }, "example": { "success": true, "message": "Transferência criada com sucesso", "data": { "id": "transfer_abc123def456", "status": "pending", "amount": 10000, "netAmount": 10000, "fees": 0, "pixKey": "fornecedor@exemplo.com" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Chave de idempotência já utilizada — operação não duplicada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "IDEMPOTENCY_CONFLICT", "message": "Esta chave de idempotência já foi utilizada" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/pix/out/pixkey/{transferId}": { "get": { "tags": [ "PIX OUT" ], "summary": "Consultar transferência PIX", "operationId": "pix-out-get-pixkey", "description": "Consulta uma transferência PIX criada anteriormente e retorna o status atual.\n\nUse o `id` retornado na criação da transferência PIX OUT.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "transferId", "in": "path", "required": true, "description": "ID da transferência retornado na criação do PIX OUT", "schema": { "type": "string", "example": "transfer_abc123def456" } } ], "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X GET 'https://api.pagzpay.com/api/v1/pix/out/pixkey/transfer_abc123def456' \\\n -H 'Authorization: Bearer SEU_TOKEN_AQUI'\n" }, { "lang": "JavaScript", "label": "Node.js", "source": "const transferId = 'transfer_abc123def456'\n\nconst response = await fetch(\n `https://api.pagzpay.com/api/v1/pix/out/pixkey/${transferId}`,\n {\n headers: { 'Authorization': 'Bearer SEU_TOKEN_AQUI' }\n }\n)\n\nconst { data } = await response.json()\nconsole.log(data.status)\n" }, { "lang": "Python", "label": "Python", "source": "import requests\n\ntransfer_id = 'transfer_abc123def456'\nresponse = requests.get(\n f'https://api.pagzpay.com/api/v1/pix/out/pixkey/{transfer_id}',\n headers={'Authorization': 'Bearer SEU_TOKEN_AQUI'}\n)\n\ndata = response.json()['data']\nprint(data['status'])\n" }, { "lang": "PHP", "label": "PHP", "source": "$transferId = 'transfer_abc123def456';\n\n$ch = curl_init(\"https://api.pagzpay.com/api/v1/pix/out/pixkey/{$transferId}\");\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\n 'Authorization: Bearer SEU_TOKEN_AQUI'\n]);\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n\n$response = json_decode(curl_exec($ch), true);\n" } ], "responses": { "200": { "description": "Transferência PIX encontrada com sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PixTransferGetResponse" }, "example": { "success": true, "data": { "id": "transfer_abc123def456", "status": "completed", "amount": 10000, "netAmount": 10000, "fees": 0, "pixKey": "fornecedor@exemplo.com", "endToEndId": "E1234567820241231000000000000002", "createdAt": "2026-01-15T13:44:25.838Z", "updatedAt": "2026-01-15T13:45:10.120Z", "processedAt": "2026-01-15T13:45:10.120Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Transferência PIX não encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "NOT_FOUND", "message": "Transferência não encontrada" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/balance": { "get": { "tags": [ "Saldo" ], "summary": "Consultar saldo", "operationId": "balance-get", "description": "Retorna os **saldos atuais** das carteiras da empresa autenticada.\n\n### Carteiras retornadas\n\n| Campo | Descrição |\n|-------|-----------|\n| `pix.balance` | Saldo livre disponível para uso e transferências |\n| `pixBlocked.balance` | Saldo bloqueado por cautelar ou MED (indisponível) |\n| `reserve.balance` | Valor em reserva (aguardando liquidação) |\n\n> Os valores são retornados em **reais** como string com 2 casas decimais (ex: `\"150.00\"`).\n", "security": [ { "bearerAuth": [] } ], "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X GET 'https://api.pagzpay.com/api/v1/balance' \\\n -H 'Authorization: Bearer SEU_TOKEN_AQUI'\n" }, { "lang": "JavaScript", "label": "Node.js", "source": "const response = await fetch('https://api.pagzpay.com/api/v1/balance', {\n headers: { 'Authorization': 'Bearer SEU_TOKEN_AQUI' }\n})\n\nconst { data } = await response.json()\nconsole.log('Saldo disponível: R$', data.pix.balance)\nconsole.log('Bloqueado: R$', data.pixBlocked.balance)\nconsole.log('Reserva: R$', data.reserve.balance)\n" }, { "lang": "Python", "label": "Python", "source": "import requests\n\nresponse = requests.get(\n 'https://api.pagzpay.com/api/v1/balance',\n headers={'Authorization': 'Bearer SEU_TOKEN_AQUI'}\n)\n\ndata = response.json()['data']\nprint(f\"Saldo disponivel: R$ {data['pix']['balance']}\")\nprint(f\"Bloqueado: R$ {data['pixBlocked']['balance']}\")\nprint(f\"Reserva: R$ {data['reserve']['balance']}\")\n" }, { "lang": "PHP", "label": "PHP", "source": "$ch = curl_init('https://api.pagzpay.com/api/v1/balance');\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\n 'Authorization: Bearer SEU_TOKEN_AQUI'\n]);\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n\n$response = json_decode(curl_exec($ch), true);\n$saldo = $response['data']['pix']['balance'];\necho \"Saldo disponivel: R$ {$saldo}\";\n" } ], "responses": { "200": { "description": "Saldos retornados com sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "pix": { "type": "object", "properties": { "balance": { "type": "string", "description": "Saldo disponivel em reais (2 casas decimais)", "example": "1250.00" } } }, "pixBlocked": { "type": "object", "properties": { "balance": { "type": "string", "description": "Saldo bloqueado em reais (cautelar ou MED)", "example": "0.00" } } }, "reserve": { "type": "object", "properties": { "balance": { "type": "string", "description": "Saldo em reserva em reais", "example": "300.00" } } } } } } }, "example": { "success": true, "data": { "pix": { "balance": "1250.00" }, "pixBlocked": { "balance": "0.00" }, "reserve": { "balance": "300.00" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/docs/webhooks/pagamento": { "get": { "tags": [ "Formato dos Webhooks" ], "summary": "Pagamento", "operationId": "webhook-format-payment", "description": "Exemplo do payload enviado nos callbacks de **PIX IN**.\n\nEste item é apenas referência de formato. Não é uma rota da API.\n\nEventos relacionados:\n\n| Evento | Quando é enviado |\n|--------|------------------|\n| `transaction_created` | Cobrança PIX criada |\n| `transaction_paid` | Cobrança PIX paga |\n| `transaction_refunded` | Cobrança PIX estornada |\n| `transaction_updated` | Cobrança PIX atualizada com outro status |\n| `infraction` | Infração/MED criada ou atualizada para uma cobrança PIX |\n", "responses": { "200": { "description": "Exemplo de payload de callback de pagamento", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPaymentPayload" }, "example": { "id": "8d0f3b8f-5c2f-4a10-8dd6-8bbf5e9b1d11", "type": "transaction", "event": "transaction_paid", "scope": "user", "transaction": { "id": "transaction_abc123", "amount": 5000, "status": "paid", "pix": { "endToEndId": "E1234567820241231000000000000001", "payerInfo": { "name": "Joao Silva", "document": "11122233344" } } } } } } } } } }, "/docs/webhooks/transferencia": { "get": { "tags": [ "Formato dos Webhooks" ], "summary": "Transferência", "operationId": "webhook-format-transfer", "description": "Exemplo do payload enviado nos callbacks de **PIX OUT**.\n\nEste item é apenas referência de formato. Não é uma rota da API.\n\nEventos relacionados:\n\n| Evento | Quando é enviado |\n|--------|------------------|\n| `transfer_created` | Transferência PIX criada |\n| `transfer_updated` | Transferência PIX atualizada com outro status |\n| `transfer_completed` | Transferência PIX concluída |\n| `transfer_canceled` | Transferência PIX cancelada ou recusada |\n", "responses": { "200": { "description": "Exemplo de payload de callback de transferência", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTransferPayload" }, "example": { "id": "5f9e0c94-60a4-4df8-bb81-7f6efc6f61b0", "type": "transfer", "event": "transfer_completed", "scope": "user", "transfer": { "id": "transfer_abc123", "amount": 10000, "status": "paid", "pix": { "endToEndId": "E1234567820241231000000000000002", "creditorAccount": { "name": "Fornecedor Exemplo", "document": "12345678000199" } } } } } } } } } }, "/api/v1/webhook": { "get": { "tags": [ "Webhooks" ], "summary": "Listar webhooks", "operationId": "webhooks-list", "description": "Retorna todos os **webhooks configurados** na sua conta.\n", "security": [ { "bearerAuth": [] } ], "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X GET 'https://api.pagzpay.com/api/v1/webhook' \\\n -H 'Authorization: Bearer SEU_TOKEN_AQUI'\n" }, { "lang": "JavaScript", "label": "Node.js", "source": "const response = await fetch('https://api.pagzpay.com/api/v1/webhook', {\n headers: { 'Authorization': 'Bearer SEU_TOKEN_AQUI' }\n})\nconst { data } = await response.json()\nconst { webhooks } = data\n" }, { "lang": "Python", "label": "Python", "source": "import requests\n\nresponse = requests.get(\n 'https://api.pagzpay.com/api/v1/webhook',\n headers={'Authorization': 'Bearer SEU_TOKEN_AQUI'}\n)\nwebhooks = response.json()['data']['webhooks']\n" }, { "lang": "PHP", "label": "PHP", "source": "$ch = curl_init('https://api.pagzpay.com/api/v1/webhook');\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\n 'Authorization: Bearer SEU_TOKEN_AQUI'\n]);\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n$response = json_decode(curl_exec($ch), true);\n$webhooks = $response['data']['webhooks'];\n" } ], "responses": { "200": { "description": "Lista de webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "pagination": { "type": "object", "additionalProperties": true } } } } }, "example": { "success": true, "data": { "webhooks": [ { "id": 123, "name": "Meu webhook", "url": "https://exemplo.com.br/webhook", "events": [ "transaction_paid", "transfer_completed" ], "isActive": true, "signatureSecret": "secret_abc123", "mtlsCapable": false, "createdAt": "2024-12-31T12:00:00Z" } ], "pagination": { "offset": 0, "pageSize": 10, "totalCount": 1, "currentPage": 1, "totalPages": 1, "hasNext": false, "hasPrevious": false } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Webhooks" ], "summary": "Criar webhook", "operationId": "webhooks-create", "description": "Configura um novo **endpoint de webhook** para receber notificações de eventos.\n\n### Como validar a autenticidade\n\nO PagzPay envia um `signatureSecret` na criação. Use-o para validar\nque as notificações são legítimas via HMAC-SHA256:\n\n```javascript\nconst crypto = require('crypto')\n\nfunction isValidPagzPayWebhook(payload, signature, secret) {\n const [timestampPart, signaturePart] = signature.split(',')\n const timestamp = timestampPart.replace('t=', '')\n const receivedSignature = signaturePart.replace('v1=', '')\n\n const expected = crypto\n .createHmac('sha256', secret)\n .update(`${timestamp}.${JSON.stringify(payload)}`)\n .digest('hex')\n\n return expected === receivedSignature\n}\n```\n", "security": [ { "bearerAuth": [] } ], "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://api.pagzpay.com/api/v1/webhook' \\\n -H 'Authorization: Bearer SEU_TOKEN_AQUI' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"url\": \"https://exemplo.com.br/webhook\",\n \"events\": [\"transaction_paid\", \"transfer_completed\"]\n }'\n" }, { "lang": "JavaScript", "label": "Node.js", "source": "const response = await fetch('https://api.pagzpay.com/api/v1/webhook', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer SEU_TOKEN_AQUI',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n url: 'https://exemplo.com.br/webhook',\n events: ['transaction_paid', 'transfer_completed']\n })\n})\n\nconst webhook = await response.json()\n" }, { "lang": "Python", "label": "Python", "source": "import requests\n\nresponse = requests.post(\n 'https://api.pagzpay.com/api/v1/webhook',\n headers={\n 'Authorization': 'Bearer SEU_TOKEN_AQUI',\n 'Content-Type': 'application/json'\n },\n json={\n 'url': 'https://exemplo.com.br/webhook',\n 'events': ['transaction_paid', 'transfer_completed']\n }\n)\n" }, { "lang": "PHP", "label": "PHP", "source": "$payload = json_encode([\n 'url' => 'https://exemplo.com.br/webhook',\n 'events' => ['transaction_paid', 'transfer_completed']\n]);\n\n$ch = curl_init('https://api.pagzpay.com/api/v1/webhook');\ncurl_setopt($ch, CURLOPT_POST, true);\ncurl_setopt($ch, CURLOPT_POSTFIELDS, $payload);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\n 'Authorization: Bearer SEU_TOKEN_AQUI',\n 'Content-Type: application/json'\n]);\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\n$response = json_decode(curl_exec($ch), true);\n" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "description": "URL HTTPS que receberá as notificações via POST", "example": "https://exemplo.com.br/webhook" }, "events": { "type": "array", "minItems": 1, "description": "Eventos que devem disparar a notificação", "items": { "type": "string", "enum": [ "transaction_created", "transaction_paid", "transaction_refunded", "transaction_updated", "transfer_created", "transfer_updated", "transfer_completed", "transfer_canceled", "infraction" ] }, "example": [ "transaction_paid", "transfer_completed" ] } } }, "examples": { "basico": { "summary": "Apenas pagamentos confirmados", "value": { "url": "https://exemplo.com.br/webhook", "events": [ "transaction_paid" ] } }, "completo": { "summary": "Todos os eventos de transação e transferência", "value": { "url": "https://exemplo.com.br/webhook", "events": [ "transaction_created", "transaction_paid", "transaction_refunded", "transaction_updated", "transfer_created", "transfer_updated", "transfer_completed", "transfer_canceled", "infraction" ] } } } } } }, "responses": { "201": { "description": "Webhook criado com sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Webhook" } } }, "example": { "success": true, "data": { "id": 123, "name": "Meu webhook", "url": "https://exemplo.com.br/webhook", "events": [ "transaction_paid", "transfer_completed" ], "isActive": true, "signatureSecret": "secret_abc123", "mtlsCapable": false, "createdAt": "2024-12-31T12:00:00Z" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/webhook/{id}": { "delete": { "tags": [ "Webhooks" ], "summary": "Deletar webhook", "operationId": "webhooks-delete", "description": "Remove um webhook permanentemente pelo seu ID.\n\n> ⚠️ Esta ação é **irreversível**. O webhook deixará de receber notificações imediatamente.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID do webhook a ser removido", "schema": { "type": "string", "example": "webhook_abc123xyz" } } ], "x-codeSamples": [ { "lang": "Shell", "label": "cURL", "source": "curl -X DELETE 'https://api.pagzpay.com/api/v1/webhook/webhook_abc123xyz' \\\n -H 'Authorization: Bearer SEU_TOKEN_AQUI'\n" }, { "lang": "JavaScript", "label": "Node.js", "source": "const webhookId = 'webhook_abc123xyz'\n\nconst response = await fetch(\n `https://api.pagzpay.com/api/v1/webhook/${webhookId}`,\n {\n method: 'DELETE',\n headers: { 'Authorization': 'Bearer SEU_TOKEN_AQUI' }\n }\n)\n\nif (response.status === 200) {\n console.log('Webhook removido com sucesso')\n}\n" }, { "lang": "Python", "label": "Python", "source": "import requests\n\nwebhook_id = 'webhook_abc123xyz'\n\nresponse = requests.delete(\n f'https://api.pagzpay.com/api/v1/webhook/{webhook_id}',\n headers={'Authorization': 'Bearer SEU_TOKEN_AQUI'}\n)\n\nif response.status_code == 200:\n print('Webhook removido com sucesso')\n" }, { "lang": "PHP", "label": "PHP", "source": "$webhookId = 'webhook_abc123xyz';\n\n$ch = curl_init(\"https://api.pagzpay.com/api/v1/webhook/{$webhookId}\");\ncurl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\n 'Authorization: Bearer SEU_TOKEN_AQUI'\n]);\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_exec($ch);\n\n$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);\nif ($httpCode === 200) {\n echo 'Webhook removido com sucesso';\n}\n" } ], "responses": { "200": { "description": "Webhook removido com sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Webhook não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "NOT_FOUND", "message": "Webhook não encontrado" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic", "description": "Autenticação Basic para obter o token JWT.\nUse `client_id` como usuário e `client_secret` como senha, codificados em Base64.\n" }, "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Token JWT obtido via `POST /api/auth`.\nEnvie no header: `Authorization: Bearer `\n" } }, "responses": { "Unauthorized": { "description": "Token ausente, inválido ou expirado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "UNAUTHORIZED", "message": "Token de autenticação inválido ou expirado" } } } }, "BadRequest": { "description": "Dados inválidos na requisição", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "INVALID_REQUEST", "message": "O campo 'amountInCents' é obrigatório" } } } }, "RateLimited": { "description": "Limite de requisições excedido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "RATE_LIMITED", "message": "Muitas requisições. Tente novamente em alguns minutos." } } } } }, "schemas": { "Customer": { "type": "object", "required": [ "documentType", "document" ], "properties": { "name": { "type": "string", "description": "Nome completo do cliente", "example": "João Silva" }, "email": { "type": "string", "format": "email", "description": "E-mail do cliente", "example": "joao@exemplo.com" }, "documentType": { "type": "string", "enum": [ "cpf", "cnpj" ], "description": "Tipo do documento", "example": "cpf" }, "document": { "type": "string", "description": "CPF (apenas dígitos) ou CNPJ (apenas dígitos)", "example": "11122233344" }, "phone": { "type": "string", "description": "Telefone do cliente com DDD", "example": "(11) 91234-5678" }, "billingAddress": { "$ref": "#/components/schemas/Address" } } }, "TrackingParameters": { "type": "object", "description": "Parâmetros de campanha para atribuição (Utmify, Meta, Google, etc.).\nObrigatório na prática quando a cobrança é criada via API e você usa integração Utmify.\nNome do campo no JSON deve ser exatamente trackingParameters (não tracking ou utms).\n", "properties": { "utm_source": { "type": "string", "nullable": true }, "utm_campaign": { "type": "string", "nullable": true }, "utm_medium": { "type": "string", "nullable": true }, "utm_content": { "type": "string", "nullable": true }, "utm_term": { "type": "string", "nullable": true }, "src": { "type": "string", "nullable": true }, "sck": { "type": "string", "nullable": true }, "xcod": { "type": "string", "nullable": true }, "fbclid": { "type": "string", "nullable": true }, "gclid": { "type": "string", "nullable": true }, "ttclid": { "type": "string", "nullable": true } }, "example": { "src": "facebook", "sck": "sck-exemplo", "utm_source": "meta", "utm_campaign": "campanha-exemplo", "utm_medium": "cpc", "utm_content": "criativo-1", "utm_term": "tenis", "fbclid": "fbclid-exemplo", "gclid": "gclid-exemplo", "ttclid": "ttclid-exemplo", "xcod": "xcod-exemplo" } }, "Item": { "type": "object", "required": [ "title", "tangible", "quantity", "amountInCents" ], "properties": { "title": { "type": "string", "description": "Nome real do produto ou serviço", "example": "Produto A" }, "imageUrl": { "type": "string", "format": "uri", "description": "URL pública da foto real do produto (opcional, compliance)", "example": "https://minhaloja.com.br/img/produto-a.jpg" }, "tangible": { "type": "boolean", "description": "Indica se o item é físico", "example": true }, "quantity": { "type": "integer", "minimum": 1, "description": "Quantidade do item", "example": 2 }, "amountInCents": { "type": "integer", "description": "Valor do item em centavos", "example": 2500 }, "shippingAddress": { "$ref": "#/components/schemas/Address" } } }, "SalesSiteUrl": { "type": "string", "format": "uri", "description": "URL do site onde o produto é vendido (opcional, compliance)", "example": "https://minhaloja.com.br" }, "CheckoutUrl": { "type": "string", "format": "uri", "description": "URL da página de checkout onde o pagamento foi feito (opcional, compliance)", "example": "https://minhaloja.com.br/checkout/4321" }, "SupportContact": { "type": "object", "description": "Contato de suporte do vendedor (opcional, compliance). Informe os canais que preferir —\ntodos os campos são opcionais.\n", "properties": { "email": { "type": "string", "format": "email", "example": "suporte@minhaloja.com.br" }, "phone": { "type": "string", "description": "Telefone com DDD (8 a 20 caracteres)", "example": "(11) 3333-4444" }, "whatsapp": { "type": "string", "description": "WhatsApp com DDD (8 a 20 caracteres)", "example": "(11) 99999-0000" }, "url": { "type": "string", "format": "uri", "description": "Site ou página de ajuda", "example": "https://minhaloja.com.br/ajuda" } } }, "Address": { "type": "object", "properties": { "street": { "type": "string", "description": "Logradouro", "example": "Rua Exemplo" }, "number": { "type": "string", "description": "Número", "example": "100" }, "neighborhood": { "type": "string", "description": "Bairro", "example": "Centro" }, "city": { "type": "string", "description": "Cidade", "example": "São Paulo" }, "state": { "type": "string", "description": "UF do estado", "example": "SP" }, "zipCode": { "type": "string", "description": "CEP", "example": "00000-000" } } }, "PixQRCodeResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Transação criada com sucesso" }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "ID único da transação", "example": "trx_1a2b3c4d5e6f7g8h9i0j" }, "pix": { "type": "object", "properties": { "emv": { "type": "string", "description": "Código EMV (copia e cola) para pagamento PIX", "example": "00020126580014br.gov.bcb.pix..." }, "qrCode": { "type": "string", "description": "Imagem do QR Code em Base64", "example": "iVBORw0KGgo..." } } }, "status": { "type": "string", "enum": [ "pending", "paid", "canceled", "refunded" ], "description": "Status da transação", "example": "pending" }, "fees": { "type": "integer", "description": "Taxa cobrada em centavos", "example": 0 } } } } }, "PixTransferResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Transferência criada com sucesso" }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "ID único da transferência", "example": "transfer_abc123def456" }, "status": { "type": "string", "enum": [ "queued", "processing", "pending", "pending_analysis", "banking_processing", "banking_refused", "banking_error", "manual_analysis", "completed", "canceled", "refused", "error" ], "description": "Status da transferência", "example": "pending" }, "amount": { "type": "integer", "description": "Valor total em centavos", "example": 10000 }, "netAmount": { "type": "integer", "description": "Valor líquido após taxas em centavos", "example": 10000 }, "fees": { "type": "integer", "description": "Taxas cobradas em centavos", "example": 0 }, "pixKey": { "type": "string", "description": "Chave PIX de destino", "example": "fornecedor@exemplo.com" } } } } }, "PixTransferGetResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "ID único da transferência", "example": "transfer_abc123def456" }, "status": { "type": "string", "enum": [ "pending", "queued", "processing", "pending_analysis", "banking_processing", "banking_refused", "banking_error", "manual_analysis", "canceled", "refused", "completed", "error" ], "description": "Status da transferência", "example": "completed" }, "amount": { "type": "integer", "description": "Valor total em centavos", "example": 10000 }, "netAmount": { "type": "integer", "description": "Valor líquido após taxas em centavos", "example": 10000 }, "fees": { "type": "integer", "description": "Taxas cobradas em centavos", "example": 0 }, "pixKey": { "type": "string", "description": "Chave PIX de destino", "example": "fornecedor@exemplo.com" }, "endToEndId": { "type": "string", "nullable": true, "description": "Identificador fim a fim do PIX quando disponível", "example": "E1234567820241231000000000000002" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-01-15T13:44:25.838Z" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-01-15T13:45:10.120Z" }, "processedAt": { "type": "string", "format": "date-time", "nullable": true, "example": "2026-01-15T13:45:10.120Z" } } } } }, "Webhook": { "type": "object", "properties": { "id": { "type": "integer", "description": "ID único do webhook", "example": 123 }, "name": { "type": "string", "nullable": true, "description": "Nome do webhook", "example": "Meu webhook" }, "url": { "type": "string", "format": "uri", "description": "URL que recebe as notificações", "example": "https://exemplo.com.br/webhook" }, "events": { "type": "array", "description": "Lista de eventos configurados", "items": { "type": "string" }, "example": [ "transaction_paid", "transfer_completed" ] }, "isActive": { "type": "boolean", "description": "Se o webhook está ativo", "example": true }, "signatureSecret": { "type": "string", "nullable": true, "description": "Secret usado para validar a assinatura dos callbacks", "example": "secret_abc123" }, "mtlsCapable": { "type": "boolean", "nullable": true, "example": false }, "createdAt": { "type": "string", "format": "date-time", "description": "Data e hora de criação", "example": "2024-12-31T12:00:00Z" } } }, "WebhookPaymentPayload": { "type": "object", "description": "Payload enviado nos callbacks de PIX IN.", "properties": { "id": { "type": "string", "description": "ID único do disparo do webhook", "example": "8d0f3b8f-5c2f-4a10-8dd6-8bbf5e9b1d11" }, "type": { "type": "string", "enum": [ "transaction" ], "example": "transaction" }, "event": { "type": "string", "enum": [ "transaction_created", "transaction_paid", "transaction_refunded", "transaction_updated" ], "example": "transaction_paid" }, "scope": { "type": "string", "enum": [ "user", "postback", "system" ], "example": "user" }, "transaction": { "type": "object", "properties": { "id": { "type": "string", "example": "transaction_abc123" }, "amount": { "type": "integer", "description": "Valor em centavos", "example": 5000 }, "status": { "type": "string", "example": "paid" }, "pix": { "type": "object", "nullable": true, "properties": { "endToEndId": { "type": "string", "nullable": true, "example": "E1234567820241231000000000000001" }, "payerInfo": { "type": "object", "nullable": true, "additionalProperties": true } } } } } } }, "WebhookTransferPayload": { "type": "object", "description": "Payload enviado nos callbacks de PIX OUT.", "properties": { "id": { "type": "string", "description": "ID único do disparo do webhook", "example": "5f9e0c94-60a4-4df8-bb81-7f6efc6f61b0" }, "type": { "type": "string", "enum": [ "transfer" ], "example": "transfer" }, "event": { "type": "string", "enum": [ "transfer_created", "transfer_updated", "transfer_completed", "transfer_canceled" ], "example": "transfer_completed" }, "scope": { "type": "string", "enum": [ "user", "postback", "system" ], "example": "user" }, "transfer": { "type": "object", "properties": { "id": { "type": "string", "example": "transfer_abc123" }, "amount": { "type": "integer", "description": "Valor em centavos", "example": 10000 }, "status": { "type": "string", "example": "paid" }, "pix": { "type": "object", "properties": { "endToEndId": { "type": "string", "nullable": true, "example": "E1234567820241231000000000000002" }, "creditorAccount": { "type": "object", "nullable": true, "additionalProperties": true } } } } } } }, "SplitItem": { "type": "object", "required": [ "email", "percentage" ], "properties": { "email": { "type": "string", "format": "email", "description": "E-mail da empresa PagzPay que receberá o split (deve ter conta ativa)", "example": "parceiro@empresa.com" }, "percentage": { "type": "number", "minimum": 0.01, "maximum": 100, "description": "Percentual do valor liquido a distribuir (0.01 a 100).\nA soma de todos os splits nao pode ultrapassar 100%.\n", "example": 30 } } }, "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Código do erro", "example": "INVALID_REQUEST" }, "message": { "type": "string", "description": "Descrição do erro", "example": "O campo 'amount' é obrigatório" }, "details": { "type": "object", "description": "Detalhes adicionais do erro", "additionalProperties": true } } } } } }