Integración

Para integrar Prevención, envías tus transacciones de venta a Rapid a través de la API de Transacciones. Consulta la documentación de la API de Transacciones para los detalles completos de los endpoints.

Datos del merchant

Antes de enviar transacciones, asegúrate de que tu merchant esté registrado con la información completa. Los siguientes campos del merchant son obligatorios para que Prevención funcione:

Campo	Descripción
name	Nombre del merchant
merchant_url	URL del sitio del merchant
contact_phone	Teléfono de contacto
store_name	Nombre de la tienda

Campos mínimos de la transacción

Además de los campos obligatorios de la API de Transacciones, Prevención necesita los siguientes para funcionar:

Campo	Por qué
items[] con product_description	Descripción de los productos comprados. Sin ella no hay qué mostrar al banco emisor
order_number	Identificación del pedido en la respuesta al banco emisor (recomendado)

Campos recomendados

Cuantos más datos envíes, mayor la probabilidad de desviar disputas. La tabla de abajo muestra los campos recomendados y el impacto de cada uno:

Para el reconocimiento de la compra

Campo	Impacto
card_bin	Aumenta la precisión del match con la transacción en disputa
auth_code	Mejora la identificación de la transacción
customer.first_name y customer.last_name	Ayuda al titular a reconocer la compra
customer.email	Ayuda al titular a reconocer la compra

Para la protección contra fraude

La protección contra fraude atiende disputas de fraude. Necesita dos señales de que quien compró es el dueño de la tarjeta: un identificador de la compra (el ancla) y un dato más que confirme a la persona.

Para calificar una transacción, envía una de las 3 combinaciones de abajo. El ancla (ip_address, device_id o device_fingerprint) es obligatoria; junto a ella, envía al menos un campo de la columna de complementos.

Formato	Ancla obligatoria	Al menos uno de los complementos
Opción 1	ip_address	customer.account_id, addresses (shipping), device_id o device_fingerprint
Opción 2	device_id	customer.account_id, addresses (shipping) o ip_address
Opción 3	device_fingerprint	customer.account_id, addresses (shipping) o ip_address

Campos: formato y restricciones

Campo	Requisitos
ip_address	IP pública del comprador en el momento de la compra. Texto plano, no puede ser hash. IPv4 o IPv6
device_id	Identificador único del dispositivo (ej.: IMEI). Texto plano, mín. 15 caracteres, no puede ser hash
device_fingerprint	Fingerprint derivada de atributos del dispositivo (SO, modelo, versión, etc.). Mín. 20 caracteres. Puede ser hash
customer.account_id	Identificador de inicio de sesión del comprador en tu sistema (email, username). Un único valor
addresses (type: shipping)	Dirección de envío completa: street (address1), city, state (region), postal_code, country. No puede ser dirección de tienda

No eliges la opción. Envía todos los campos que tengas: Rapid usa automáticamente la combinación que tu transacción cubre. Por ejemplo, si envías ip_address + device_id + account_id, tu transacción califica tanto para la Opción 1 como para la Opción 2, y la combinación con más campos maximiza la probabilidad de deflexión.

Bienes digitales: no envíes dirección de envío

Si tu empresa vende bienes digitales (software, SaaS, streaming, ebooks, cursos online, servicios sin entrega física), no envíes addresses con type shipping. Las reglas de la red de tarjetas prohíben que quien vende bienes digitales informe una dirección de envío, y enviarla puede suspender la protección contra fraude de tu cuenta.

Para bienes digitales, concéntrate en estos complementos:

Opción	Ancla	Complementos prácticos
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 suelen ser los campos más naturales de capturar en e-commerce digital.

Ejemplo de transacción 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": "203.0.113.10",
  "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 ejemplo incluye todos los campos recomendados para la máxima cobertura de deflexión.