Ir al contenido
A AmunPay API PixVersión 3.38 · actualizada el Páginas

Webhooks

Usted registra una URL HTTPS y recibe un POST con cada evento. La entrega está firmada, se intenta 9 veces en unas 5 horas, y cada dirección tiene su propia cola: un endpoint lento suyo no retrasa a nadie.

Registrar #

PUT /v2/ex/webhook

Alcance: ex.webhook.write.

PUT /v2/ex/webhook
{
  "url": "https://loja.exemplo.com/webhooks/pix",
  "tiposHabilitados": ["*"],
  "urlsPorFamilia": {
    "payout": "https://loja.exemplo.com/webhooks/saques"
  }
}
→ 200
{
  "url": "https://loja.exemplo.com/webhooks/pix",
  "tiposHabilitados": ["*"],
  "urlsPorFamilia": {
    "payout": "https://loja.exemplo.com/webhooks/saques"
  },
  "ativo": true,
  "atualizadoEm": "2026-09-18T12:00:00Z"
}
Campo Tipo Obligatorio Descripción
url string sí HTTPS público. Recibe todo lo que no tiene desvío.
tiposHabilitados lista no ["*"] para todos, o los tipos que usted quiere. Si falta, vale ["*"].
urlsPorFamilia objeto no Desvío por familia. La familia es el primer segmento del tipo, y GET /v2/ex/webhook/familias lista las aceptadas.
cabecalhos objeto no Hasta 3 cabeceras suyas en toda entrega. El valor no vuelve en la lectura.

El PUT describe el estado final: omitir urlsPorFamilia borra los desvíos. Un campo que la ruta no conoce responde 400 campo_desconhecido. GET /v2/ex/webhook lee la configuración, DELETE /v2/ex/webhook desactiva la entrega y GET /v2/ex/webhook/familias lista las familias aceptadas.

El sobre #

Todo evento llega con este cuerpo. Responda 2xx en hasta 10 segundos y procese después. Responda 2xx también a un tipo que usted no conoce.

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N002",
  "tipo": "pix.creditado",
  "criadoEm": "2026-10-23T15:00:07.412Z",
  "sequencia": 2,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "endToEndId": "E60746948202610231500Ab1Cd2Ef3Gh",
    "txid": "FIN02J1ZK7M9QW3ERT5TY6UI8O",
    "valor": "150.00",
    "situacaoFundos": "CREDITADO",
    "pagador": { "cpf": "12345678909", "nome": "Fulano de Tal", "ispb": "60746948" },
    "titularidadeOk": true,
    "instrumento": "PIX",
    "horario": { "liquidacao": "2026-10-23T15:00:07.001Z" }
  }
}
Campo Tipo Descripción
eventoId string Único. Descarte los repetidos por él: la entrega es al menos una vez.
sequencia entero Crece por recurso (txid, idEnvio). El orden entre recursos diferentes no está garantizado.
correlationId string El id de la solicitud que originó el evento. Puede no venir, como en los avisos del plazo del retiro.
dados objeto El contenido del evento. Las claves varían por tipo. En pagador, una empresa viene en cnpj en lugar de cpf. Cuando la institución de pago solo informa el documento de quien pagó enmascarado, viene como ella lo envió en cpfMascarado (o cnpjMascarado), con cpf vacío.

Su respuesta #

Responda 2xx en cuanto lo reciba. Un evento que usted rechace o en el que su sistema falle se repite solo y no detiene a los demás. La cola de la dirección solo se pausa cuando el endpoint parece caído.

Su dirección recibe varios eventos al mismo tiempo, de recursos diferentes. El número se ajusta solo: empieza en 8 y sube mientras la dirección responde 2xx rápido, hasta 512, y baja cuando falla o tarda. Los de un mismo recurso llegan uno a la vez, en el orden de la sequencia. La dirección que todavía no respondió 2xx, o que falló después del último 2xx, recibe uno a la vez. El rechazo de un evento no cuenta.

