Pular para o conteúdo

↑↓ navegar ↵ abrir Ctrl↵ nova aba esc fechar

Registra um evento de captura usando o token publicável. É o endpoint que o snippet chama, e você pode chamá-lo direto se preferir não carregar o script.

POST https://api.rapidchargeback.com/api/v1/capture/{token}/events

Nenhuma. O token publicável na URL identifica o merchant.

Content-Type: application/json

O snippet manda o mesmo JSON como text/plain, que o navegador envia sem consulta prévia de CORS. Os dois tipos são aceitos.

O token não é segredo e pode ficar no HTML da sua loja. Ele só permite escrever, e o evento só vira evidência se corresponder a um pedido real seu.

CampoTipoDescrição
tokenstringToken publicável do merchant, gerado no painel
CampoTipoDescriçãoObrigatório
typestring (enum)checkout, terms_acceptance, access_log ou usage_logSim
order_refstring ou númeroIdentificador do pedido no seu sistema, até 100 caracteresSim
event_idstring ou númeroIdentificador do evento, gerado por você, até 64 caracteresSim
payloadobjetoDados do fato, com campos de lista fechadaNão

A referência completa dos valores aceitos está em Tipos e payload.

Dois pontos específicos deste canal:

  • event_id é obrigatório aqui. Gere um UUID por evento
  • captured_at enviado no corpo é ignorado. A Rapid registra o horário de chegada. Para informar o horário do fato, use o canal servidor

Os tipos delivery_confirmation, scan e delivery_gps não existem neste canal: são fatos da sua operação, não do navegador do comprador.

120 requisições por minuto, por IP de origem e token. É folgado para um checkout real e aperta quem estiver usando o token fora do seu site. Contar também pelo token evita que compradores de lojas diferentes atrás do mesmo IP (rede móvel) dividam o mesmo limite.

Além disso, cada merchant tem um teto de eventos do navegador esperando a transação aparecer. Acima dele, o evento responde 429 TOO_MANY_PENDING_EVENTS até a fila andar. Uso normal não chega perto: o teto existe para o caso de alguém mandar pedidos inventados com o seu token. O envio pelo servidor tem um teto separado, então esse abuso não barra os eventos que o seu backend manda.

RegraResposta
Token desconhecido, inativo ou sem merchant404 NOT_FOUND
type ausente, ou fora dos quatro aceitos neste canal422 VALIDATION_ERROR: invalid_type
order_ref ausente, vazio ou acima de 100 caracteres422 VALIDATION_ERROR: invalid_order_ref
event_id ausente, vazio ou acima de 64 caracteres422 VALIDATION_ERROR: invalid_event_id
device_id acima de 100 caracteres, device_fingerprint acima de 255 ou outro campo de texto do payload acima de 512422 VALIDATION_ERROR: payload_too_large
Evento vindo de um site que não está entre os sites em que o token vale (ver)403 ORIGIN_NOT_ALLOWED
Acima de 120 requisições por minuto429 Too Many Requests
Merchant com eventos demais esperando a transação429 TOO_MANY_PENDING_EVENTS
Recebimento da captura temporariamente indisponível503 CAPTURE_TEMPORARILY_UNAVAILABLE, com Retry-After

No 503, reenvie o evento depois dos segundos do header Retry-After. Com o mesmo event_id, o reenvio nunca duplica a evidência.

Não existe erro para order_ref inexistente. O evento é aceito, fica na fila e é descartado se nenhuma transação corresponder dentro da janela de correlação. Ver Janela de correlação.

Janela do terminal
curl -X POST https://api.rapidchargeback.com/api/v1/capture/seu_token_publicavel/events \
-H "Content-Type: application/json" \
-d '{
"type": "terms_acceptance",
"order_ref": "TXN-2026-001",
"event_id": "019b0000-1111-7000-8000-000000000001",
"payload": { "url": "https://loja.exemplo.com/checkout" }
}'

Evento de checkout com identificação do aparelho:

Janela do terminal
curl -X POST https://api.rapidchargeback.com/api/v1/capture/seu_token_publicavel/events \
-H "Content-Type: application/json" \
-d '{
"type": "checkout",
"order_ref": "TXN-2026-001",
"event_id": "019b0000-1111-7000-8000-000000000002",
"payload": {
"device_id": "8kJ2mQvR1nZxYb0T",
"device_fingerprint": "8kJ2mQvR1nZxYb0T",
"fp": "pro",
"fp_request_id": "1712059781234.Xk9Lp2"
}
}'
{ "accepted": true }

202 quer dizer que o evento entrou na fila, não que já virou evidência. A correlação com a transação acontece depois.

{ "error": { "code": "NOT_FOUND" } }
{
"error": {
"code": "VALIDATION_ERROR",
"message": "invalid_type"
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "invalid_event_id"
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "payload_too_large"
}
}