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.

{
  "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:

{
  "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

cURL

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"
  }'

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));

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()}")

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 [email protected].

Exemplo de Resposta de Erro:

{
  "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

post

This endpoint creates a new qrcode with the provided data.

Authorizations

Header parameters

User-AgentanyOptional

Client Identifier

Body

amountnumberRequired

customer_codestringOptional

descriptionstringRequired

expirationinteger · min: 60Required

notification_urlstringOptional

Responses

201

Created

application/json

Responsestring

400

Bad Request

application/json

401

Unauthorized

application/json

500

Internal Server Error

application/json

post

HTTPcURLJavaScriptPython

POST /v1/pix HTTP/1.1
Host: sandbox-api.pagou.com.br
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 182

{
  "amount": 1,
  "customer_code": "text",
  "description": "text",
  "expiration": 1,
  "metadata": [
    {
      "key": "text",
      "value": "text"
    }
  ],
  "notification_url": "text",
  "payer": {
    "document": "text",
    "name": "text"
  }
}

text

Create a QRCode with due

post

This endpoint creates a new qrcode due with the provided data.

Authorizations

Header parameters

User-AgentanyOptional

Client Identifier

Body

amountnumberRequired

descriptionstringRequired

due_datestringRequired

expirationinteger · min: 1Required

notification_urlstringOptional

Responses

201

Created

application/json

Responsestring

400

Bad Request

application/json

401

Unauthorized

application/json

500

Internal Server Error

application/json

post

HTTPcURLJavaScriptPython

POST /v1/pix/due HTTP/1.1
Host: sandbox-api.pagou.com.br
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 310

{
  "amount": 1,
  "description": "text",
  "discount": {
    "amount": 1,
    "limit_date": "text",
    "type": "fixed"
  },
  "due_date": "text",
  "expiration": 1,
  "fine": {
    "amount": 1,
    "type": "fixed"
  },
  "interest": {
    "amount": 1,
    "type": "fixed"
  },
  "metadata": [
    {
      "key": "text",
      "value": "text"
    }
  ],
  "notification_url": "text",
  "payer": {
    "document": "text",
    "name": "text"
  }
}

text