Respuesta Qué sucede
2xx Entregado.
400, 409, 413 o 422 Rechazo de este evento. Se intenta de nuevo solo y los demás siguen llegando. Los del mismo recurso esperan detrás de él.
5xx, o ninguna respuesta en 10 segundos con la conexión abierta Falla de este evento. Se intenta de nuevo solo y los demás siguen llegando. Los del mismo recurso esperan detrás de él.
La conexión que no se abre (DNS, TLS, conexión rechazada), 401, 403, 404, 405, 410 u otra respuesta La dirección está caída. Los eventos que fallaron esperan, y uno de ellos prueba la dirección hasta que vuelva. Un evento nuevo se intenta de todos modos.

Con 3 eventos diferentes fallando en la misma dirección, ninguno con un 2xx de ella desde la primera falla, la dirección también se pausa. Ningún evento retiene a otro: no hay límite de eventos rechazados, y un evento nuevo sale incluso con la dirección pausada. Cuando un evento llega con 2xx a una dirección pausada, la entrega a ella se reanuda en el acto, y un evento que falló antes de ese 2xx, incluso con 404, pasa a intentarse solo sin pausar la dirección.

La firma #

Cada entrega trae la cabecera x-jws-signature con una JWS separada ES256 sobre el cuerpo. La clave pública está en GET /.well-known/jwks.json. Verifíquela antes de confiar en el cuerpo.

Cabeceras suyas #

Si un firewall o gateway delante de su endpoint exige un token, registre hasta 3 cabeceras. Van en toda entrega, en la URL general y en los desvíos.

PUT /v2/ex/webhook
{
  "url": "https://loja.exemplo.com/webhooks/pix",
  "tiposHabilitados": ["*"],
  "cabecalhos": {
    "Authorization": "Bearer token-do-seu-gateway"
  }
}
→ 200
{
  "url": "https://loja.exemplo.com/webhooks/pix",
  "tiposHabilitados": ["*"],
  "cabecalhos": {
    "Authorization": null
  },
  "ativo": true,
  "atualizadoEm": "2026-09-29T12:00:00Z"
}

Omitir cabecalhos mantiene las registradas, {} borra todas, un nombre con null mantiene ese valor y un nombre registrado que no viene en el objeto se borra. Cambiar la url no borra las cabeceras. La firma sigue siendo obligatoria: las cabeceras van junto con ella, nunca en su lugar.

Eventos #

Tipo Cuándo
pix.recebido El Pix se liquidó. Todavía no es saldo. Con situacaoFundos EM_DEVOLUCAO, fue rechazado y vuelve al pagador.
pix.creditado El dinero se convirtió en saldo. Acredite a su cliente aquí.
pix.retido El Pix entró y quedó bloqueado.
cob.pagamento_rejeitado Rechazamos el pago. motivo dice por qué. Si custodia.recusaAntesDoCredito es false en GET /v2/ex/config, el dinero entró y vuelve al pagador: siguen pix.recebido con EM_DEVOLUCAO y devolucao.criada.
cob.atualizada El cobro fue modificado o cancelado.
devolucao.criada Salió una devolución, suya o nuestra. motivo dice cuál.
devolucao.concluida La devolución se liquidó.
devolucao.nao_realizada La devolución no salió. En la que usted solicitó, el banco del pagador la rechazó. En la nuestra, el Pix no volvió al pagador y fue acreditado a usted: el pix.creditado llega aparte, sin orden garantizado entre los dos.
payout.aguardando_aprovacao El retiro se detuvo en una regla de aprobación, o usted solicitó la aprobación, y espera a un gestor en el panel. El valor ya salió del disponible. Sin endToEndId.
payout.em_processamento El retiro está en envío. Sin aprobación, el valor sale del disponible ahora.
payout.realizado El retiro se liquidó. endToEndId es el definitivo. Trae recebedor cuando la institución informa quién lo recibió.
payout.nao_realizado El retiro fue rechazado. El valor volvió al disponible.
payout.devolucao_recebida El banco del beneficiario devolvió un retiro ya realizado.
payout.sla.em_risco Faltan 30 minutos para el plazo del retiro.
payout.sla.estourado El plazo del retiro venció con él en curso.
favorecido.criado Alguien registró en el panel un destino para retiros. Ya vale: liberaEm es el propio registro. Si usted no lo reconoce, elimínelo.
favorecido.liberado La institución liberó antes del plazo un destino que estaba esperando. Ya recibe, y liberaEm dice desde cuándo. Si usted no lo reconoce, elimínelo.
favorecido.renomeado La institución corrigió, a su pedido, el nombre de un destino. Solo cambia el nombre: la clave, el documento y la espera quedan como estaban.
favorecido.removido El destino salió de la lista.
med.infracao.criada Un Pix recibido fue disputado. Vea Disputas.
med.infracao.atualizada La disputa cambió de situación o tuvo desenlace.
saldo.bloqueado Parte del saldo fue retenida.
saldo.desbloqueado La retención terminó.
subconta.atualizada Una subcuenta fue creada, cambió de estado o tuvo el custodiante cambiado. statusAnterior solo viene en el cambio de estado.
conta.status_alterado Su cuenta cambió de estado.
conta.segmento_alterado La institución reclasificó su cuenta. Vuelva a leer GET /v2/ex/config.
conta.custodiante_alterado Su cuenta principal pasó a estar en otra institución. custodiante y custodianteAnterior traen el nombre de cada una. Vuelva a leer GET /v2/ex/config.
split.executado Un cobro recibido fue repartido.
split.revertido Una devolución o disputa deshizo el reparto.
tarifa.cobrada Se cobró una tarifa. En un cobro recibido, meio es PIX_RECEBIDO y referencia es el txid; en un retiro realizado, meio es PIX_ENVIADO y referencia es el idEnvio. valor es la tarifa.
webhook.teste Disparado por POST /v2/ex/webhook/teste. Cuando llega, la entrega pausada de esa dirección vuelve a intentarse.

