API para Desenvolvedores

Integre doações, webhooks e automações na sua stack. Autenticação por chave de API.

Autenticação

Todas as requisições autenticadas exigem o header Authorization com sua chave de API. Gere a chave em Configurações do dashboard ou via GET /api/user/api-key.

Header obrigatório

Authorization: Bearer tp_live_xxxxxxxx

Nunca exponha sua chave no front-end público. Use apenas em servidor ou automações.

Base URL: https://api.pix.tips/v1

Webhooks

Configure um endpoint HTTPS para receber eventos assinados com HMAC-SHA256 no header X-Tip-Page-Signature.

donation.created

Disparado quando uma doação é iniciada (Pix gerado ou cartão em processamento).

{
  "event": "donation.created",
  "data": {
    "id": "txn_abc123",
    "amount": 25.00,
    "currency": "BRL",
    "status": "pending",
    "donor_name": "Maria",
    "created_at": "2026-05-28T14:00:00Z"
  }
}

donation.confirmed

Disparado quando o pagamento é confirmado e o alerta pode ser exibido.

{
  "event": "donation.confirmed",
  "data": {
    "id": "txn_abc123",
    "amount": 25.00,
    "status": "confirmed",
    "method": "pix",
    "confirmed_at": "2026-05-28T14:02:11Z"
  }
}

donation.failed

Disparado quando o pagamento expira, é recusado ou cancelado.

{
  "event": "donation.failed",
  "data": {
    "id": "txn_abc123",
    "amount": 25.00,
    "status": "failed",
    "reason": "expired"
  }
}

Endpoints

Referência dos principais recursos REST. Substitua tp_live_SUA_CHAVE pela chave do dashboard.

GEThttps://api.pix.tips/v1/me

Retorna dados do criador autenticado (perfil público e metas).

curl -X GET "https://api.pix.tips/v1/me" \
  -H "Authorization: Bearer tp_live_SUA_CHAVE"

GEThttps://api.pix.tips/v1/donations

Lista doações com paginação e filtros por status e período.

curl -X GET "https://api.pix.tips/v1/donations?status=confirmed&limit=20" \
  -H "Authorization: Bearer tp_live_SUA_CHAVE"

GEThttps://api.pix.tips/v1/donations/{id}

Detalhes de uma transação específica.

curl -X GET "https://api.pix.tips/v1/donations/txn_abc123" \
  -H "Authorization: Bearer tp_live_SUA_CHAVE"

POSThttps://api.pix.tips/v1/webhooks

Registra URL de webhook para receber eventos de doação.

curl -X POST "https://api.pix.tips/v1/webhooks" \
  -H "Authorization: Bearer tp_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://seu-servidor.com/hooks/tip-page","events":["donation.confirmed"]}'

POSThttps://api.pix.tips/v1/test-alert

Envia alerta de teste para o widget conectado (rate limit: 10/h).

curl -X POST "https://api.pix.tips/v1/test-alert" \
  -H "Authorization: Bearer tp_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"amount":10,"donor_name":"API Test"}'

Gere sua chave em Configurações ou via GET /api/user/api-key autenticado.