Documentação legada do Pagar.me v5
Entendendo os conceitos
A integração com Pix através do Pagar.me requer que o lojista tenha conta transacional em um dos participantes diretos do arranjo Pix, para que seja possível repassar os dados na requisição e criação do QR Code.
O que é o Pix?
O Pix é um sistema desenvolvido pelo Banco Central que disponibiliza uma forma de realizar pagamentos, transferências e recebimentos instantâneos.
Nesse arranjo, o Sistema de Pagamentos Instantâneos (SPI) é a infraestrutura centralizada para liquidação entre instituições — onde transferências de moedas eletrônicas ocorrem 24×7 em tempo real.
Para o varejo, o Pix traz:
- ✅ Aumento de eficiência do mercado
- ✅ Mais segurança
- ✅ Experiência mais fluida para o cliente
- ✅ Custo significativamente menor que cartão
O que são as chaves Pix?
Uma transferência tradicional entre instituições financeiras se baseia em um conjunto de dados de identificação (banco, agência, conta + dados pessoais). Pensando em uma experiência mais simples, o Pix introduziu o Diretório de Identificadores de Contas Transacionais (DICT).
A proposta do DICT é atrelar todos os dados de conta a algumas "chaves fortes" mais comuns:
- 📱 Telefone
- 📄 CPF / CNPJ
- 🔑 Chave aleatória (UUID gerada pelo sistema)
No caso da Pagar.me, a instituição financeira do arranjo é o próprio Pagar.me — você não precisa cadastrar chave manualmente. Será usada uma chave aleatória atrelada à sua conta, sem dados pessoais expostos. Essa chave é criada assim que o contrato/aditivo Pix é firmado.
Como funciona uma compra com Pix
Lojista → Pagar.me → BACEN/SPI → Banco do pagador → Pagador
↑ ↓
└──── Webhook charge.paid ←── Confirmação ←─────────┘
- Pagador recebe o QR Code com dados bancários do recebedor e detalhes do produto
- Pagador abre o app do banco (PSP), escaneia o QR e aceita a transferência
- PSP realiza a transferência via SPI
- Recebedor é notificado via webhook que o valor foi creditado
Como criar uma venda com Pix no Pagar.me
Para criar uma transação com Pix na v5, o lojista informa o payment_method = pix na criação do pedido + a expires_in.
curl -X POST https://api.stone.com.br/core/v5/orders \
-H "Authorization: Basic $(echo -n $API_KEY: | base64)" \
-d '{
"items": [{ "amount": 1990, "description": "Pedido 1042", "quantity": 1 }],
"customer": { "name": "Maria", "email": "maria@x.com" },
"payments": [{
"payment_method": "pix",
"pix": { "expires_in": 3600 }
}]
}'
A resposta inclui:
{
"charges": [{
"last_transaction": {
"qr_code": "00020126360014BR.GOV.BCB.PIX...",
"qr_code_url": "https://api.stone.com.br/.../pix.png",
"expires_at": "2026-04-28T15:32:11Z"
}
}]
}
Posteriormente, o webhook order.paid informa que o pedido foi concluído.
Migração para a API Unificada
Jornada: Cobrar um cliente
Etapa 22 de 22