Ejemplos de cada evento #

El cuerpo completo que su endpoint recibe en cada tipo, con valores ficticios. Una clave nueva puede aparecer en dados: ignore las que no conozca.

pix.recebido #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N001",
  "tipo": "pix.recebido",
  "criadoEm": "2026-10-23T15:00:07.212Z",
  "sequencia": 1,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "endToEndId": "E60746948202610231500Ab1Cd2Ef3Gh",
    "txid": "FIN02J1ZK7M9QW3ERT5TY6UI8O",
    "valor": "150.00",
    "situacaoFundos": "RECEBIDO",
    "pagador": { "cpf": "12345678909", "nome": "Fulano de Tal", "ispb": "60746948" },
    "instrumento": "PIX",
    "horario": { "liquidacao": "2026-10-23T15:00:07.001Z" }
  }
}

pix.creditado #

En un cobro con split también viene split, y en una subcuenta, subconta.

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N002",
  "tipo": "pix.creditado",
  "criadoEm": "2026-10-23T15:00:07.412Z",
  "sequencia": 2,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "endToEndId": "E60746948202610231500Ab1Cd2Ef3Gh",
    "txid": "FIN02J1ZK7M9QW3ERT5TY6UI8O",
    "valor": "150.00",
    "situacaoFundos": "CREDITADO",
    "pagador": { "cpf": "12345678909", "nome": "Fulano de Tal", "ispb": "60746948" },
    "titularidadeOk": true,
    "instrumento": "PIX",
    "horario": { "liquidacao": "2026-10-23T15:00:07.001Z" }
  }
}

pix.retido #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N003",
  "tipo": "pix.retido",
  "criadoEm": "2026-10-23T18:20:41.090Z",
  "sequencia": 4,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "endToEndId": "E60746948202610231500Ab1Cd2Ef3Gh",
    "valor": "100.00",
    "situacaoFundos": "RETIDO",
    "tipo": "MED",
    "bloqueio": { "id": "med:01JB2Q7M9QW3ERT5TY6VK8NPQR", "tipo": "MED" }
  }
}

cob.pagamento_rejeitado #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N004",
  "tipo": "cob.pagamento_rejeitado",
  "criadoEm": "2026-10-23T15:10:02.530Z",
  "sequencia": 1,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "txid": "FIN03JB2Q7M9QW3ERT5TY6VK8N",
    "motivo": "TITULARIDADE",
    "politica": "RECUSAR",
    "pagador": { "cpf": "98765432100" },
    "cpfMascaradoPagador": "***654321**"
  }
}

cob.atualizada #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N005",
  "tipo": "cob.atualizada",
  "criadoEm": "2026-10-23T15:12:30.118Z",
  "sequencia": 2,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "txid": "FIN04JB2Q7M9QW3ERT5TY6VK8N",
    "revisao": 1,
    "status": "ATIVA",
    "valor": "120.00",
    "pixCopiaECola": "00020126480014br.gov.bcb.pix0126...6304C057"
  }
}

