# Send an event from the server

> Record capture events from your backend: confirmed delivery, tracking, service usage and backdated events.

Página: https://doc.rapidchargeback.com/en/canais/capture/enviar-evento-servidor/

Records a capture event from your backend, with the same credentials as the other APIs. It is the channel for facts that do not happen in the browser: confirmed delivery, tracking scan, delivery coordinate, and for any event you need to resend or date.

## Endpoint

```
POST https://api.rapidchargeback.com/api/v1/capture/events
```

## Authentication

Basic Auth with `client_id:client_secret`. See [Authentication](https://doc.rapidchargeback.com/en/referencia/autenticacao/).

```
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json
```

Do not use the publishable token here. The company comes from the credential, which is why this channel can write device data without the validation required in the browser.

## Request body

| Field | Type | Description | Required |
|---|---|---|---|
| `merchant_id` | string (UUID) | Merchant the event belongs to, within your company (see [List merchants](https://doc.rapidchargeback.com/en/canais/merchants/listar-merchants/)) | Yes |
| `type` | string (enum) | The four browser types plus `delivery_confirmation`, `scan` and `delivery_gps` | Yes |
| `order_ref` | string | Order identifier in your system, up to 100 characters | Yes |
| `event_id` | string | Event identifier, up to 64 characters. If omitted, Rapid generates one | No |
| `payload` | object | Data about the fact, with a closed list of fields | No |
| `captured_at` | string (ISO 8601) | When the fact happened. If omitted, the time of the call is used | No |

The full reference of accepted values is in [Types and payload](https://doc.rapidchargeback.com/en/canais/capture/payload/).

Three differences from the browser channel:

- `merchant_id` is required, because the credential identifies the company and not the merchant
- `captured_at` is respected, so a batch routine can send the real time of each fact
- `event_id` is optional, but send your own: it is what makes resending safe

## Idempotency

Resending the same call with the same `event_id` does not duplicate the evidence. That is the expected behavior on a retry after a timeout or a lost response.

If you omit `event_id`, each call generates a new identifier, and the same call repeated becomes two records.

## Validations

| Rule | Response |
|---|---|
| Missing or invalid credential | `401 UNAUTHORIZED` |
| `merchant_id` missing | `422 VALIDATION_ERROR`: *merchant_id required* |
| `type` missing or outside the enum | `422 VALIDATION_ERROR`: *invalid_type* |
| `order_ref` missing, empty or over 100 characters | `422 VALIDATION_ERROR`: *invalid_order_ref* |
| `event_id` over 64 characters | `422 VALIDATION_ERROR`: *invalid_event_id* |
| `payload` text field over 512 characters | `422 VALIDATION_ERROR`: *payload_too_large* |

A `merchant_id` from another company does not cause an error in the call: the event is accepted and discarded at correlation, because the transaction is looked up within your company. The same goes for a nonexistent `order_ref`.

## Request example

Confirmed delivery:

```bash
curl -X POST https://api.rapidchargeback.com/api/v1/capture/events \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "00000000-0000-0000-0000-000000000001",
    "type": "delivery_confirmation",
    "order_ref": "TXN-2026-001",
    "event_id": "entrega-TXN-2026-001",
    "payload": { "carrier": "correios", "tracking": "AA123456789BR" },
    "captured_at": "2026-04-03T11:20:00Z"
  }'
```

Delivery coordinate:

```bash
curl -X POST https://api.rapidchargeback.com/api/v1/capture/events \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "00000000-0000-0000-0000-000000000001",
    "type": "delivery_gps",
    "order_ref": "TXN-2026-001",
    "event_id": "gps-TXN-2026-001",
    "payload": { "lat": -23.5614, "lng": -46.6559 },
    "captured_at": "2026-04-03T11:20:00Z"
  }'
```

## Response examples

### Success (202)

```json
{ "accepted": true }
```

`202` means the event entered the queue. Correlation with the transaction happens later, through `order_ref`.

### Error: missing credential (401)

```json
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid Authorization header"
  }
}
```

### Error: missing `merchant_id` (422)

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "merchant_id required"
  }
}
```

### Error: invalid type (422)

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "invalid_type"
  }
}
```

## Capture or evidence

Both channels record a fact on a transaction, and the choice is simple:

| Situation | Use |
|---|---|
| The transaction is already at Rapid and you have its UUID | [`POST /evidence`](https://doc.rapidchargeback.com/en/canais/evidence/registrar-evidencia/) |
| You only have your own order identifier, or the fact happens before the transaction is sent | this endpoint |
| The fact needs a field outside the closed payload list | [`POST /evidence`](https://doc.rapidchargeback.com/en/canais/evidence/registrar-evidencia/), which accepts a free-form payload |

## Next steps

- [Types and payload](https://doc.rapidchargeback.com/en/canais/capture/payload/)
- [Install the snippet](https://doc.rapidchargeback.com/en/canais/capture/instalar-o-snippet/)
- [Response codes](https://doc.rapidchargeback.com/en/referencia/codigos-de-resposta/)