# Criando um QRCode imediato ## Criando um QRCode imediato A criação de um QRCode na API do Pagou permite gerar um código Pix dinâmico para pagamentos instantâneos. ### Visão Geral Técnica O endpoint `POST`` ``/v1/pix` cria um QRCode para pagamento via Pix, com base nas informações fornecidas no payload JSON. O QRCode é identificado por um UUID único, retornado na resposta, e inclui um payload Pix e uma imagem em base64 para exibição. A operação é síncrona, retornando `201 Created` com os detalhes do QRCode, incluindo o código Pix (`payload.data`) e a imagem (`payload.image`). O pagamento pode ser monitorado via webhook (ex.: evento `ChargePaid`). **Especificações**: * **Método**: `POST` * **URL**: * Produção: `https://api.pagou.com.br/v1/pix` * Sandbox: `https://sandbox.api.pagou.com.br/v1/pix` * **Autenticação**: Cabeçalho `X-API-KEY` com chave do painel. * **Content-Type**: `application/json` * **Resposta**: Status `201 Created` com corpo JSON contendo os detalhes do QRCode. * **Erros**: `400 Bad Request`, `401 Unauthorized`, `500 Internal Server Error`. ### Cabeçalhos | Cabeçalho | Valor | Descrição | | -------------- | ------------------------ | ------------------------------------------------------------ | | `X-API-KEY` | `sua_chave_api` | Chave de autenticação. | | `Content-Type` | `application/json` | Formato JSON para o corpo da requisição. | | `User-Agent` | `NomeDaSuaAplicacao/1.0` | Identificador da aplicação (ex.: `MinhaLoja/1.0`, opcional). | ### Corpo da Requisição O payload deve conter informações do pagamento Pix, incluindo valor, descrição, pagador e configurações de notificação. ```json { "amount": 50.00, "description": "Payment for product or service", "expiration": 3600, "metadata": [ { "key": "order_id", "value": "ORD-2024-001" }, { "key": "reference", "value": "REF-12345" } ], "payer": { "name": "João Silva", "document": "12345678901" }, "notification_url": "https://your-webhook.com/notifications", "customer_code": "CUST-001" } ``` **Campos do Payload**: | Campo | Tipo | Obrigatório | Descrição | | ------------------ | ------ | -------------- | ------------------------------------------------------------------------ | | `amount` | number | Sim | Valor do pagamento em reais (ex.: 50.00 para R$ 50,00). | | `description` | string | Sim | Descrição do pagamento (máx. 255 caracteres). | | `expiration` | number | Sim | Tempo de expiração do QRCode em segundos (ex.: 3600 para 1 hora). | | `metadata` | array | Não | Pares chave-valor para dados adicionais (ex.: ID do pedido). | | `metadata[].key` | string | Sim (se usado) | Chave do metadado (ex.: `order_id`). | | `metadata[].value` | string | Sim (se usado) | Valor do metadado (ex.: `ORD-2024-001`). | | `payer` | object | Sim | Dados do pagador. | | `payer.name` | string | Sim | Nome completo do pagador (máx. 100 caracteres). | | `payer.document` | string | Sim | CPF (11 dígitos) ou CNPJ (14 dígitos). | | `notification_url` | string | Não | URL HTTPS para webhooks (ex.: `https://your-webhook.com/notifications`). | | `customer_code` | string | Não | Código interno do cliente (máx. 50 caracteres). | **Validações**: * `amount`: Valor mínimo de 5 (R$ 5,00). * `description`: Máximo de 255 caracteres. * `expiration`: Valor positivo, geralmente entre 60 (1 minuto) e 604800 (7 dias). * `payer.document`: Deve ser um CPF (11 dígitos) ou CNPJ (14 dígitos) válido. * `notification_url`: Deve ser uma URL HTTPS válida. ### Resposta * **Status**: `201 Created` * **Corpo**: JSON com os detalhes do QRCode, incluindo o UUID, payload Pix e imagem em base64. **Exemplo de Resposta**: ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "amount": 50.00, "description": "Payment for product or service", "expiration": 3600, "metadata": [ { "key": "order_id", "value": "ORD-2024-001" }, { "key": "reference", "value": "REF-12345" } ], "payer": { "name": "João Silva", "document": "12345678901" }, "notification_url": "https://your-webhook.com/notifications", "customer_code": "CUST-001", "payload": { "payload_id": 12345, "data": "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-426614174000520400005303986540550.005802BR5913JOAO SILVA6008SAO PAULO62070503***6304ABCD", "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEACAYAAABccqhmAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAAdgAAAHYBTnsmCAAAABl0RVh0U29mdHdhcmUAd3d3Lmlua3NjYXBlLm9yZ5vuPBoAAANCSURBVHic7doxAQAAAMKg9U9tCj+gAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA4GvAAAEAAQ==" } } ``` **Campos da Resposta**: | Campo | Tipo | Descrição | | -------------------- | ------ | ------------------------------------------------------------------- | | `id` | string | UUID único do QRCode (ex.: `550e8400-e29b-41d4-a716-446655440000`). | | `amount` | number | Valor do pagamento em reais (ex.: 50.00). | | `description` | string | Descrição do pagamento (máx. 255 caracteres). | | `expiration` | number | Tempo de expiração do QRCode em segundos (ex.: 3600). | | `metadata` | array | Pares chave-valor para dados adicionais. | | `metadata[].key` | string | Chave do metadado (ex.: `order_id`). | | `metadata[].value` | string | Valor do metadado (ex.: `ORD-2024-001`). | | `payer` | object | Dados do pagador. | | `payer.name` | string | Nome completo do pagador (máx. 100 caracteres). | | `payer.document` | string | CPF (11 dígitos) ou CNPJ (14 dígitos). | | `notification_url` | string | URL HTTPS para webhooks. | | `customer_code` | string | Código interno do cliente (máx. 50 caracteres). | | `payload` | object | Dados do QRCode Pix. | | `payload.payload_id` | number | ID interno do payload Pix. | | `payload.data` | string | Código Pix para pagamento (copia-e-cola). | | `payload.image` | string | Imagem do QRCode em base64 (formato `data:image/png;base64,...`). | ### Exemplos de Código #### cURL {% tabs %} {% tab title="cURL" %} ```bash curl -X POST https://sandbox.api.pagou.com.br/v1/pix \ -H "X-API-KEY: sua_chave_api" \ -H "Content-Type: application/json" \ -H "User-Agent: MinhaLoja/1.0" \ -H "Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000" \ -d '{ "amount": 50.00, "description": "Payment for product or service", "expiration": 3600, "metadata": [ { "key": "order_id", "value": "ORD-2024-001" }, { "key": "reference", "value": "REF-12345" } ], "payer": { "name": "João Silva", "document": "12345678901" }, "notification_url": "https://your-webhook.com/notifications", "customer_code": "CUST-001" }' ``` {% endtab %} {% tab title="JavaScript" %} ```javascript const fetch = require('node-fetch'); const { validate } = require('jsonschema'); // Esquema de validação do payload const schema = { type: 'object', required: ['amount', 'description', 'expiration', 'payer'], properties: { amount: { type: 'number', minimum: 0.01 }, description: { type: 'string', maxLength: 255 }, expiration: { type: 'integer', minimum: 300, maximum: 604800 }, metadata: { type: 'array', items: { type: 'object', required: ['key', 'value'], properties: { key: { type: 'string' }, value: { type: 'string' } } } }, payer: { type: 'object', required: ['name', 'document'], properties: { name: { type: 'string', maxLength: 100 }, document: { type: 'string', pattern: '^\\d{11}|\\d{14}$' } } }, notification_url: { type: 'string', format: 'uri' }, customer_code: { type: 'string', maxLength: 50 } } }; // Payload const payload = { amount: 50.00, description: 'Payment for product or service', expiration: 3600, metadata: [ { key: 'order_id', value: 'ORD-2024-001' }, { key: 'reference', value: 'REF-12345' } ], payer: { name: 'João Silva', document: '12345678901' }, notification_url: 'https://your-webhook.com/notifications', customer_code: 'CUST-001' }; // Validar payload const validation = validate(payload, schema); if (!validation.valid) { console.error('Erro de validação:', validation.errors); process.exit(1); } // Enviar requisição fetch('https://sandbox.api.pagou.com.br/v1/pix', { method: 'POST', headers: { 'X-API-KEY': 'sua_chave_api', 'Content-Type': 'application/json', 'User-Agent': 'MinhaLoja/1.0', 'Idempotency-Key': '123e4567-e89b-12d3-a456-426614174000' }, body: JSON.stringify(payload) }) .then(response => { if (!response.ok) { return response.json().then(err => { throw new Error(`Erro ${response.status}: ${err.error.message}`); }); } return response.json(); }) .then(data => { console.log(`QRCode ID: ${data.id}`); console.log(`Código Pix: ${data.payload.data}`); console.log(`Imagem Base64: ${data.payload.image}`); }) .catch(error => console.error('Erro na requisição:', error)); ``` {% endtab %} {% tab title="Python" %} ```python import requests from jsonschema import validate, ValidationError import re # Esquema de validação do payload schema = { "type": "object", "required": ["amount", "description", "expiration", "payer"], "properties": { "amount": {"type": "number", "minimum": 0.01}, "description": {"type": "string", "maxLength": 255}, "expiration": {"type": "integer", "minimum": 300, "maximum": 604800}, "metadata": { "type": "array", "items": { "type": "object", "required": ["key", "value"], "properties": { "key": {"type": "string"}, "value": {"type": "string"} } } }, "payer": { "type": "object", "required": ["name", "document"], "properties": { "name": {"type": "string", "maxLength": 100}, "document": {"type": "string", "pattern": "^\\d{11}|\\d{14}$"} } }, "notification_url": {"type": "string", "format": "uri"}, "customer_code": {"type": "string", "maxLength": 50} } } # Payload payload = { "amount": 50.00, "description": "Payment for product or service", "expiration": 3600, "metadata": [ {"key": "order_id", "value": "ORD-2024-001"}, {"key": "reference", "value": "REF-12345"} ], "payer": { "name": "João Silva", "document": "12345678901" }, "notification_url": "https://your-webhook.com/notifications", "customer_code": "CUST-001" } # Validar payload try: validate(instance=payload, schema=schema) except ValidationError as e: print(f"Erro de validação: {e}") exit(1) # Enviar requisição url = "https://sandbox.api.pagou.com.br/v1/pix" headers = { "X-API-KEY": "sua_chave_api", "Content-Type": "application/json", "User-Agent": "MinhaLoja/1.0", "Idempotency-Key": "123e4567-e89b-12d3-a456-426614174000" } try: response = requests.post(url, json=payload, headers=headers) response.raise_for_status() data = response.json() print(f"QRCode ID: {data['id']}") print(f"Código Pix: {data['payload']['data']}") print(f"Imagem Base64: {data['payload']['image']}") except requests.RequestException as e: print(f"Erro na requisição: {e}") if e.response: print(f"Detalhes: {e.response.json()}") ``` {% endtab %} {% endtabs %} ### Tratamento de Erros | Código HTTP | Descrição | Possível Causa | Solução | | ----------- | --------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | `400` | Bad Request | Payload inválido (ex.: CPF inválido, `amount` < 5, `expiration` fora do intervalo). | Validar dados antes de enviar (use schema fornecido). | | `401` | Unauthorized | `X-API-KEY` inválido ou ausente. | Verificar chave.. | | `500` | Internal Server Error | Erro interno da API. | Tentar novamente e contatar [contato@pagou.com.br](mailto:suporte@pagou.com.br). | **Exemplo de Resposta de Erro**: ```json { "error": "amount must be greater than or equal to 0.01" } ``` ### Mapa de Status do Pix Cada QRCode Pix com vencimento possui um status que reflete seu estado no ciclo de vida. Os status possíveis, conforme definido na API do Pagou, são: | Status | Valor Numérico | Descrição | | ---------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `StatusEmpty` | 1 | Estado inicial transitório, indicando que o QRCode foi criado, mas ainda não está ativo (ex.: aguardando validação interna). | | `StatusActive` | 2 | QRCode ativo, pronto para pagamento, com código Pix e imagem disponíveis. | | `StatusCanceled` | 3 | QRCode cancelado, não mais válido para pagamento (ex.: por solicitação ou expiração). | | `StatusCompleted` | 4 | QRCode pago pelo cliente, com liquidação confirmada. | | `StatusRefunded` | 5 | QRCode pago, mas reembolsado ao cliente (ex.: após devolução do produto). | **Transições de Status**: * `StatusEmpty` → `StatusActive`: Após validação interna bem-sucedida (geralmente imediata). * `StatusActive` → `StatusCompleted`: Quando o pagamento é confirmado (notificado via webhook `QRCodeCompleted`). * `StatusActive` → `StatusCanceled`: Após solicitação de cancelamento (ex.: `DELETE`` ``/v1/pix/{id}`) ou expiração do QRCode (definida por `due_date` e `expiration`). * `StatusCompleted` → `StatusRefunded`: Após processamento de reembolso (se aplicável). * `StatusCanceled`, `StatusRefunded`: Estados finais, sem transições adicionais. ### Boas Práticas Técnicas * **Validação de Dados**: Use esquemas JSON (como nos exemplos) para validar o payload antes de enviar, evitando erros `400`. * **Segurança**: Armazene `X-API-KEY` em variáveis de ambiente e use HTTPS para todas as requisições. * **Webhooks**: Configure o `notification_url` para receber o evento `QRCodeCompleted` ou `QRCodeRefunded` quando o pagamento for confirmado ou estornado. * **Testes no Sandbox**: Use `https://sandbox.api.pagou.com.br/v1/pix` para simular criação de QRCodes sem custos reais. * **Monitoramento**: Registre todas as requisições e respostas (incluindo `id`, `payload.data` e `payload.image`) em logs para auditoria e depuração. ## Create a QRCode > This endpoint creates a new qrcode with the provided data. ```json {"openapi":"3.1.1","info":{"title":"Pagou API","version":"0.0.1"},"servers":[{"url":"https://sandbox-api.pagou.com.br"}],"security":[{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"XApiKeyAuth":{"type":"apiKey","name":"X-API-KEY","in":"header"}},"schemas":{"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}}},"models.CreateQRCodeRequest":{"type":"object","required":["amount","description","expiration","payer"],"properties":{"amount":{"type":"number"},"customer_code":{"type":"string"},"description":{"type":"string"},"expiration":{"type":"integer","minimum":60},"metadata":{"type":"array","items":{"$ref":"#/components/schemas/models.QRCodeMetadata"}},"notification_url":{"type":"string"},"payer":{"$ref":"#/components/schemas/models.QRCodePayer"}}},"models.QRCodeMetadata":{"type":"object","required":["key","value"],"properties":{"key":{"type":"string"},"value":{"type":"string"}}},"models.QRCodePayer":{"type":"object","required":["document","name"],"properties":{"document":{"type":"string"},"name":{"type":"string"}}}}},"paths":{"/v1/pix":{"post":{"description":"This endpoint creates a new qrcode with the provided data.","tags":["pix"],"summary":"Create a QRCode","parameters":[{"type":"string","description":"Client Identifier","name":"User-Agent","in":"header"}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.CreateQRCodeRequest"}}},"description":"QRCode data","required":true}}}}} ``` ## Create a QRCode with due > This endpoint creates a new qrcode due with the provided data. ```json {"openapi":"3.1.1","info":{"title":"Pagou API","version":"0.0.1"},"servers":[{"url":"https://sandbox-api.pagou.com.br"}],"security":[{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"XApiKeyAuth":{"type":"apiKey","name":"X-API-KEY","in":"header"}},"schemas":{"models.ErrorResponse":{"type":"object","properties":{"error":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}}},"models.CreateQRCodeDueRequest":{"type":"object","required":["amount","description","due_date","expiration","payer"],"properties":{"amount":{"type":"number"},"description":{"type":"string"},"discount":{"$ref":"#/components/schemas/models.DiscountQRCodeDueInfo"},"due_date":{"type":"string"},"expiration":{"type":"integer","minimum":1},"fine":{"$ref":"#/components/schemas/models.QRCodeDueInfo"},"interest":{"$ref":"#/components/schemas/models.QRCodeDueInfo"},"metadata":{"type":"array","items":{"$ref":"#/components/schemas/models.QRCodeMetadata"}},"notification_url":{"type":"string"},"payer":{"$ref":"#/components/schemas/models.QRCodePayer"}}},"models.DiscountQRCodeDueInfo":{"type":"object","required":["amount","limit_date","type"],"properties":{"amount":{"type":"number"},"limit_date":{"type":"string"},"type":{"description":"TODO: check it after","type":"string","enum":["fixed","percentage","fixed_calendar_days","fixed_working_days","percentage_calendar_days","percentage_working_days","percentage_month_calendar_days","percentage_month_working_days","percentage_year_calendar_days","percentage_year_working_days"]}}},"models.QRCodeDueInfo":{"type":"object","required":["amount","type"],"properties":{"amount":{"type":"number"},"type":{"description":"TODO: check it after","type":"string","enum":["fixed","percentage","fixed_calendar_days","fixed_working_days","percentage_calendar_days","percentage_working_days","percentage_month_calendar_days","percentage_month_working_days","percentage_year_calendar_days","percentage_year_working_days"]}}},"models.QRCodeMetadata":{"type":"object","required":["key","value"],"properties":{"key":{"type":"string"},"value":{"type":"string"}}},"models.QRCodePayer":{"type":"object","required":["document","name"],"properties":{"document":{"type":"string"},"name":{"type":"string"}}}}},"paths":{"/v1/pix/due":{"post":{"description":"This endpoint creates a new qrcode due with the provided data.","tags":["pix"],"summary":"Create a QRCode with due","parameters":[{"type":"string","description":"Client Identifier","name":"User-Agent","in":"header"}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"string"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/models.CreateQRCodeDueRequest"}}},"description":"QRCode data","required":true}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.pagou.com.br/integracao-com-a-api/meio-de-pagamento-pix/criando-um-qrcode-imediato.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.