devolucao.criada #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N006",
  "tipo": "devolucao.criada",
  "criadoEm": "2026-10-23T16:00:00.401Z",
  "sequencia": 1,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "endToEndId": "E60746948202610231500Ab1Cd2Ef3Gh",
    "txid": "FIN02J1ZK7M9QW3ERT5TY6UI8O",
    "id": "D1",
    "valor": "10.00",
    "motivo": "SOLICITADA",
    "natureza": "ORIGINAL"
  }
}

devolucao.concluida #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N007",
  "tipo": "devolucao.concluida",
  "criadoEm": "2026-10-23T16:00:02.877Z",
  "sequencia": 2,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "endToEndId": "E60746948202610231500Ab1Cd2Ef3Gh",
    "id": "D1",
    "rtrId": "D12345678202610231600Mn4Pq7Rs2Tv",
    "valor": "10.00"
  }
}

devolucao.nao_realizada #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N008",
  "tipo": "devolucao.nao_realizada",
  "criadoEm": "2026-10-23T16:05:01.954Z",
  "sequencia": 2,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "endToEndId": "E60746948202610231500Ab1Cd2Ef3Gh",
    "id": "D2",
    "motivo": "AC06"
  }
}

payout.aguardando_aprovacao #

regras dice qué reglas detuvieron el retiro: PEDIDA, VALOR, QUANTIDADE_DESTINO o SOMA_DESTINO.

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N009",
  "tipo": "payout.aguardando_aprovacao",
  "criadoEm": "2026-10-23T15:20:00.330Z",
  "sequencia": 1,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "idEnvio": "SAQ02JB2Q7M9QW3ERT5TY6VK8N",
    "valor": "7500.00",
    "tipo": "SAQUE",
    "origem": "API",
    "regras": ["VALOR"],
    "expiraEm": "2026-10-24T15:20:00Z"
  }
}

payout.em_processamento #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N010",
  "tipo": "payout.em_processamento",
  "criadoEm": "2026-10-23T15:30:00.215Z",
  "sequencia": 1,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "idEnvio": "SAQ01JB2Q7M9QW3ERT5TY6VK8N",
    "endToEndId": "E12345678202610231530Kd7Fp2Rt9Wx",
    "valor": "20.00",
    "tipo": "SAQUE",
    "origem": "API",
    "prazoRegulatorio": "2026-10-23T17:30:00Z"
  }
}

payout.realizado #

recebedor solo viene cuando la institución informa quién lo recibió.

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N011",
  "tipo": "payout.realizado",
  "criadoEm": "2026-10-23T15:30:03.640Z",
  "sequencia": 2,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "idEnvio": "SAQ01JB2Q7M9QW3ERT5TY6VK8N",
    "endToEndId": "E12345678202610231530Kd7Fp2Rt9Wx",
    "valor": "20.00",
    "tipo": "SAQUE",
    "origem": "API",
    "sla": { "cumprido": true },
    "recebedor": {
      "nome": "Fulano de Tal",
      "documento": "12345678909",
      "ispb": "18236120",
      "banco": "NU PAGAMENTOS - IP",
      "bancoNomeCompleto": "NU PAGAMENTOS S.A. - INSTITUIÇÃO DE PAGAMENTO",
      "bancoCodigo": "260",
      "bancoCnpj": "18236120000158",
      "agencia": "0001",
      "conta": "35",
      "tipoConta": "TRAN"
    }
  }
}

payout.nao_realizado #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N012",
  "tipo": "payout.nao_realizado",
  "criadoEm": "2026-10-23T15:35:01.102Z",
  "sequencia": 2,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "idEnvio": "SAQ03JB2Q7M9QW3ERT5TY6VK8N",
    "tipo": "SAQUE",
    "origem": "API",
    "motivo": {
      "codigo": "AC03",
      "classe": "CORRIGIVEL",
      "descricao": "Agência/conta do usuário recebedor inexistente ou inválida."
    }
  }
}

