# Types and payload

> Reference of the values accepted in the two capture channels. Applies to POST /capture/{token}/events and POST /capture/events.

Página: https://doc.rapidchargeback.com/en/canais/capture/payload/

Reference of the values accepted in the two capture channels. Applies to [`POST /capture/{token}/events`](https://doc.rapidchargeback.com/en/canais/capture/enviar-evento-navegador/) and [`POST /capture/events`](https://doc.rapidchargeback.com/en/canais/capture/enviar-evento-servidor/).

## Event fields

| Field | Type | Limit | Required |
|---|---|---|---|
| `type` | string (enum) | see table below | Yes |
| `order_ref` | string | 100 characters | Yes |
| `event_id` | string | 64 characters | Yes in the browser, optional on the server |
| `payload` | object | see accepted fields | No |
| `captured_at` | string (ISO 8601) | - | No, and only the server channel uses it |
| `merchant_id` | string (UUID) | - | Server channel only |

### `order_ref`

It is the order identifier in **your** system, and it is the only thing that links the event to a transaction. Rapid looks, within your company and the given merchant, for:

1. a transaction with `external_id` equal to `order_ref`
2. if not found, a transaction with `order_number` equal to `order_ref`

Always send the same value you used in `external_id` when [creating the transaction](https://doc.rapidchargeback.com/en/canais/transactions/criar-transacao/). A wrong `order_ref` does not cause an error in the call: the event is accepted, finds no transaction and is discarded after the correlation window.

### `event_id`

Event identifier, generated by you. It works as an idempotency key: resending the same `event_id` for the same merchant does not create duplicate evidence.

In the browser channel it is **required** (the snippet generates a UUID per event). In the server channel, if you omit it, Rapid generates one. Send your own whenever you might resend the same call, that is what guarantees idempotency.

Do not use `:` in `event_id`. The character is removed before internal use, which would make two different ids collide.

### `captured_at`

When the fact happened, in ISO 8601.

| Channel | Behavior |
|---|---|
| Browser | ignored. Rapid records the time the event arrived |
| Server | used as sent. If omitted, the time of the call is used |

If the fact happened before the call (a nightly batch process, for example), use the server channel and send `captured_at`.

## `type` values

| Value | What it records | Browser | Server |
|---|---|---|---|
| `checkout` | Purchase completion, with device data | Yes | Yes |
| `terms_acceptance` | Acceptance of terms, policy or contract | Yes | Yes |
| `access_log` | Access to the product or the logged-in area | Yes | Yes |
| `usage_log` | Actual use of the product or service | Yes | Yes |
| `delivery_confirmation` | Delivery confirmed | No | Yes |
| `scan` | Tracking code scan in transit | No | Yes |
| `delivery_gps` | Delivery coordinate | No | Yes |

The last three exist only in the server channel: they are facts of your operation, not of the buyer's browser. Using them in the browser channel returns `422 invalid_type`.

## `payload` fields

`payload` has a **closed list** of fields. A key outside the list is silently discarded, with no error, so check the spelling.

| Field | Type | Use in |
|---|---|---|
| `device_id` | string | `checkout` |
| `device_fingerprint` | string | `checkout` |
| `fp` | string | `checkout`, indicates the origin of the identification (`pro` or `fallback`) |
| `fp_request_id` | string | `checkout`, required to validate the identification |
| `url` | string | `terms_acceptance`, `access_log`, `usage_log` |
| `note` | string | any type |
| `carrier` | string | `delivery_confirmation`, `scan` |
| `tracking` | string | `delivery_confirmation`, `scan` |
| `lat` | number | `delivery_gps` |
| `lng` | number | `delivery_gps` |

Rules:

- scalar values only (string, number, boolean). Objects and lists are discarded
- a string over **512 characters** returns `422 payload_too_large`
- a missing or empty `payload` is accepted

## The `checkout` event

`checkout` is the only type that writes data directly to the transaction, and not just as an attached record. It fills in the transaction's device and IP **only when those fields are empty**: an earlier capture is never overwritten.

What each channel can write:

| Transaction data | Browser | Server |
|---|---|---|
| `device_id` | does not write | writes |
| `device_fingerprint` | only with validated identification | writes |
| `ip_address` | only with validated identification | writes |

The difference exists because the browser token is publishable: anyone who has it can send events. Unvalidated data never touches the fields that back the defense.

**Validated identification** means: you sent `fp_request_id` and `device_id` in the payload, and Rapid confirmed the pair against Fingerprint on the server side. In that case the event also generates a device verification record, with bot, VPN and incognito window signals. Without `fp_request_id`, the event still counts as a record, just without the device part.

Each `fp_request_id` is valid for **one** transaction. The same pair reused in another order is treated as a replay and ignored.

## Correlation window

The event can arrive before the transaction exists. It stays in the queue and is retried for about **68 hours**, at increasing intervals. Once the window passes with no matching transaction, the event is discarded.

In practice: sending `checkout` at the exact moment of the purchase works, even if your routine only sends the transaction to Rapid hours later.

## Next steps

- [Install the snippet](https://doc.rapidchargeback.com/en/canais/capture/instalar-o-snippet/)
- [Send an event from the browser](https://doc.rapidchargeback.com/en/canais/capture/enviar-evento-navegador/)
- [Send an event from the server](https://doc.rapidchargeback.com/en/canais/capture/enviar-evento-servidor/)