Pix Cobrança Pix

Como criar uma cobrança Pix e acompanhar o pagamento.

1. Crie a cobrança

curl -X POST https://api.paygrid.tech/v1/transactions \
  -H "X-Api-Key: sk_sua_chave" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-4211" \
  -d '{
    "workflowId": "22222222-2222-2222-2222-222222222222",
    "paymentMethod": "pix",
    "amount": 1990,
    "currency": "BRL",
    "reference": "pedido-4211",
    "customer": {
      "name": "João da Silva",
      "document": "12345678900",
      "phone": "+5511999999999"
    }
  }'

Pix é sempre 1x — sem parcelamento. E o pagador precisa ter nome, documento e telefone; sem isso o provedor recusa.

O workflowId é obrigatório: é o id do fluxo que processa a cobrança. Pegue-o no painel (menu Fluxos) ou em GET /v1/workflows.

2. Resposta e QR

A criação é assíncrona: a resposta (202) confirma que a cobrança foi enfileirada.

{
  "transactionId": "e01663ce-bef5-4cd2-9339-13b1ccebb77b",
  "trackingId": "3f2a9c1e-7b40-4d6a-9e21-5c8f0a1b2d3e",
  "status": "accepted",
  "messageId": "..."
}

Guarde o transactionId e busque o QR assim que o provedor responder (normalmente em poucos segundos):

curl https://api.paygrid.tech/v1/transactions/{transactionId} \
  -H "X-Api-Key: sk_sua_chave"

{
  "transactionId": "e01663ce-bef5-4cd2-9339-13b1ccebb77b",
  "status": "pending",
  "paymentId": "5183e61a-d1e4-5624-8674-536b05cc6f0e",
  "reference": "pedido-4211",
  "updatedAt": "2026-09-28T14:21:40Z",
  "qrCodePix": "00020126580014br.gov.bcb.pix...",
  "qrCodePixUrl": "https://..."
}

Exiba o qrCodePix (copia-e-cola) ou o qrCodePixUrl (imagem, quando o provedor devolve) para o pagador.

3. Validade do QR

O QR Pix vale 1 hora por padrão. Para outro prazo, envie pix_expires_in no metadata da cobrança, em segundos e como texto:

"metadata": {
  "pix_expires_in": "1800"
}

Hoje o pix_expires_in é respeitado na Pagar.me. Na InfoPago o QR vale sempre 1 hora. Valor ausente ou inválido também vale 1 hora.

O prazo efetivo aparece em pixExpiresAt ao consultar o pagamento (GET /v1/payments/{paymentId}).

Se o prazo passar sem pagamento, o Paygrid confere com o provedor e encerra a cobrança: o status vira cancelled, com failureReason: "pix_expirado", e sai o webhook payment.cancelled — em até cerca de 3 minutos após o vencimento. Se o provedor mostrar que o Pix foi pago, vale o pagamento (approved).

Pix pendente não se cancela. O provedor recusa o cancelamento de um Pix ainda não pago — a chamada a /cancel falha. Não é preciso fazer nada: ele expira sozinho no fim do prazo. Para desistir antes, use um prazo curto na criação.

4. Acompanhe o status

Consulte a qualquer momento:

curl https://api.paygrid.tech/v1/transactions/{transactionId} \
  -H "X-Api-Key: sk_sua_chave"

O status muda para approved quando o provedor confirma o pagamento. Em sandbox o Pix é aprovado automaticamente; em produção, o pagador precisa realmente pagar.

5. Receba a notificação

Configure webhooks para ser notificado do desfecho sem precisar consultar. Também é possível consultar a lista de pagamentos: GET /v1/payments.

curl "https://api.paygrid.tech/v1/payments?method=pix&from=2026-09-01T00:00:00-03:00&to=2026-09-30T23:59:59-03:00&limit=50" \
  -H "X-Api-Key: sk_sua_chave"

Vem do mais recente para o mais antigo, pela data de criação.
from e to (RFC 3339, cada um opcional) limitam o período pela data de criação.
Filtros: status, method (pix ou card) e provider (pagarme ou infopago).
limit vai de 1 a 100 (padrão 50).
A resposta traz payments e, se houver mais, next: repasse-o em cursor para a próxima página. É opaco — não monte nem altere.
Com filtros, uma página pode vir com menos itens que o limit (até vazia) e ainda trazer next. Pagine até o next sumir.
Data fora do RFC 3339, from depois de to, ou method/provider fora da lista devolvem 400.

Pronto: o pagador escaneia, o provedor confirma, o Paygrid atualiza o status e (se configurado) dispara o webhook.