# Integration

> What to send to enable Prevention: merchant data, minimum transaction fields and the ones that enable fraud protection.

Página: https://doc.rapidchargeback.com/en/produtos/prevencao/integracao/

To integrate Prevention, you send your sales transactions to Rapid through the **Transactions API**. See the [Transactions API documentation](https://doc.rapidchargeback.com/en/canais/transactions/visao-geral/) 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

```json
{
  "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.