Status de fatura e depósito

Leia o estado da fatura ou depósito por requisições GET. Os webhooks avisam você das mudanças automaticamente.

Leia uma fatura ou depósito

Use o id retornado quando você criou a fatura ou o depósito:

curl 'https://platform.invoise.me/api/v1/shops/{shop_id}/issuances/{issuance_id}' \
  -H 'Authorization: Bearer ivk_...'

Campos relevantes de uma resposta de exemplo (outros campos omitidos):

{
  "id": "f06b8a31-19c7-4687-ade3-1c09466d2751",
  "kind": "invoice",
  "status": "funded",
  "amount": "10000000",
  "received": "10000000",
  "token_decimals": 6,
  "expires_at": "2026-10-19T10:00:00Z",
  "cancelled_at": null,
  "disabled_at": null,
  "payout_tx_hash": null
}

Ambos os valores são strings de números inteiros em unidades base. Este exemplo significa que 10 tokens chegaram, mas nenhuma transação de repasse confirmada é mostrada ainda.

Interprete uma fatura

status	O que fazer
registering	Aguarde um address não vazio. Não derive um você mesmo.
open	Continue aguardando. received pode mostrar um pagamento parcial.
funded	Fundos confirmados suficientes estão disponíveis para a liquidação.
settled	A fatura foi fechada na blockchain.
reconciling	Aguarde a reconciliação; não trate como um pagamento bem-sucedido.

Verifique também cancelled_at. É um timestamp ou null, não um valor de status. É definido quando você cancela a fatura, quando uma fatura não paga passa do expires_at, ou quando a equipe do Invoise bloqueia o lojista; o webhook invoice.cancelled diferencia esses casos por data.reason. O cancelamento oculta a página de pagamento, mas não interrompe os fundos recebidos nem a liquidação. Decida explicitamente como seu negócio trata uma fatura paga e cancelada.

funded significa pagamento recebido, não repasse concluído. settled registra o fechamento da fatura. Para a contabilização completa do repasse, use payout.confirmed; payout_tx_hash identifica a última transferência de saída confirmada ao destinatário, quando disponível.

Se você receber transfer.reverted, o Invoise está informando a reversão de uma transferência recebida específica na rede. Identifique-a por chain_event.reference_event_id, leia o estado atual da fatura e ajuste seu registro dessa transferência uma única vez. Veja Webhooks para o formato do evento.

Acompanhe depósitos

Um endereço de depósito é reutilizável. Ele pode voltar a open após um repasse, então não espere que ele se torne settled permanentemente.

received é o total acumulado de dinheiro recebido confirmado, não o saldo restante. Um repasse não é subtraído dele. Ele pode diminuir quando uma transferência é revertida. Credite cada pagamento recebido apenas uma vez; os webhooks são úteis para isso porque cada evento tem um ID estável.

disabled_at controla a disponibilidade da página de pagamento. Desativar um depósito não interrompe o monitoramento do seu endereço.

Liste faturas e depósitos

curl 'https://platform.invoise.me/api/v1/shops/{shop_id}/payments?limit=50' \
  -H 'Authorization: Bearer ivk_...'

Com limit (1–100), a resposta é {"items":[...],"next_cursor":"..."}. Envie cursor para a próxima página até que next_cursor esteja vazio. Sem parâmetros de paginação, o endpoint retorna um array limitado; não é o histórico completo.

A listagem aceita os filtros kind, status e q. Seu filtro status=paid seleciona funded e settled; paid não é um status de issuance retornado pelo endpoint de detalhe.

O campo transfers do endpoint de detalhe contém apenas as dez entradas mais recentes de transferências recebidas/repasses confirmadas. Não o use como um livro-razão completo.

Status público da página de pagamento

GET /api/v1/checkout/{public_id} não exige credenciais. Ele fornece o estado da página de pagamento, incluindo status, received, amount e expires_at. Use o endpoint autenticado de issuance para os registros de loja do seu back-end.

Para atualizações push e verificação de assinatura, veja Webhooks.