payout.devolucao_recebida #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N013",
  "tipo": "payout.devolucao_recebida",
  "criadoEm": "2026-10-23T17:02:44.510Z",
  "sequencia": 3,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "idEnvio": "SAQ01JB2Q7M9QW3ERT5TY6VK8N",
    "endToEndIdOriginal": "E12345678202610231530Kd7Fp2Rt9Wx",
    "rtrId": "D18236120202610231702Hj5Kl8Mn1Pq",
    "valor": "20.00",
    "natureza": "ORIGINAL",
    "motivo": "Devolvido pela instituição de quem recebeu.",
    "devolvidaEm": "2026-10-23T17:01:58Z"
  }
}

payout.sla.em_risco #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N014",
  "tipo": "payout.sla.em_risco",
  "criadoEm": "2026-10-23T17:00:00.019Z",
  "sequencia": 2,
  "dados": {
    "idEnvio": "SAQ04JB2Q7M9QW3ERT5TY6VK8N",
    "tipo": "SAQUE",
    "valor": "300.00",
    "status": "EM_PROCESSAMENTO",
    "prazoRegulatorio": "2026-10-23T17:30:00Z",
    "sla": { "estourado": false, "restanteSegundos": 1800 }
  }
}

payout.sla.estourado #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N015",
  "tipo": "payout.sla.estourado",
  "criadoEm": "2026-10-23T17:31:00.024Z",
  "sequencia": 3,
  "dados": {
    "idEnvio": "SAQ04JB2Q7M9QW3ERT5TY6VK8N",
    "tipo": "SAQUE",
    "valor": "300.00",
    "status": "EM_PROCESSAMENTO",
    "prazoRegulatorio": "2026-10-23T17:30:00Z",
    "sla": { "estourado": true, "restanteSegundos": -60 }
  }
}

favorecido.criado #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N016",
  "tipo": "favorecido.criado",
  "criadoEm": "2026-10-23T14:00:00.711Z",
  "sequencia": 1,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "id": "01JB2Q3F8ZX6M7MMJ99YRB5AYG",
    "chave": "financeiro@fornecedor.com.br",
    "tipoChave": "EMAIL",
    "nome": "Fornecedor Exemplo Ltda",
    "criadoPor": "joao.silva",
    "liberaEm": "2026-10-23T14:00:00Z"
  }
}

favorecido.liberado #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N017",
  "tipo": "favorecido.liberado",
  "criadoEm": "2026-10-23T14:10:00.302Z",
  "sequencia": 2,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "id": "01JB2Q3F8ZX6M7MMJ99YRB5AYG",
    "chave": "financeiro@fornecedor.com.br",
    "nome": "Fornecedor Exemplo Ltda",
    "liberaEm": "2026-10-23T14:10:00Z",
    "liberavaEm": "2026-10-24T14:00:00Z"
  }
}

favorecido.renomeado #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N018",
  "tipo": "favorecido.renomeado",
  "criadoEm": "2026-10-23T14:20:00.845Z",
  "sequencia": 3,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "id": "01JB2Q3F8ZX6M7MMJ99YRB5AYG",
    "chave": "financeiro@fornecedor.com.br",
    "nome": "Fornecedor Exemplo Comércio Ltda",
    "nomeAnterior": "Fornecedor Exemplo Ltda",
    "renomeadoPor": "instituicao"
  }
}

favorecido.removido #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N019",
  "tipo": "favorecido.removido",
  "criadoEm": "2026-10-23T14:30:00.127Z",
  "sequencia": 4,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "id": "01JB2Q3F8ZX6M7MMJ99YRB5AYG",
    "chave": "financeiro@fornecedor.com.br",
    "motivo": "trocou de banco",
    "removidoPor": "joao.silva"
  }
}

med.infracao.criada #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N020",
  "tipo": "med.infracao.criada",
  "criadoEm": "2026-10-23T18:20:41.090Z",
  "sequencia": 1,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "idInfracao": "01JB2Q7M9QW3ERT5TY6VK8NPQR",
    "endToEndId": "E60746948202610231500Ab1Cd2Ef3Gh",
    "tipo": "FRAUDE",
    "valor": "100.00",
    "situacao": "ABERTA",
    "prazoFinalizacao": "2026-10-30T18:20:41Z"
  }
}

