Webhooks

Receba notificacoes automaticas sobre eventos de transacoes e saques.

Webhook PixIn (Depositos)

Receba notificacoes automaticas sempre que uma transacao de entrada (PIX) mudar de status.

Pagamento Confirmado

Webhook PixIn - Pagamento Confirmadojson

{
  "object": "transaction",
  "type": "cashin",
  "status": "successful",
  "companyId": 1,
  "transactionId": "6dcf2aee0d6148e1a12b78db78",
  "subTransactionId": 41394,
  "externalRef": "LEAD-1764252408748_52740",
  "method": "pix",
  "value": 500,
  "amount": 5,
  "currency": "BRL",
  "endToEndId": "E22896431202511271407sjUGQflhcVE",
  "providerEndToEndId": "E22896431202511271407sjUGQflhcVE",
  "providerTxId": "6dcf2aee0d6148e1a12b78db78",
  "pixKey": "c32361fa-44de-4be7-815f-0e782a10860c",
  "payer": {
    "name": "ANGELO ALVES DE MARCHI",
    "documentId": "50651470862",
    "bankName": null,
    "ispb": null
  },
  "receiver": {
    "name": null,
    "documentId": "48969523000177"
  },
  "processedAt": "2025-11-27T11:07:14.997603Z"
}

Reenvio Automatico

3 tentativas automaticas (1 min / 5 min / 15 min)
Idempotencia garantida pelo header X-Idempotency-Key

Webhook CashOut (Saques)

Receba notificacoes automaticas sobre o status das solicitacoes de saque.

Endpoint

URL definida pelo cliente. Exemplo: https://meusite.com.br/api/webhook/korvopay

Headers Obrigatorios

Headershttp

Content-Type: application/json
X-Idempotency-Key: <uuid>

Exemplo de Webhook CashOut

Webhook CashOutjson

{
  "object": "withdraw",
  "type": "cashout",
  "status": "successful",
  "companyId": 1,
  "withdrawId": 7184,

  "value": 10,
  "valueInCents": 1000,
  "currency": "BRL",

  "provider": "A55",
  "providerStatus": 1,
  "providerTid": "wld-00007184",
  "providerPaymentId": "uuid-provider",
  "endToEndId": "Exxxxxxxx",

  "providerAmount": 10,
  "providerConfirmedAt": "2025-11-27T10:12:33Z",
  "providerDebitedAt": null,
  "providerPayload": { ... },

  "pixKey": "chave",
  "pixKeyType": "CPF",
  "creditorDocument": "xxx",

  "payer": {
    "name": "NOME DO BANCO/A55",
    "document": "xxx",
    "ispb": "xxxxx",
    "agency": "xxxx",
    "account": "xxxx"
  },

  "receiver": {
    "name": "NOME DO CLIENTE",
    "document": "xxx",
    "ispb": "xxxx",
    "agency": "xxxx",
    "account": "xxxx"
  },

  "createdAt": "2025-11-27T00:00:00Z",
  "updatedAt": "2025-11-27T00:00:00Z",
  "processedAt": "2025-11-27T00:00:00Z",

  "metadata": null
}

Descricao dos Campos

Campo	Tipo	Descricao
`object`	string	Sempre "withdraw"
`type`	string	Tipo do evento — sempre "cashout"
`status`	string	Status final: successful, failure, refunded
`companyId`	number	ID da empresa dona do saque
`withdrawId`	number	ID interno do saque
`value`	number	Valor sacado em reais
`valueInCents`	number	Valor sacado em centavos
`currency`	string	Moeda (sempre "BRL")
`provider`	string	Provedor usado (ex: "A55")
`providerTid`	string	TID do saque no provedor
`endToEndId`	string	Codigo PIX unico do saque (E2E)
`pixKey`	string	Chave PIX de destino
`pixKeyType`	string	Tipo da chave (CPF, CNPJ, EMAIL, PHONE, EVP)
`payer`	object	Dados do pagador (banco)
`receiver`	object	Dados do recebedor (cliente)
`processedAt`	string	Data/hora que o provedor processou
`metadata`	object \| null	Metadados customizados enviados na solicitacao

Quando o Webhook e Enviado

O saque e confirmado (successful)
O saque e estornado (refunded)
O saque e recusado (failure)

Exemplo de Resposta

Sua aplicacao deve responder com um JSON confirmando o recebimento:

Responsejson

{ "received": true, "idempotent": false }