Conciliação do pagamento de boleto

Resumo

Depois de pagar um boleto pela API (fluxo Boleto OUT — veja Como pagar um boleto via API), o pagamento é processado de forma assíncrona. Este guia mostra as duas formas de conciliar e saber que o boleto foi efetivamente pago:

Forma	Quando usar
Webhook `OPENPIX:MOVEMENT_CONFIRMED`	Você quer ser avisado no momento em que o pagamento é confirmado, sem ficar consultando a API.
`GET /api/v1/payment/{id}`	Você quer consultar o estado atual do pagamento pontualmente (polling ou verificação sob demanda).

Nas duas formas, a amarração com a sua operação é feita pelo correlationID que você definiu na criação do pagamento.

Valores em centavos

Todos os valores (value) são expressos em centavos (300 = R$ 3,00).

Máquina de status do pagamento

CREATED ──aprovação──▶ APPROVED ──▶ PROCESSING ──▶ CONFIRMED
                                        │
                                        └──falha──▶ FAILED

`status`	Significado
`CREATED`	Pagamento criado, aguardando aprovação
`APPROVED`	Aprovado; pagamento do boleto disparado ao provedor
`PROCESSING`	Em processamento no provedor
`CONFIRMED`	Boleto pago (estado final)
`FAILED`	Falha no processamento (estado final)

A conciliação acontece nos estados finais: CONFIRMED (pago) ou FAILED (falha).

Forma 1 — Webhook `OPENPIX:MOVEMENT_CONFIRMED`

Quando o pagamento do boleto é confirmado, a Woovi dispara o webhook OPENPIX:MOVEMENT_CONFIRMED para a URL configurada na sua conta. É o mesmo evento de confirmação de PIX OUT, mas no pagamento de boleto o payload traz um objeto boleto (com barcode e expiresDate):

{
  "event": "OPENPIX:MOVEMENT_CONFIRMED",
  "account": {
    "accountId": "6843167bb88789ea9046003f"
  },
  "payment": {
    "value": 300,
    "status": "CONFIRMED",
    "comment": "teste boleto out",
    "correlationID": "boleto-out-teste-006",
    "metadata": {}
  },
  "boleto": {
    "barcode": "34191091725285164077229826090002215000000000300",
    "expiresDate": "2026-07-08T02:59:59.999Z"
  }
}

Campo	Descrição
`event`	`OPENPIX:MOVEMENT_CONFIRMED` no pagamento confirmado
`account.accountId`	Conta de origem que pagou o boleto
`payment.value`	Valor pago, em centavos
`payment.status`	`CONFIRMED` (pago)
`payment.correlationID`	O `correlationID` que você definiu ao criar o pagamento
`payment.metadata`	Metadados que você enviou na criação (se houver)
`boleto.barcode`	Código de barras do boleto pago
`boleto.expiresDate`	Data de vencimento do boleto (ISO 8601)

Ao receber o webhook, use o payment.correlationID para localizar o pagamento na sua base e marcá-lo como pago.

Em caso de falha

Quando o pagamento falha, o evento disparado é OPENPIX:MOVEMENT_FAILED, com payment.status em FAILED e um objeto error com o motivo. Veja Payload de Pagamentos e a lista de erros de pagamento.

Para receber esse evento, crie um webhook selecionando o evento OPENPIX:MOVEMENT_CONFIRMED — veja Tipos de eventos do Webhook. A criação em si pode ser feita via plataforma ou via API; para validar a assinatura, veja Validando o HMAC do webhook.

Forma 2 — Consultar o pagamento (`GET /api/v1/payment/{id}`)

Se preferir consultar em vez de receber o webhook, use o endpoint de pagamento passando o correlationID (ou o id) do pagamento:

Get one Payment request

curl --request GET \
  --url https://api.woovi.com/api/v1/payment/boleto-out-teste-006 \
  --header 'Authorization: {APP_ID}'

A resposta traz o payment com o status atual:

{
  "payment": {
    "status": "CONFIRMED",
    "value": 300,
    "comment": "teste boleto out",
    "correlationID": "boleto-out-teste-006",
    "sourceAccountId": "6843167bb88789ea9046003f"
  }
}

Concilie olhando o campo payment.status:

CONFIRMED → boleto pago (estado final, pode conciliar).
FAILED → pagamento falhou (estado final).
CREATED / APPROVED / PROCESSING → ainda em andamento; consulte novamente mais tarde.

Fluxo recomendado

Crie e aprove o pagamento com um correlationID próprio da sua operação (veja Como pagar um boleto via API).
Prefira o webhook OPENPIX:MOVEMENT_CONFIRMED para ser avisado da confirmação sem polling. Amarre pelo payment.correlationID.
Como alternativa ou reforço, consulte GET /api/v1/payment/{correlationID} e verifique payment.status até chegar em CONFIRMED (pago) ou FAILED (falha).

Resumo​

Máquina de status do pagamento​

Forma 1 — Webhook OPENPIX:MOVEMENT_CONFIRMED​

Forma 2 — Consultar o pagamento (GET /api/v1/payment/{id})​

Fluxo recomendado​

Resumo

Máquina de status do pagamento

Forma 1 — Webhook `OPENPIX:MOVEMENT_CONFIRMED`

Forma 2 — Consultar o pagamento (`GET /api/v1/payment/{id}`)

Fluxo recomendado