VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Gateways de pagamento

Pix

Gera o QR Code do Pix de um pedido e acompanha o pagamento.

Pix é o pagamento instantâneo brasileiro: o cliente escaneia um QR Code, ou cola um código "copia e cola", no app do banco, e o dinheiro cai na hora. Estas três rotas geram o Pix de um pedido e deixam o cliente (logado ou não) acompanhar a confirmação. Todas exigem o módulo pix-payments.

Gerar um Pix

Gera um Pix dinâmico para o pedido e devolve o QR Code e o código "copia e cola". Funciona também para visitante (sem token): quem tem o order_id consegue cobrar. O valor vem sempre do total do pedido; o campo amount, se enviado, é ignorado. Exige o módulo pix-payments.

POST/api/v1/storefront/pix/paymentsPública

Gera o QR Code e o copia e cola do Pix de um pedido

Corpo da requisição

order_iduuidobrigatório
Pedido a cobrar.
descriptionstring
Texto exibido no app do banco do cliente (até 80 caracteres).
merchant_namestring
Nome do recebedor exibido no QR code (até 25 caracteres). Só vale no Pix local; se omitido, usa a configuração da loja.
merchant_citystring
Cidade do recebedor exibida no QR code (até 15 caracteres). Só vale no Pix local; se omitida, usa a configuração da loja.
pix_keystring
Chave Pix do recebedor. Só vale no Pix local; se omitida, usa a chave padrão da loja. Prefira omitir.
customer_namestring
Nome completo. Exigido pelos gateways (Pagar.me, Getnet); ignorado no Pix local.
customer_emailstring
E-mail do pagador. Mesma regra.
customer_cpfstring
CPF (11 dígitos). CPF ou CNPJ, não os dois.
customer_cnpjstring
CNPJ (14 dígitos).

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/storefront/pix/payments" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
    "description": "Pedido 1042",
    "customer_name": "Maria Souza",
    "customer_email": "maria.souza@example.com",
    "customer_cpf": "12345678909"
  }'

Resposta

201Pix gerado
json
{
  "txid": "PIX7F3A9C21B84",
  "payload": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890520400005303986540522.505802BR5913MINHA LOJA6009SAO PAULO62070503***6304ABCD",
  "qr_code_b64": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAABlBMVEUAAAD///+l2Z/dAAAA...",
  "amount": 22500,
  "expires_at": "2026-10-11T15:32:11Z",
  "status": "pending",
  "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "pix_key": "",
  "provider": "pagarme",
  "gateway_charge_id": "ch_Kx9QzR2mVn3LdY7a",
  "created_at": "2026-10-11T15:02:11Z",
  "updated_at": "2026-10-11T15:02:11Z",
  "refund_status": "none",
  "refunded_amount": 0
}

Campos da resposta

txidstring
Identificador do Pix: PIX seguido de 11 caracteres hexadecimais maiúsculos.
statusstring
pendingpaidexpiredfailed
Estado do Pix. expired cancela o pedido se ele ainda não estava pago.
expires_atstring
Até quando o código vale (RFC 3339). O prazo é configurado pela loja (30 minutos por padrão).
paid_atstring
Quando foi pago. Ausente enquanto pendente.
providerstring
localpagarmegetnet
Quem gerou o QR Code.
qr_code_b64string
Imagem PNG do QR Code em base64 (sem prefixo data:). Use como data:image/png;base64,....
payloadstring
O Pix "copia e cola" (BR Code EMV).
amountinteger
Valor, em centavos.
order_iduuid
O pedido.
pix_keystring
Chave Pix do recebedor. Vazia quando um gateway gerencia a chave.
gateway_charge_idstring
Id da cobrança no gateway, quando há.
end_to_end_idstring
Id de liquidação do Banco Central. Só depois de pago.
refund_statusstring
nonemanual_pendingrefunded
Estado do reembolso. manual_pending: no Pix local, a loja devolve à mão.
refunded_amountinteger
Total reembolsado, em centavos.
created_at, updated_atstring
Datas de criação e atualização (RFC 3339).

Erros

StatusQuandoCorpo de exemplo
400Corpo inválido ou order_id ausente.{"error":"order_id is required"}
403O módulo pix-payments está desligado nesta loja.{"error":"module_disabled","module":"pix-payments"}
404Pedido inexistente.{"error":"order not found"}
422O pedido não tem total a pagar.{"error":"order has no payable total"}
500Falha ao gerar o Pix (por exemplo, chave Pix não configurada no Pix local, ou erro do gateway).{"error":"pix: ..."}
502Não foi possível carregar o pedido.{"error":"could not load the order for this payment"}
Pix vencido cancela o pedido

