Configurar Webhook

Configure o webhook para receber notificacoes em tempo real quando um pagamento Pix for recebido.

Apenas pagamentos Pix que possuem txid (gerados via cobranca) acionam o webhook. Pix recebidos sem txid nao geram notificacao. Os IPs de origem das notificacoes sao dinamicos e podem mudar sem aviso previo.

PUT/webhook/{chave}

Configura a URL de webhook que recebera notificacoes de pagamentos Pix para a chave informada.

Base URL: https://api.pix.basspago.com.br

Headers

Header	Valor	Descricao
`Content-Type`	application/json	Tipo do conteudo da requisicao
`Authorization`	Bearer {access_token}	Token de acesso obtido via OAuth2

Parametros de Rota

Nome	Tipo	Descricao
`chave`	string	Chave Pix para a qual o webhook sera configurado

Parametros do Body

Nome	Tipo	Obrigatorio	Descricao
`webhookUrl`	string	Obrigatorio	URL do webhook que recebera as notificacoes (deve ser HTTPS)

Exemplo de Request

{
  "webhookUrl": "https://sua-api.com.br/webhook/pix"
}

Exemplo de Response

{
  "webhookUrl": "https://sua-api.com.br/webhook/pix",
  "chave": "sua-chave-pix@example.com",
  "criacao": "2025-01-15T10: 30: 00.000Z"
}

Exemplos de Codigo

curl -X PUT https://api.pix.basspago.com.br/webhook/sua-chave-pix@example.com \
  --cert ./client.crt \
  --key ./client.key \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "webhookUrl": "https://sua-api.com.br/webhook/pix"
  }'

A API adiciona automaticamente o sufixo "/pix" a URL de webhook registrada. Por exemplo, se voce configurar "https://example.com/webhook", as notificacoes serao enviadas para "https://example.com/webhook/pix".

GET/webhook/{chave}

Consulta a configuracao de webhook registrada para uma chave Pix especifica.

Base URL: https://api.pix.basspago.com.br

Headers

Header	Valor	Descricao
`Authorization`	Bearer {access_token}	Token de acesso obtido via OAuth2

Parametros de Rota

Nome	Tipo	Descricao
`chave`	string	Chave Pix para a qual o webhook sera consultado

Exemplo de Response

{
  "webhookUrl": "https://your-server.com/webhook/pix"
}

Exemplos de Codigo

curl -X GET https://api.pix.basspago.com.br/webhook/sua-chave-pix@example.com \
  --cert ./client.crt \
  --key ./client.key \
  -H "Authorization: Bearer {access_token}"

DELETE/webhook/{chave}

Cancela e remove a configuracao de webhook registrada para uma chave Pix.

Base URL: https://api.pix.basspago.com.br

Headers

Header	Valor	Descricao
`Authorization`	Bearer {access_token}	Token de acesso obtido via OAuth2

Parametros de Rota

Nome	Tipo	Descricao
`chave`	string	Chave Pix para a qual o webhook sera removido

Exemplo de Response

// 204 No Content

Exemplos de Codigo

curl -X DELETE https://api.pix.basspago.com.br/webhook/sua-chave-pix@example.com \
  --cert ./client.crt \
  --key ./client.key \
  -H "Authorization: Bearer {access_token}"

GET/webhook

Lista todos os webhooks registrados, com suporte a paginacao e filtro por periodo.

Base URL: https://api.pix.basspago.com.br

Headers

Header	Valor	Descricao
`Authorization`	Bearer {access_token}	Token de acesso obtido via OAuth2

Parametros de Query

Nome	Tipo	Obrigatorio	Descricao
`inicio`	string	Obrigatorio	Data/hora inicial do periodo de consulta (formato RFC 3339, ex: 2025-01-01T00:00:00Z)
`fim`	string	Obrigatorio	Data/hora final do periodo de consulta (formato RFC 3339, ex: 2025-01-31T23:59:59Z)
`paginacao.paginaAtual`	integer	Opcional	Numero da pagina atual para paginacao (inicia em 0)
`paginacao.itensPorPagina`	integer	Opcional	Quantidade de itens por pagina (1 a 1000)

Exemplo de Response

{
  "parametros": {
    "inicio": "2025-01-01T00: 00:00Z",
    "fim": "2025-01-31T23: 59:59Z",
    "paginacao": {
      "paginaAtual": 0,
      "itensPorPagina": 100,
      "quantidadeDePaginas": 1,
      "quantidadeTotalDeItens": 2
    }
  },
  "webhooks": [
    {
      "webhookUrl": "https://sua-api.com.br/webhook/pix",
      "chave": "sua-chave-pix@example.com",
      "criacao": "2025-01-15T10: 30: 00.000Z"
    },
    {
      "webhookUrl": "https://sua-api.com.br/webhook/pix",
      "chave": "+5511999999999",
      "criacao": "2025-01-20T14: 00: 00.000Z"
    }
  ]
}

Exemplos de Codigo

curl -X GET "https://api.pix.basspago.com.br/webhook?inicio=2025-01-01T00:00:00Z&fim=2025-01-31T23:59:59Z&paginacao.paginaAtual=0&paginacao.itensPorPagina=100" \
  --cert ./client.crt \
  --key ./client.key \
  -H "Authorization: Bearer {access_token}"