Integração

Para integrar a Prevenção, você precisa enviar suas transações de venda para a Rapid via API de Transações. Consulte a documentação da API de Transações para detalhes completos dos endpoints.

Dados do merchant

Antes de enviar transações, certifique-se de que seu merchant está cadastrado com as informações completas. Os seguintes campos do merchant são obrigatórios para a Prevenção funcionar:

Campo	Descrição
name	Nome do merchant
merchant_url	URL do site do merchant
contact_phone	Telefone de contato
store_name	Nome da loja

Campos mínimos da transação

Além dos campos obrigatórios da API de Transações, a Prevenção precisa dos seguintes para funcionar:

Campo	Por quê
items[] com product_description	Descrição dos produtos comprados. Sem ela não há o que mostrar ao banco emissor
order_number	Identificação do pedido na resposta ao banco emissor (recomendado)

Campos recomendados

Quanto mais dados você enviar, maior a chance de deflectir disputas. A tabela abaixo mostra os campos recomendados e o impacto de cada um:

Para o reconhecimento da compra

Campo	Impacto
card_bin	Aumenta a precisão do match com a transação em disputa
auth_code	Melhora a identificação da transação
customer.first_name e customer.last_name	Ajuda o portador a reconhecer a compra
customer.email	Ajuda o portador a reconhecer a compra

Para a proteção contra fraude

A proteção contra fraude atende disputas de fraude. Ela precisa de dois sinais de que quem comprou é o dono do cartão: um identificador da compra (a âncora) e mais um dado que confirme a pessoa.

Para qualificar uma transação, envie uma das 3 combinações abaixo. A âncora (ip_address, device_id ou device_fingerprint) é obrigatória; ao lado dela, envie ao menos um campo da coluna de complementos.

Formato	Âncora obrigatória	Pelo menos um dos complementos
Opção 1	ip_address	customer.account_id, addresses (shipping), device_id ou device_fingerprint
Opção 2	device_id	customer.account_id, addresses (shipping) ou ip_address
Opção 3	device_fingerprint	customer.account_id, addresses (shipping) ou ip_address

Campos: formato e restrições

Campo	Requisitos
ip_address	IP público do comprador no momento da compra. Texto claro, não pode ser hash. Formatos IPv4 ou IPv6
device_id	Identificador único do dispositivo (ex: IMEI). Texto claro, mín. 15 caracteres, não pode ser hash
device_fingerprint	Fingerprint derivada de atributos do dispositivo (SO, modelo, versão, etc.). Mín. 20 caracteres. Pode ser hash
customer.account_id	Identificador de autenticação do comprador no seu sistema (email, username). Um único valor
addresses (type: shipping)	Endereço de entrega completo: street (address1), city, state (region), postal_code, country. Não pode ser endereço de loja

Você não escolhe a opção. Envie o máximo de campos que tiver: a Rapid usa automaticamente a combinação que a sua transação cobre. Por exemplo, se você envia ip_address + device_id + account_id, sua transação se qualifica tanto para a Opção 1 quanto para a Opção 2, a combinação com mais campos maximiza a chance de deflexão.

Digital goods: não envie endereço de entrega

Se sua empresa vende bens digitais (software, SaaS, streaming, ebooks, cursos online, serviços sem entrega física), não envie addresses com type shipping. As regras da bandeira proíbem quem vende bem digital de informar endereço de entrega, e o envio pode suspender a proteção contra fraude da sua conta.

Para digital goods, foque nestes complementos:

Opção	Âncora	Complementos práticos
1	ip_address	customer.account_id, device_id, device_fingerprint
2	device_id	customer.account_id, ip_address
3	device_fingerprint	customer.account_id, ip_address

customer.account_id e ip_address tendem a ser os campos mais naturais de capturar em e-commerce digital.

Exemplo de transação completa

{
  "merchant_id": "00000000-0000-0000-0000-000000000001",
  "transaction_date": "2026-04-01T15:30:00Z",
  "amount": 150.00,
  "currency": "USD",
  "card_last4": "4242",
  "card_bin": "424242",
  "order_number": "ORD-001",
  "auth_code": "AUTH999",
  "network": "visa",
  "descriptor": "LOJA EXEMPLO",
  "ip_address": "192.168.1.100",
  "device_id": "041C226BBD5A80020040105118304404",
  "external_source": "shopify",
  "external_id": "TXN-2026-001",
  "items": [
    {
      "product_description": "Assinatura Premium - Mensal",
      "product_name": "Plano Premium",
      "quantity": 1,
      "unit_price": 150.00
    }
  ],
  "customer": {
    "first_name": "João",
    "last_name": "Silva",
    "email": "joao@exemplo.com",
    "account_id": "joao@exemplo.com"
  },
  "addresses": [
    {
      "type": "shipping",
      "street": "Rua das Flores",
      "number": "123",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01001000",
      "country": "BRA"
    }
  ]
}

Este exemplo inclui todos os campos recomendados para máxima cobertura de deflexão.