Webhooks

A Barte envia notificações via webhook quando há mudanças no status das contas e atualizações sobre pagamentos, saques e depósitos.

Configuração

A URL de callback é configurada durante o onboarding. Requisitos:

• HTTPS obrigatório

• Responder com status 2xx em até 30 segundos

• Suportar retentativas (até 5 tentativas com backoff exponencial)

Headers

Header	Descrição
Content-Type	application/json

Evento principal

Evento	Quando	Descrição
account_status.update	Qualquer mudança de status da conta	Notifica mudança de status da conta
cash_in.update	Depósito na conta	Notifica qualquer depósito feito para a conta
cash_out.update	Saque ou pagamento	Notifica qualquer saque ou pagamento feito pela a conta
cash_out.refund	Estorno na conta	Notifica qualquer estorno que houver na conta

Status da Conta (KYC)

Status	Descrição	Ação recomendada
PENDING	KYC em processamento	Aguardar
KYC_APPROVED	KYC aprovado	Chamar POST /activate
KYC_REPROVED	KYC rejeitado	Corrigir dados via PUT

Status de Pagamento

Status	Descrição	Ação recomendada
SUCCESS	Pagamento em processamento	Aguardar a conclusão do processamento.
FAILED	Pagamento falhou	Verificar o motivo da falha e tomar a ação apropriada.
REFUNDED	Pagamento Estornado	Verificar o estorno e tomar a ação apropriada

Exemplos de Payload

Status da Conta (KYC)

KYC Aprovado

{
  "event": "account_status.update",
  "processedAt": "2026-01-30T16:00:00Z",
  "data": {
    "accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "accountType": "business",
    "status": "KYC_APPROVED",
    "reasons": []
  }
}

KYC Rejeitado

{
  "event": "account_status.update",
  "timestamp": "2026-01-30T16:00:00Z",
  "data": {
    "accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "accountType": "business",
    "status": "KYC_REPROVED",
    "reasons": ["name_mismatch, partners_are_missing"]
  }
}

KYC Pendente

{
  "event": "account_status.update",
  "timestamp": "2026-01-30T16:00:00Z",
  "data": {
    "accountId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "accountType": "business",
    "status": "PENDING",
    "reasons": []
  }
}

Eventos de cash-in | cash-out

Pagamento efetuado ou Saque

{
  "id": "488cfff1-7b81-47cc-a68f-fcf6d0246a3e",
  "eventType": "cash_out.update",
  "amount": 0.01,
  "initiationType": "static_qrcode",
  "endToEndId": "E3168015120251236210953SF2OT9BB8",
  "status": "SUCCESS",
  "operationDate": "2025-08-27T00:00:00",
  "description": "",
  "errorReason": null,
  "creditParty": {
    "pixKey": "33439146812",
    "name": "Empresa Recebedora LTDA",
    "document": "12345678000199",
    "accountNumber": "987654",
    "accountType": "CACC",
    "branch": "0001"
  },
  "debitParty": {
    "accountNumber": "123456",
    "accountType": "CACC",
    "bankIspb": "87654321",
    "branch": "0001",
    "document": "98765432100",
    "name": "Cliente Pagador"
  }
}

Depósito

{
  "id": "8b8baece-7da7-4441-8826-fb507a481106",
  "eventType": "cash_in.update",
  "amount": 1000000,
  "initiationType": "static_qrcode",
  "endToEndId": "E3168015120251236210953SF2OT9BB8",
  "status": "SUCCESS",
  "operationDate": "2026-02-20T00:00:00",
  "description": "Payment simulation",
  "errorReason": null,
  "creditParty": {
    "pixKey": "d46fe074-c77c-4ef5-8831-7a6833cd2781",
    "name": "Cliente Recebedor",
    "document": "36186677000103",
    "accountNumber": "118802",
    "accountType": "TRAN",
    "branch": "1"
  },
  "debitParty": {
    "accountNumber": "4370771",
    "accountType": "CACC",
    "bankIspb": "30306294",
    "branch": "30",
    "document": "31680151000161",
    "name": "Cliente Pagador"
  }
}

Estorno

{
  "id": "804",
  "eventType": "cash_out.refund",
  "amount": 0.01,
  "initiationType": "static_qrcode",
  "endToEndId": "E3168015120251236210953SF2OT9BB8",
  "status": "REFUNDED",
  "operationDate": "2025-12-05T11:50:47",
  "description": null,
  "errorReason": "devolução solicitada pelo destinatário final",
  "creditParty": {
    "pixKey": "33541533854",
    "name": "Cliente Pagador",
    "document": "98765432100",
    "accountNumber": "123456",
    "accountType": "CACC",
    "branch": "0001"
  },
  "debitParty": {
    "accountNumber": "987654",
    "accountType": "CACC",
    "bankIspb": "12345678",
    "branch": "0001",
    "document": "12345678000199",
    "name": "Empresa Recebedora LTDA"
  }
}