Uma rotina da plataforma marca como expired o Pix pendente cujo prazo acabou e cancela o pedido (a menos que ele já conste como pago). Se o cliente quiser pagar depois do prazo, gere um novo Pix; o pedido, porém, pode já ter sido cancelado.

Consultar um Pix

Devolve o estado de um Pix e os dados para exibir o QR Code de novo. Consulte a cada poucos segundos (5 s é razoável, com limite de tempo) até paid, expired ou failed. Sem login: o txid é o identificador.

GET/api/v1/storefront/pix/payments/{txid}Pública

Estado e QR Code de um Pix pelo txid

Parâmetros de caminho

txidstringobrigatório
O txid devolvido ao gerar.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/pix/payments/PIX7F3A9C21B84"

Resposta

200Estado do Pix
json
{
  "txid": "PIX7F3A9C21B84",
  "status": "paid",
  "expires_at": "2026-10-11T15:32:11Z",
  "paid_at": "2026-10-11T15:04:40Z",
  "provider": "pagarme",
  "qr_code_b64": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAABlBMVEUAAAD///+l2Z/dAAAA...",
  "payload": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890520400005303986540522.505802BR5913MINHA LOJA6009SAO PAULO62070503***6304ABCD",
  "amount": 22500
}

Campos da resposta

txidstring
Identificador do Pix: PIX seguido de 11 caracteres hexadecimais maiúsculos.
statusstring
pendingpaidexpiredfailed
Estado do Pix. expired cancela o pedido se ele ainda não estava pago.
expires_atstring
Até quando o código vale (RFC 3339). O prazo é configurado pela loja (30 minutos por padrão).
paid_atstring
Quando foi pago. Ausente enquanto pendente.
providerstring
localpagarmegetnet
Quem gerou o QR Code.
qr_code_b64string
Imagem PNG do QR Code em base64 (sem prefixo data:). Use como data:image/png;base64,....
payloadstring
O Pix "copia e cola" (BR Code EMV).
amountinteger
Valor, em centavos.

Erros

StatusQuandoCorpo de exemplo
403O módulo pix-payments está desligado nesta loja.{"error":"module_disabled","module":"pix-payments"}
404txid desconhecido.{"error":"payment not found"}

Pix de um pedido

Devolve o Pix mais recente do pedido, no mesmo formato de Consultar um Pix. Existe para a página de confirmação do pedido, que conhece o orderId mas não guardou o txid.

GET/api/v1/storefront/pix/payments/by-order/{orderId}Pública

O Pix mais recente de um pedido

Parâmetros de caminho

orderIduuidobrigatório
Id do pedido.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/pix/payments/by-order/3f73310d-bfdd-4713-a664-305c08eda58b"

Resposta

200Estado do Pix
json
{
  "txid": "PIX7F3A9C21B84",
  "status": "paid",
  "expires_at": "2026-10-11T15:32:11Z",
  "paid_at": "2026-10-11T15:04:40Z",
  "provider": "pagarme",
  "qr_code_b64": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAABlBMVEUAAAD///+l2Z/dAAAA...",
  "payload": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890520400005303986540522.505802BR5913MINHA LOJA6009SAO PAULO62070503***6304ABCD",
  "amount": 22500
}

Campos da resposta

(corpo)object
Os mesmos campos de Consultar um Pix.

Erros

StatusQuandoCorpo de exemplo
403O módulo pix-payments está desligado nesta loja.{"error":"module_disabled","module":"pix-payments"}
404O pedido não tem Pix.{"error":"no pix payment found for this order"}
500orderId que não é um UUID válido.{"error":"o valor \"abc\" não é um uuid válido. ..."}
Quem confirma o pagamento

A confirmação chega à plataforma por webhook do banco ou do gateway, não por estas rotas. Elas só mostram o resultado: o status muda de pending para paid sozinho.

Veja também

  • Cobrar um pedido
  • Visão geral dos gateways
Anterior
Gateways de pagamento
Próxima
Pagar.me: cobrar e tokenizar
Nesta página
  • Gerar um Pix
  • Consultar um Pix
  • Pix de um pedido
  • Veja também