Pular para o conteúdo principal

Conciliação do pagamento Pix (Pix Out)

Resumo​

Depois de criar um pagamento Pix (Pix Out) via POST /api/v1/payment com um correlationID próprio, é comum precisar relacionar esse correlationID com o endToEndId (o id oficial da transação Pix, gerado pelo Banco Central) para fins de conciliação.

FormaQuando usar
Webhook OPENPIX:MOVEMENT_CONFIRMEDVocê quer ser avisado no momento em que o pagamento é confirmado, já recebendo correlationID e endToEndId juntos — sem polling.
GET /api/v1/payment/{id}Você quer consultar sob demanda um pagamento específico, usando o correlationID que você mesmo definiu.
GET /api/v1/paymentVocê quer conciliar em lote, listando os pagamentos de um período.
GET /api/v1/transaction não retorna o correlationID do pagamento

É comum tentar localizar o correlationID consultando GET /api/v1/transaction (ou GET /api/v1/transaction?withdrawal={endToEndId}) — mas esse endpoint lista as transações Pix (o evento processado pelo Banco Central), não os pagamentos (o pedido que você fez). Por isso a resposta traz endToEndId, value, time, contas, etc., mas não traz o correlationID do pagamento que originou aquela transação.

Para relacionar as duas pontas, use sempre GET /api/v1/payment/{id} ou o webhook OPENPIX:MOVEMENT_CONFIRMED, descritos abaixo.

Forma 1 (recomendada) — Webhook OPENPIX:MOVEMENT_CONFIRMED​

Assim que o pagamento é confirmado, a Woovi dispara o webhook OPENPIX:MOVEMENT_CONFIRMED já com o payment.correlationID e o transaction.endToEndId no mesmo payload:

{
  "event": "OPENPIX:MOVEMENT_CONFIRMED",
  "payment": {
    "value": 30,
    "status": "CONFIRMED",
    "destinationAlias": "06882328684",
    "comment": "",
    "correlationID": "222a1750-de17-406c-bd0c-25af9a5a5d08"
  },
  "transaction": {
    "value": 30,
    "endToEndId": "E23114447202303161242u80lZNR7nQZ",
    "time": "2023-03-16T12:42:47.526Z"
  }
}

Salvando esse mapeamento assim que o webhook chega, você deixa de precisar consultar a API depois para descobrir o endToEndId de um pagamento — ele já fica disponível no seu sistema desde a confirmação.

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

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 a lista de erros de pagamento.

Forma 2 — Consultar pelo correlationID (GET /api/v1/payment/{id})​

Se preferir consultar sob demanda em vez de depender do webhook, use o endpoint de pagamento passando o correlationID (ou o id interno) que você definiu na criação:

Get one Payment request

curl --request GET \
  --url https://api.woovi.com/api/v1/payment/222a1750-de17-406c-bd0c-25af9a5a5d08 \
  --header 'Authorization: {APP_ID}'

A resposta traz o payment (com correlationID, status, value, etc.) e, quando a transação já existe, o objeto transaction com o endToEndId:

{
  "payment": {
    "status": "CONFIRMED",
    "value": 30,
    "correlationID": "222a1750-de17-406c-bd0c-25af9a5a5d08",
    "destinationAlias": "06882328684"
  },
  "transaction": {
    "value": 30,
    "endToEndId": "E23114447202303161242u80lZNR7nQZ",
    "time": "2023-03-16T12:42:47.526Z"
  },
  "destination": {
    "name": "...",
    "taxID": "...",
    "pixKey": "...",
    "bank": "..."
  }
}

payment.correlationID e transaction.endToEndId vêm juntos na mesma resposta — não é necessária nenhuma outra chamada para relacioná-los.

dica

O correlationID também é a chave de idempotência do pagamento — reuse-o em retentativas até o pagamento chegar a um estado final (CONFIRMED ou FAILED). Veja Idempotência em Pagamentos e a Máquina de Estados do Pagamento.

Forma 3 — Listar em lote (GET /api/v1/payment)​

Para fechar um período inteiro de uma vez — em vez de consultar pagamento por pagamento — use a listagem, filtrando por data:

curl --request GET \
  --url 'https://api.woovi.com/api/v1/payment?start=2026-06-01T00:00:00Z&end=2026-06-30T23:59:59Z&limit=100' \
  --header 'Authorization: {APP_ID}'

Cada item da lista já traz payment.correlationID e transaction.endToEndId juntos. Veja os detalhes de paginação em Como consultar e listar Pagamentos?.

E o reembolso? Como vincular um reembolso à transação original​

O mesmo tipo de dúvida aparece na direção contrária: depois de estornar uma cobrança recebida, como saber a qual cobrança original aquele reembolso pertence?

A resposta é a mesma lógica: use o identificador da cobrança original (correlationID, transactionID ou id interno) como âncora — tanto para criar quanto para consultar os reembolsos, já que todo reembolso é criado e consultado dentro do contexto da cobrança que ele estorna:

Assim, a partir do correlationID que você já usa para identificar a cobrança no seu sistema, você chega direto em todos os reembolsos associados a ela, sem precisar cruzar dados manualmente entre cobrança, transação e estorno.

Fluxo recomendado​

  1. Crie o pagamento com um correlationID próprio, estável por operação (veja Idempotência em Pagamentos).
  2. Prefira o webhook OPENPIX:MOVEMENT_CONFIRMED para capturar correlationID e endToEndId juntos no momento da confirmação, sem polling.
  3. Como alternativa ou reforço, consulte GET /api/v1/payment/{correlationID} sob demanda.
  4. Para fechamento de período, use GET /api/v1/payment com start/end.
  5. Para reembolsos de cobranças, ancore sempre pelo correlationID/id da cobrança original ao criar (POST /api/v1/charge/{id}/refund) e ao consultar (GET /api/v1/charge/{id}/refund).
  6. Reserve GET /api/v1/transaction para consultar o histórico de transações Pix recebidas ou o detalhe de uma transação pelo endToEndId — não para localizar o correlationID de um pagamento.