Objeto cobrança
O objeto cobrança é o mesmo na criação, na consulta, na listagem e dentro de dados dos webhooks de venda. Esta página é a referência única dele.
Exemplo
{
"id": "8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f",
"status": "pendente",
"valor": 9700,
"taxa": 371,
"liquido": 9329,
"descricao": "Curso de Marketing",
"pix_copia_e_cola": "00020101021226...",
"link_pagamento": "https://app.grinnypay.com/pix?c=8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f",
"cliente": { "nome": "Carlos Silva", "email": "[email protected]" },
"expira_em": "2026-10-15T14:45:00-03:00",
"pago_em": null,
"criado_em": "2026-10-15T14:30:00-03:00",
"referencia": "pedido-1042",
"livemode": true
}Campos
idtextoIdentificador da cobrança: 32 caracteres, letras de a a f e números. Não muda nunca.
statustextoUm de pendente, pago, expirado, falhou, med, contestado, reembolsado. Veja Status.
valorinteiroValor cobrado, em centavos. R$ 97,00 é 9700.
taxainteiroTaxa da Grinny Pay sobre a venda, em centavos.
liquidointeiroO que entra no seu saldo: valor menos taxa e menos a comissão de afiliado, se houver. Em centavos.
descricaotextoDescrição que o comprador vê.
pix_copia_e_colatexto ou nullCódigo Pix (QR Code e "copia e cola"). Só vem enquanto o status é pendente; depois é null.
link_pagamentotextoPágina pronta de pagamento, com QR Code e contador.
clienteobjetonome e email de quem paga. O CPF e o celular que você manda na criação não voltam.
expira_emdataAté quando o Pix pode ser pago (ISO 8601 com fuso).
pago_emdata ou nullQuando o pagamento foi confirmado. null se ainda não foi pago.
criado_emdataQuando a cobrança foi criada.
livemodebooleanotrue em cobrança de produção, false em cobrança criada com a chave de teste.
referenciatexto ou nullO código seu que você mandou ao criar (até 100 caracteres). null se não mandou.
Ciclo de vida
Uma cobrança nasce pendente e termina de um dos jeitos abaixo. Os eventos de webhook correspondentes estão em Webhooks de venda.
| De | Para | Quando | Webhook |
|---|---|---|---|
pendente | pago | O banco confirmou o Pix. | venda.aprovada |
pendente | expirado | Passou o prazo (expira_em). | venda.expirada |
pago | med | O banco do comprador abriu um MED. | med.aberto |
med | pago | MED ganho. | med.encerrado |
med | contestado | MED perdido. | med.encerrado e venda.contestada |
pago | reembolsado | Devolução ao comprador. | venda.reembolsada |
Guarde o id da cobrança junto com o seu pedido. É ele que liga o pedido ao pagamento em consultas, webhooks e MED.