Integration

To integrate Prevention, you send your sales transactions to Rapid through the Transactions API. See the Transactions API documentation for the full endpoint details.

Merchant data

Before sending transactions, make sure your merchant is registered with complete information. The following merchant fields are required for Prevention to work:

Field	Description
name	Merchant name
merchant_url	Merchant website URL
contact_phone	Contact phone number
store_name	Store name

Minimum transaction fields

Besides the required fields of the Transactions API, Prevention needs the following to work:

Field	Why
items[] with product_description	Description of the products purchased. Without it there is nothing to show the issuing bank
order_number	Order identification in the answer to the issuing bank (recommended)

Recommended fields

The more data you send, the higher the chance of deflecting disputes. The table below shows the recommended fields and the impact of each:

For purchase recognition

Field	Impact
card_bin	Improves the accuracy of the match with the disputed transaction
auth_code	Improves transaction identification
customer.first_name and customer.last_name	Helps the cardholder recognize the purchase
customer.email	Helps the cardholder recognize the purchase

For fraud protection

Fraud protection handles fraud disputes. It needs two signals that the buyer is the card owner: an identifier of the purchase (the anchor) and one more piece of data that confirms the person.

To qualify a transaction, send one of the 3 combinations below. The anchor (ip_address, device_id or device_fingerprint) is required; next to it, send at least one field from the complements column.

Format	Required anchor	At least one of the complements
Option 1	ip_address	customer.account_id, addresses (shipping), device_id or device_fingerprint
Option 2	device_id	customer.account_id, addresses (shipping) or ip_address
Option 3	device_fingerprint	customer.account_id, addresses (shipping) or ip_address

Fields: format and restrictions

Field	Requirements
ip_address	The buyer’s public IP at the time of purchase. Plain text, cannot be a hash. IPv4 or IPv6
device_id	Unique device identifier (e.g. IMEI). Plain text, at least 15 characters, cannot be a hash
device_fingerprint	Fingerprint derived from device attributes (OS, model, version, etc.). At least 20 characters. Can be a hash
customer.account_id	The buyer’s login identifier in your system (email, username). A single value
addresses (type: shipping)	Full shipping address: street (address1), city, state (region), postal_code, country. Cannot be a store address

You do not choose the option. Send as many fields as you have: Rapid automatically uses the combination your transaction covers. For example, if you send ip_address + device_id + account_id, your transaction qualifies for both Option 1 and Option 2, and the combination with more fields maximizes the chance of deflection.

Digital goods: do not send a shipping address

If your company sells digital goods (software, SaaS, streaming, ebooks, online courses, services without physical delivery), do not send addresses with type shipping. Card network rules forbid sellers of digital goods from providing a shipping address, and sending one can suspend fraud protection for your account.

For digital goods, focus on these complements:

Option	Anchor	Practical complements
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 and ip_address tend to be the most natural fields to capture in digital e-commerce.

Full transaction example

{
  "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"
    }
  ]
}

This example includes every recommended field for maximum deflection coverage.