med.infracao.atualizada #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N021",
  "tipo": "med.infracao.atualizada",
  "criadoEm": "2026-10-28T12:00:00.640Z",
  "sequencia": 2,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "idInfracao": "01JB2Q7M9QW3ERT5TY6VK8NPQR",
    "situacao": "REJEITADA",
    "encerradaPor": "MED"
  }
}

saldo.bloqueado #

En una retención que no viene de una disputa, como una orden judicial, solo vienen id, tipo y valor.

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N022",
  "tipo": "saldo.bloqueado",
  "criadoEm": "2026-10-23T18:20:41.090Z",
  "sequencia": 1,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "id": "med:01JB2Q7M9QW3ERT5TY6VK8NPQR",
    "tipo": "MED",
    "valor": "100.00",
    "endToEndId": "E60746948202610231500Ab1Cd2Ef3Gh",
    "idInfracao": "01JB2Q7M9QW3ERT5TY6VK8NPQR",
    "prazo": "2026-10-30T18:20:41Z"
  }
}

saldo.desbloqueado #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N023",
  "tipo": "saldo.desbloqueado",
  "criadoEm": "2026-10-28T12:00:00.640Z",
  "sequencia": 2,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "id": "med:01JB2Q7M9QW3ERT5TY6VK8NPQR",
    "tipo": "MED",
    "valor": "100.00",
    "endToEndId": "E60746948202610231500Ab1Cd2Ef3Gh",
    "desfecho": "LIBERADO"
  }
}

subconta.atualizada #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N024",
  "tipo": "subconta.atualizada",
  "criadoEm": "2026-10-23T13:00:00.411Z",
  "sequencia": 1,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "id": "SUB01JB2Q7M9QW3ERT5TY6VK8N",
    "nome": "Filial Centro",
    "cnpj": "11222333000181",
    "status": "EM_ANALISE"
  }
}

conta.status_alterado #

efeitos dice qué salió de circulación con el bloqueo.

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N025",
  "tipo": "conta.status_alterado",
  "criadoEm": "2026-10-23T19:00:00.072Z",
  "sequencia": 1,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "status": "BLOQUEADA",
    "statusAnterior": "ATIVA",
    "motivo": "COMPLIANCE",
    "efeitos": [{ "acao": "COBS_REMOVIDAS", "quantidade": 2 }]
  }
}

conta.custodiante_alterado #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N026",
  "tipo": "conta.custodiante_alterado",
  "criadoEm": "2026-10-23T19:30:00.588Z",
  "sequencia": 2,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "custodiante": "Conta nominal B",
    "custodianteAnterior": "Conta nominal A"
  }
}

split.executado #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N027",
  "tipo": "split.executado",
  "criadoEm": "2026-10-23T15:40:05.330Z",
  "sequencia": 4,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "txid": "FIN05JB2Q7M9QW3ERT5TY6VK8N",
    "endToEndId": "E60746948202610231540Qw3Er5Ty7Ui",
    "referencia": "FIN05JB2Q7M9QW3ERT5TY6VK8N",
    "meio": "PIX",
    "config": "afiliados",
    "valorTotal": "99.60",
    "repartido": "9.96",
    "retidoRecebedor": "89.64",
    "pernas": [{ "parceiro": "afiliado-01", "bps": 1000, "valor": "9.96" }]
  }
}

split.revertido #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N028",
  "tipo": "split.revertido",
  "criadoEm": "2026-10-23T16:10:00.902Z",
  "sequencia": 5,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "referencia": "FIN05JB2Q7M9QW3ERT5TY6VK8N",
    "meio": "PIX",
    "valorRevertido": "50.00",
    "recuperado": "5.00",
    "descoberto": "0.00",
    "pernas": [{ "parceiro": "afiliado-01", "revertido": "5.00", "descoberto": "0.00" }]
  }
}

tarifa.cobrada #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N029",
  "tipo": "tarifa.cobrada",
  "criadoEm": "2026-10-23T15:00:07.413Z",
  "sequencia": 3,
  "correlationId": "01M2SX29NP95HKN0W06DDFPZFG",
  "dados": {
    "meio": "PIX_RECEBIDO",
    "referencia": "FIN02J1ZK7M9QW3ERT5TY6UI8O",
    "valor": "0.40",
    "valorBase": "150.00",
    "faixa": 0
  }
}

webhook.teste #

