⌘K

Configurar Webhooks

Configure webhooks para receber notificações em tempo real sobre mudanças de status de recorrências (webhookrec) e de cobranças recorrentes (webhookcobr) do Pix Automático.

Diferente do webhook de Cash In (configurado por chave Pix), os webhooks do Pix Automático são globais por usuário recebedor — não há chave Pix no path. Cada usuário recebedor possui no máximo um webhook de recorrências (webhookrec) e um webhook de cobranças recorrentes (webhookcobr).

Webhook de Recorrências (webhookrec)

PUT/webhookrec

Configura a URL de webhook que receberá notificações de mudança de status das recorrências do usuário recebedor. Requer o escopo webhookrec.write.

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

Headers

Header	Valor	Descricao
`Content-Type`	application/json	Tipo de conteúdo da requisição
`Authorization`	Bearer {access_token}	Token de acesso obtido via OAuth2

Parametros do Body

Nome	Tipo	Obrigatorio	Descricao
`webhookUrl`	string	Obrigatorio	URL do webhook que receberá as notificações (deve ser HTTPS)

Exemplo de Request

{
  "webhookUrl": "https://sua-aplicacao.com.br/webhooks/recorrencias"
}

Exemplo de Response

{
  "webhookUrl": "https://sua-aplicacao.com.br/webhooks/recorrencias",
  "criacao": "2026-06-20T12: 51: 16.485Z"
}

Exemplos de Codigo

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

GET/webhookrec

Consulta a configuração de webhook de recorrências registrada para o usuário recebedor.

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

Headers

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

Exemplo de Response

{
  "webhookUrl": "https://sua-aplicacao.com.br/webhooks/recorrencias",
  "criacao": "2026-06-20T12: 51: 16.485Z"
}

Exemplos de Codigo

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

DELETE/webhookrec

Cancela e remove a configuração de webhook de recorrências do usuário recebedor. Retorna 204 No Content.

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

Headers

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

Exemplo de Response

// 204 No Content

Exemplos de Codigo

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

Webhook de Cobranças Recorrentes (webhookcobr)

PUT/webhookcobr

Configura a URL de webhook que receberá notificações de mudança de status e tentativas de liquidação das cobranças recorrentes do usuário recebedor.

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

Headers

Header	Valor	Descricao
`Content-Type`	application/json	Tipo de conteúdo da requisição
`Authorization`	Bearer {access_token}	Token de acesso obtido via OAuth2

Parametros do Body

Nome	Tipo	Obrigatorio	Descricao
`webhookUrl`	string	Obrigatorio	URL do webhook que receberá as notificações (deve ser HTTPS)

Exemplo de Request

{
  "webhookUrl": "https://sua-aplicacao.com.br/webhooks/cobrancas-recorrentes"
}

Exemplo de Response

{
  "webhookUrl": "https://sua-aplicacao.com.br/webhooks/cobrancas-recorrentes",
  "criacao": "2026-06-20T12: 51: 16.485Z"
}

Exemplos de Codigo

curl -X PUT https://api.pix.basspago.com.br/webhookcobr \
  --cert ./client.crt \
  --key ./client.key \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "webhookUrl": "https://sua-aplicacao.com.br/webhooks/cobrancas-recorrentes"
  }'

GET/webhookcobr

Consulta a configuração de webhook de cobranças recorrentes registrada para o usuário recebedor.

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

Headers

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

Exemplo de Response

{
  "webhookUrl": "https://sua-aplicacao.com.br/webhooks/cobrancas-recorrentes",
  "criacao": "2026-06-20T12: 51: 16.485Z"
}

Exemplos de Codigo

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

DELETE/webhookcobr

Cancela e remove a configuração de webhook de cobranças recorrentes do usuário recebedor. Retorna 204 No Content.

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

Headers

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

Exemplo de Response

// 204 No Content

Exemplos de Codigo

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

Payloads de Notificação

As notificações são enviadas via POST no seu endpoint com um sufixo adicionado à URL configurada: POST {webhookUrl}/rec para mudanças de status de recorrências e POST {webhookUrl}/cobr para mudanças de status e tentativas de cobranças recorrentes.

POST {webhookUrl}/rec — Mudança de status de recorrência

{
  "recs": [
    {
      "idRec": "RR1026652320260821lab77511abf",
      "status": "APROVADA",
      "atualizacao": [
        {
          "status": "CRIADA",
          "data": "2026-06-16T10: 12: 07.567Z"
        },
        {
          "status": "APROVADA",
          "data": "2026-06-18T12: 43: 53.337Z"
        }
      ],
      "ativacao": {
        "tipoJornada": "JORNADA_3",
        "dadosJornada": {
          "txid": "r9eFIFmwcZ55Nm4RsKZAAtIvvCrlcNN6"
        }
      }
    }
  ]
}

POST {webhookUrl}/cobr — Mudança de status/tentativas de cobrança

{
  "cobsr": [
    {
      "idRec": "RR1234567820260801abcdefghijk",
      "txid": "3136957d93134f2184b369e8f1c0729d",
      "status": "ATIVA",
      "atualizacao": [
        {
          "status": "ATIVA",
          "data": "2026-06-16T12: 34: 21.300Z"
        }
      ],
      "tentativas": [
        {
          "dataLiquidacao": "2026-06-20",
          "tipo": "AGND",
          "status": "SOLICITADA",
          "endToEndId": "E12345678202606201221abcdef12345"
        }
      ]
    }
  ]
}

A chamada ao seu endpoint apresenta certificado de cliente mTLS. Valide a origem da notificação verificando o certificado de cliente apresentado na conexão.

Os dados de notificação ficam retidos por 15 dias. Responda com HTTP 2xx para confirmar o recebimento da notificação.