Cobranças Pix

Gere a cobrança, mostre o Pix copia e cola ao cliente e libere o pedido quando o pagamento chegar.

POSTCriar cobrança Pix/transactions/payment GETConsultar cobrança/transactions/payment/{paymentId}POSTEstornar cobrança/transactions/payment/{paymentId}/refund

Criar a cobrança

POST /transactions/payment, escopo PAYMENT_WRITE. Obrigatórios: amount em centavos, method: "PIX" e o cliente, com customer.name e customer.document (CPF ou CNPJ).

Mande o número do seu pedido em externalRef: repetir a chamada com o mesmo externalRef devolve a mesma cobrança em vez de criar outra.

curl -X POST https://api.hub.payzu.com.br/api/v1/transactions/payment \
  -H "Authorization: Bearer $PAYZU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1500,
    "method": "PIX",
    "description": "Pedido 4821",
    "externalRef": "pedido-4821",
    "metadata": { "pedido": "4821", "canal": "checkout-web" },
    "customer": {
      "name": "Maria Souza",
      "document": "52998224725",
      "email": "maria.souza@exemplo.com"
    }
  }'

const res = await fetch('https://api.hub.payzu.com.br/api/v1/transactions/payment', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 1500,
    method: 'PIX',
    description: 'Pedido 4821',
    externalRef: 'pedido-4821',
    metadata: { pedido: '4821', canal: 'checkout-web' },
    customer: {
      name: 'Maria Souza',
      document: '52998224725',
      email: 'maria.souza@exemplo.com',
    },
  }),
});
const cobranca = await res.json();

description aparece para quem paga. metadata volta nos webhooks da cobrança. callbackUrl recebe os webhooks desta cobrança e exige o segredo de callback. Todos os campos estão em Criar cobrança Pix.

Mostrar o Pix ao cliente

A resposta (201) traz o Pix copia e cola em pix.qrCodeText. Mostre-o ao cliente e gere o QR Code a partir dele.

{
  "id": "hubp-20261005K7Q2M9XB4T127431",
  "status": "PENDING",
  "amount": 1500,
  "serviceFee": 105,
  "netAmount": 1395,
  "externalRef": "pedido-4821",
  "pix": {
    "qrCodeText": "00020126580014br.gov.bcb.pix0136b3c7e9a2-4f1d-4c8a-9e2b-7d5f6a8c1e03520400005303986540515.005802BR5912LOJA EXEMPLO6009SAO PAULO62070503***63041EC4"
  }
}

serviceFee é a tarifa, descontada do valor: numa cobrança de R$ 15,00 com tarifa de R$ 1,05, entram R$ 13,95 (netAmount).

Liberar o pedido no pagamento

Quando o cliente paga, chega o webhook PAYMENT_PAID, com o seu externalRef e o metadata da criação. Libere o pedido aí. Se a cobrança vencer sem pagamento, chega PAYMENT_EXPIRED.

Para conferir a qualquer momento, consulte GET /transactions/payment/{paymentId}, com o id da resposta ou o paymentId do webhook.

Status da cobrança

Status	Significado
`PENDING`	Aguardando pagamento.
`PAID`	Paga. O valor líquido está na conta.
`REFUNDED`	Estornada por inteiro.
`EXPIRED`	Venceu sem pagamento. Não volta a `PENDING`.

Depois do pagamento, payer mostra quem de fato pagou, com o CPF mascarado ou o CNPJ formatado, e pix.conciliationId traz o end-to-end do Pix. customer continua sendo o cliente que você informou.

Pedido repetido

Você manda	A API responde
O mesmo `externalRef` com os mesmos dados	`200` com a cobrança que já existe.
O mesmo `externalRef` com algum dado diferente	`409` `PAYMENT_EXTERNAL_REF_MISMATCH`. Os campos diferentes vêm em `details.fields`.
O mesmo `externalRef` enquanto a primeira ainda é processada	`412` `PAYMENT_CREATION_IN_FLIGHT`. Repita em alguns segundos.

A comparação usa valor, método, descrição, metadata e os dados do cliente. callbackUrl e ipAddress ficam de fora. Não ponha em metadata nada que mude a cada tentativa.

Consultar e comprovar

Listar: GET /transactions/payment, com filtros de status, período, externalRef e cliente.
Comprovante: GET /transactions/payment/{paymentId}/receipt devolve o PDF em base64, para cobrança paga ou estornada.

Estornar

POST /transactions/payment/{paymentId}/refund, escopo REFUND. Mande amount para devolver parte; sem amount, devolve tudo o que resta.

{ "amount": 1000 }

A tarifa de estorno é cobrada à parte, além do valor devolvido.
O valor e a tarifa saem do saldo disponível na hora do pedido e voltam se o estorno falhar.
Um estorno por vez em cada cobrança. Estornos parciais podem se repetir até o valor total.
Com contestação MED aberta na cobrança, o estorno é recusado (REFUND_INFRACTION_OPEN).
O resultado chega pelos webhooks REFUND_COMPLETED ou REFUND_FAILED.
A rota não aceita Idempotency-Key. Num 502, o estorno pode ter saído: consulte a cobrança antes de pedir de novo.

Limites

O valor fica entre o mínimo e o máximo da conta e precisa ser maior que a tarifa. Veja os seus em limites.
Até 60 cobranças por minuto por credencial e 120 por conta. Acima disso, a API responde 429 com Retry-After.
Estornos contam no mesmo limite de saques: 5 por minuto por credencial e 10 por conta.

As recusas de cada rota, com o code, estão em Criar cobrança Pix e Estornar cobrança.

Cobranças Pix

Nesta página