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

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

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

Estado inicial transitório, indicando que o QRCode foi criado, mas ainda não está ativo (ex.: aguardando validação interna).

StatusActive

QRCode ativo, pronto para pagamento, com código Pix e imagem disponíveis.

StatusCanceled

QRCode cancelado, não mais válido para pagamento (ex.: por solicitação ou expiração).

StatusCompleted

QRCode pago pelo cliente, com liquidação confirmada.

StatusRefunded

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

X-API-KEYstringRequired

Header parameters

User-AgentanyOptional

Client Identifier

Body

amountnumberRequired

customer_codestringOptional

descriptionstringRequired

expirationinteger · min: 60Required

notification_urlstringOptional

Responses

201

Created

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

500

Internal Server Error

application/json

post

/v1/pix

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

X-API-KEYstringRequired

Header parameters

User-AgentanyOptional

Client Identifier

Body

amountnumberRequired

descriptionstringRequired

due_datestringRequired

expirationinteger · min: 1Required

notification_urlstringOptional

Responses

201

Created

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

500

Internal Server Error

application/json

post

/v1/pix/due

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

PreviousMeio de Pagamento: Pix NextCriando um QRCode com vencimento

Last updated 6 months ago

hashtagCriando um QRCode imediato

hashtagVisão Geral Técnica

hashtagCabeçalhos

hashtagCorpo da Requisição

hashtagResposta

hashtagExemplos de Código

hashtagcURL

hashtagTratamento de Erros

hashtagMapa de Status do Pix

hashtagBoas Práticas Técnicas

hashtagCreate a QRCode

hashtagCreate a QRCode with due