{
  "eventoId": "01JB2Q7M9QW3ERT5TY6VK8N030",
  "tipo": "webhook.teste",
  "criadoEm": "2026-10-23T12:00:00.000Z",
  "sequencia": 1,
  "dados": {
    "mensagem": "entrega de teste do webhookd"
  }
}

Salud de la cola #

GET /v2/ex/webhook/saude

Alcance: ex.webhook.read.

GET /v2/ex/webhook/saude
→ 200
{
  "situacao": "OK",
  "entregues": 0,
  "emBackoff": 0,
  "recusadas": 0,
  "comErro": 0,
  "desistidas": 0,
  "janelaHoras": 24
}

situacao es OK, ATENCAO o FALHANDO. Fuera de OK viene motivo; en FALHANDO viene también ultimaFalha, con falha RECUSA, ERRO o INDISPONIBILIDADE. recusadas cuenta las que su endpoint rechazó y comErro aquellas en las que falló, y las dos siguen intentándose. Las entregas abandonadas ya no salen solas: corrija el endpoint y solicite el reenvío.

Reenvío #

POST /v2/ex/webhook/reenvios

Alcance: ex.webhook.write.

POST /v2/ex/webhook/reenvios
{
  "tipos": ["pix.creditado"],
  "inicio": "2026-09-17T12:00:00Z",
  "fim": "2026-09-18T12:00:00Z",
  "dryRun": true
}
→ 202
{
  "idReenvio": "01M2SX3Q56B91Y7HDH49X0QQH5",
  "status": "CONCLUIDO",
  "total": 0,
  "enfileirados": 0,
  "dryRun": true
}

dryRun: true solo cuenta. soFalhas: true reenvía solo los avisos que fallaron: los que agotaron los intentos sin que su endpoint los aceptara y nunca fueron entregados. La ventana alcanza hasta 30 días hacia atrás e inicio no puede estar en el futuro; un fim en el futuro vale hasta ahora. Sin webhook activo, el reenvío termina INTERROMPIDO. GET /v2/ex/webhook/reenvios/{id} sigue un reenvío, GET /v2/ex/webhook/reenvios lista los 10 más recientes, POST /v2/ex/webhook/reenvios/{id}/cancelar cancela el reenvío mientras alguno de sus avisos no salió, también el que ya terminó de poner los avisos en la cola (CONCLUIDO): pasa a INTERROMPIDO, y sus avisos que todavía no salieron no se envían, contados en naoEnviados, GET /v2/ex/webhook/entregas lista los intentos con estado HTTP y latencia, filtra por status (PENDENTE, ENTREGUE o FALHA_PERMANENTE) y continúa por ?cursor=, y GET /v2/ex/eventos es el feed de los mismos sobres, para conciliar: avanza por ?apos= con el cursor.proximo de la página anterior. Para ver primero lo que acaba de ocurrir, use ?ordem=recentes, que avanza por ?antes=.

Errores #

Estado title Cuándo
400 url_invalida La URL no es un HTTPS válido.
400 url_privada La URL apunta a una red privada o a localhost, o el host no se resuelve en el DNS.
400 familia_desconhecida urlsPorFamilia menciona una familia que no existe.
400 tipos_invalidos Un elemento de tiposHabilitados en blanco.
400 cabecalho_invalido Nombre o valor fuera de la forma, el mismo nombre dos veces con distinta mayúscula o minúscula, más de 3, o null para un nombre sin valor registrado.
400 cabecalho_proibido Una cabecera de la conexión, del cuerpo o nuestra, como Host, Content-Type o x-jws-signature.
400 campo_desconhecido Un campo que la ruta no conoce, como headers en lugar de cabecalhos.
400 periodo_invalido inicio o fim del reenvío fuera de RFC 3339.
400 janela_invalida fim no es posterior a inicio, o inicio está en el futuro.
400 janela_muito_antiga inicio tiene más de 30 días.
404 nao_encontrado GET o DELETE sin webhook registrado, o reenvío que no existe.
409 reenvio_em_andamento Ya hay un reenvío en curso.
409 reenvio_encerrado El reenvío que se quiere cancelar ya terminó, y todos sus avisos ya salieron.
422 webhook_nao_configurado Prueba sin webhook activo.
503 cabecalhos_indisponiveis La instalación no guarda cabeceras en este momento. No se registró nada.