Primeira integração

O caminho mais curto até a integração funcionando. Ao fim deste guia a sua aplicação recebe alertas com a assinatura validada, envia transações e responde alertas pela API. Cada passo aponta para a página com o detalhe completo.

1. Pegue as credenciais

No painel da Rapid, em Configurações › API, gere o client_id e o client_secret. O segredo aparece uma única vez: copie na hora. Se perder, gere de novo no mesmo lugar (as credenciais anteriores deixam de valer no mesmo instante).

Guarde as duas em variáveis de ambiente, nunca no código:

export RAPID_CLIENT_ID="seu_client_id"
export RAPID_CLIENT_SECRET="seu_client_secret"

Detalhes em Autenticação.

2. Confirme que a credencial funciona

Liste o alerta mais recente da sua empresa:

curl -u "$RAPID_CLIENT_ID:$RAPID_CLIENT_SECRET" \
  "https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts?per_page=1"

Resposta	O que significa
200 com data e meta	Credencial certa. data pode vir vazio se ainda não chegou nenhum alerta
401 UNAUTHORIZED	client_id ou client_secret errado
403 COMPANY_BLOCKED	A empresa está bloqueada na Rapid: fale com o suporte

3. Cadastre o webhook

Em Configurações › Webhook, cadastre a URL que vai receber os eventos. Ela precisa ser HTTPS e de endereço público de internet: o painel recusa http://, localhost e IP de rede local.

Ao salvar, a Rapid gera a chave de assinatura e mostra uma única vez. Guarde em RAPID_WEBHOOK_SECRET.

Para receber na sua máquina durante o desenvolvimento, exponha o servidor local com um túnel HTTPS (ver Boas práticas).

4. Valide a assinatura

Toda entrega traz X-Webhook-Signature e X-Webhook-Timestamp. O seu endpoint confere a assinatura antes de processar qualquer coisa.

Copie o endpoint pronto da sua linguagem (Node.js, Python ou PHP) em Autenticação do webhook. Os três seguem as mesmas regras:

• a assinatura é calculada sobre o corpo bruto: não leia como JSON antes de validar
• entrega com mais de 5 minutos é recusada (proteção contra reenvio)
• qualquer entrega que não passe recebe 401

Responda 2xx rápido e processe depois, numa fila: a Rapid espera até 30 segundos e, sem resposta, tenta de novo. Use o alert_id para não processar o mesmo alerta duas vezes. Ver Boas práticas.

5. Envie a primeira transação

Se você usa a Prevenção ou a Disputa, elas trabalham com as transações de venda que você envia. Cada transação diz de qual merchant (loja, marca ou vendedor) ela é, pelo merchant_id. Veja os seus:

curl -u "$RAPID_CLIENT_ID:$RAPID_CLIENT_SECRET" \
  "https://api.rapidchargeback.com/api/v1/merchants"

O id de cada item da resposta é o merchant_id (ver Listar merchants). Com ele, a transação mínima:

curl -X POST https://api.rapidchargeback.com/api/v1/transactions \
  -u "$RAPID_CLIENT_ID:$RAPID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "00000000-0000-0000-0000-000000000001",
    "external_id": "TXN-2026-001",
    "transaction_id": "cob_8f2a91c4",
    "transaction_date": "2026-04-01T15:30:00Z",
    "amount": 150.00,
    "currency": "USD",
    "card_bin": "424242",
    "card_last4": "4242",
    "items": [
      { "product_description": "Assinatura Premium - Mensal", "unit_price": 150.00 }
    ]
  }'

• O transaction_id é o identificador da cobrança no seu gateway de pagamento. É por ele que um chargeback futuro encontra a transação: sem ele a defesa sai sem histórico.
• A resposta é 201 com o id da transação na Rapid: guarde. Se perder, dá para achar a transação pelo external_id.
• Se vier a chave warnings, a transação foi criada, mas faltam campos que melhoram a proteção.

Todos os campos em Criar transação. Para volume, use o envio em lote.

6. Responda o primeiro alerta

Quando chegar um alerta de Mastercard, você tem 24 horas para responder. Com o alert_id recebido no webhook:

curl -X PATCH https://api.rapidchargeback.com/api/v1/chargeback-alert/alerts/00000000-0000-0000-0000-000000000099/status \
  -u "$RAPID_CLIENT_ID:$RAPID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "status": "account_suspended" }'

Status	Quando usar
notfound	A transação não existe no seu sistema
account_suspended	A transação existe e já está resolvida (estorno feito, acesso cortado)
other	A transação existe, mas ainda não está resolvida

Alerta de Visa chega com o estorno já feito e não tem prazo. Ver Regras e prazos.

Antes de ir para produção

• Credenciais e chave de assinatura em variáveis de ambiente ou cofre de segredos
• Webhook valida a assinatura e a janela de 5 minutos, e recusa com 401
• Webhook responde 2xx em menos de 30 segundos e processa em fila
• O mesmo alert_id processado duas vezes não gera efeito duplicado
• Alerta de Mastercard respondido em até 24 horas, de forma automática ou por alguém de plantão
• Transações com transaction_id preenchido, se você usa a Disputa
• 429 tratado esperando o Retry-After (ver Códigos de resposta)

Próximos passos

• Payload do webhook: todos os campos de cada evento.
• Ferramentas para devs: a documentação no seu assistente de IA e a coleção do Postman.