Pagamentos

Fluxo de pagamentos Pix (cash-out) — iniciação, confirmação e schema de retorno

Os pagamentos Pix permitem enviar valores a partir da conta autenticada (cash-out). Diferem das cobranças Pix, que geram QR Code para receber.

Na Referência API, o grupo é Pix > Pagamentos (/api/v2/pix/pagamentos).

Fluxo

Obter token Bearer com scopes pix.read e/ou pix.write (login).
Iniciar o pagamento por chave, QR Code ou manual.
A API devolve um pagamento com status: "0" (INICIADO).
Confirmar em Confirmar com id, valor, chave_idempotencia e recebedor (espelhado da iniciação). Não envie endToEndId nem pagador no body.
Listar ou consultar por id para acompanhar — ou receba webhook de pagamento quando o débito for efetivado (pagamento) ou falhar (pagamento-falha).

Sem a confirmação, o pagamento iniciado não é liquidado.

Cadastre pagamento e/ou pagamento-falha em uma chave da conta pagadora. Espelho do webhook de recebimento (recebimento).

Autenticação

Header	Valor
`Authorization`	`Bearer {{access_token}}`
`Accept`	`application/json`
`Content-Type`	`application/json` (POST)

Scope	Uso
`pix.read`	Listar e consultar
`pix.write`	Iniciar e confirmar

Bases: https://api-h.nuvende.com.br (homologação) · https://api.nuvende.com.br (produção)

Endpoints

Método	Rota	Página
GET	`/api/v2/pix/pagamentos`	Listar
GET	`/api/v2/pix/pagamentos/{id}`	Consultar
POST	`/api/v2/pix/pagamentos/chave`	Por chave
POST	`/api/v2/pix/pagamentos/qrcode`	Por QR Code
POST	`/api/v2/pix/pagamentos/manual`	Manual
POST	`/api/v2/pix/pagamentos/confirmar`	Confirmar
PUT	`/api/v2/cobranca/webhooks/{chave}`	Webhook (`pagamento` / `pagamento-falha`)
PATCH	`/api/v2/cobranca/webhooks/{id}`	Atualiza webhook pelo `id`
DELETE	`/api/v2/cobranca/webhooks/{id}`	Remove webhook pelo `id`

Schema comum de retorno (iniciação)

Os três fluxos de iniciação retornam a mesma estrutura (PagamentoResource). Campos opcionais são omitidos quando null. Pode existir correlationId no envelope quando o middleware define correlação.

{
  "id": "794d7b9e-1a42-4a12-93c2-b48c0d63f730",
  "endToEndId": "E382973742026070812519TFXDFWFD11",
  "chave": "efca2b48-0d8a-4f10-9f07-26e6b5a1b921",
  "valor": 0,
  "txid": "qykhwjRKogXV28MnPcQTmC36iO",
  "status": "0",
  "tipo": 1,
  "id_req": null,
  "recebedor": {
    "pessoa": {
      "nome": "Maria Souza Exemplo",
      "cpfCnpj": "52998224725",
      "tipo": 0
    },
    "conta": {
      "ispb": "38297374",
      "agencia": "0001",
      "conta": "00001234",
      "dataAbertura": "2025-06-18T11:21:45.000000Z",
      "tipo": 0
    }
  },
  "pagador": {
    "pessoa": {
      "nome": "João Silva Exemplo",
      "cpfCnpj": "39053344705",
      "tipo": 0
    },
    "conta": {
      "ispb": "38297374",
      "agencia": "0001",
      "conta": "00005678",
      "dataAbertura": "2026-06-26T20:06:56.000000Z",
      "tipo": 0
    }
  },
  "dataHoraAtualizacao": "2026-07-08T12:51:31.000000Z",
  "dataHoraCriacao": "2026-07-08T12:51:31.000000Z",
  "tipo_transacao": -1,
  "rec_status": null
}

Campos

Campo	Tipo	Descrição
`id`	UUID	Identificador do pagamento — usar em confirmar
`endToEndId`	string \| omitido	Presente em chave/QR; ausente no manual até a confirmação
`chave`	string \| omitido	Chave do recebedor quando resolvida (DICT ou QR)
`valor`	number	Pré-preenchido: `0` em chave/manual; no QR pode vir do payload
`txid`	string	Conciliação (gerado se omitido no request, ~26 caracteres)
`status`	string	Na iniciação: `"0"` = INICIADO
`tipo`	integer	Tipo de iniciação (ver tabela)
`id_req`	string \| null	ID no PSP — `null` na iniciação; preenchido na confirmação
`recebedor` / `pagador`	object	Pessoa + conta
`dataHoraCriacao` / `dataHoraAtualizacao`	datetime	ISO 8601
`tipo_transacao`	integer	`-1` = débito (cash-out)
`rec_status`	string \| null	Pix Automático (QR composto); senão `null`

Campos de erro (erro_codigo, erro_descricao) não vêm na iniciação bem-sucedida.

`pessoa` e `conta`

Subcampo	Descrição
`pessoa.nome`	Nome do titular
`pessoa.cpfCnpj`	CPF/CNPJ (somente dígitos)
`pessoa.nomeFantasia`	PJ, quando existir
`pessoa.tipo`	`0` = PF, `1` = PJ
`conta.ispb`	ISPB (8 dígitos)
`conta.agencia`	Agência
`conta.conta`	Número com dígito verificador
`conta.dataAbertura`	ISO 8601, quando existir
`conta.tipo`	`0` CC · `1` salário · `2` poupança · `3` pagamento · `4` transacional PI

Status e tipo

`status`	Significado
`"0"`	INICIADO (após iniciação) ou PROCESSANDO (após confirmar, aceito no JDPI — Pix externo pode evoluir para `"9"`)
`"9"`	CONFIRMADO — débito efetivado (comum em Pix interno / mesmo ISPB)
`"-1"`	ERRO

`tipo`	Código	Fluxo
`0`	`manu`	Manual
`1`	`dict`	Chave Pix
`2`	`qres`	QR estático
`3`	`qrdn`	QR dinâmico
`8`	`paut`	QR composto (Pix Automático)

Comparativo das iniciações

Aspecto	Chave	QR Code	Manual
Consulta externa	DICT	Decodificação BR Code	Nenhuma
`endToEndId`	Sim	Sim	Não (até confirmar)
`chave`	Sim	Opcional	Não
`valor` na iniciação	`0`	Do QR ou `0`	`0`
`tipo`	`1`	`2`, `3` ou `8`	`0`
`rec_status`	`null`	`null` ou status Pix Automático	`null`

Erros comuns na iniciação

HTTP	Situação
403	Conta pagadora = recebedora (transação local bloqueada na iniciação)
4xx	Falha DICT / decodificação QR / validação

Pagador e recebedor precisam ser contas distintas, mesmo no mesmo PSP (mesmo ISPB).

Relação com outras APIs

API	Uso
Cobranças Cob	Receber (cash-in)
Conta (saldo/extrato)	Consultar saldo antes de enviar
BaaS Pix	Cash-out de parceiro (Bearer + HMAC)

Detalhes e exemplos por linguagem: Referência API → Pix > Pagamentos.

Devoluções Pix

Listar, consultar e solicitar devolução de um Pix recebido.

Listar

Listar pagamentos Pix iniciados e confirmados