# Record evidence

> Attaches an evidence record to a transaction already sent to Rapid.

Página: https://doc.rapidchargeback.com/en/canais/evidence/registrar-evidencia/

Attaches an evidence record to a transaction already sent to Rapid.

## Endpoint

```
POST https://api.rapidchargeback.com/api/v1/evidence
```

## 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
```

## Request body

| Field | Type | Description | Required |
|---|---|---|---|
| `transaction_id` | string (UUID) | Transaction ID at Rapid, returned when you created it | Yes, or `transaction_ref` |
| `transaction_ref` | object | Alternative to `transaction_id`: points to the transaction by **your** identifier. See below | Yes, or `transaction_id` |
| `type` | string (enum) | Nature of the recorded fact. Accepted values below | Yes |
| `payload` | object | The data about the fact. Free format, 32 KB cap | Yes |
| `captured_at` | string (ISO 8601 with offset) | When the fact happened in your system, not when you send it | Yes |

Send **one** of the two: `transaction_id` or `transaction_ref`. If both are missing, the response is `422`.

### `transaction_ref` field

| Field | Type | Description | Required |
|---|---|---|---|
| `external_source` | string | The same source you used when creating the transaction (e.g. `"shopify"`) | Yes |
| `external_id` | string | The same ID from your system you used when creating the transaction | Yes |

### `type` values

| Value | When to use |
|---|---|
| `terms_acceptance` | Customer accepted terms, policy or contract |
| `access_log` | Customer accessed the product or the logged-in area |
| `delivery_confirmation` | Delivery confirmed |
| `usage_log` | Actual use of the product or service |
| `communication` | Exchange with the customer (email, chat, ticket) |
| `other` | Any fact that does not fit the previous ones |

### `payload` field

Free format: you choose the keys. The only rule is the **32 KB cap** on the serialized JSON: evidence is a record, not a file.

Suggestions by type, not required:

```json
// terms_acceptance
{ "accepted_at": "2026-04-01T15:29:40Z", "terms_version": "v3.2", "ip": "203.0.113.10" }

// access_log
{ "first_access_at": "2026-04-01T16:02:11Z", "sessions": 3 }

// delivery_confirmation
{ "carrier": "correios", "tracking": "AA123456789BR", "delivered_at": "2026-04-03T11:20:00Z" }
```

## Validations

| Rule | Response |
|---|---|
| Neither `transaction_id` nor `transaction_ref` | `422 VALIDATION_ERROR`: *transaction_id or transaction_ref is required* |
| `type` outside the enum | `422 VALIDATION_ERROR` with the list of accepted values |
| `captured_at` without a time zone offset | `422 VALIDATION_ERROR`: *Invalid datetime* |
| Serialized `payload` over 32 KB | `422 VALIDATION_ERROR`: *payload exceeds 32KB: evidence is a record, not a file* |
| Transaction does not exist, or is not from your company | `404 TRANSACTION_NOT_FOUND` |
| Missing or invalid credential | `401 UNAUTHORIZED` |

The transaction is always resolved **within your company**. A transaction ID from another company returns `404`, never `403`: we do not confirm the existence of someone else's data.

## Request example

```bash
curl -X POST https://api.rapidchargeback.com/api/v1/evidence \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "00000000-0000-0000-0000-000000000042",
    "type": "terms_acceptance",
    "payload": {
      "accepted_at": "2026-04-01T15:29:40Z",
      "terms_version": "v3.2",
      "ip": "203.0.113.10"
    },
    "captured_at": "2026-04-01T15:29:41Z"
  }'
```

By your own identifier, without storing Rapid's UUID:

```bash
curl -X POST https://api.rapidchargeback.com/api/v1/evidence \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_ref": { "external_source": "shopify", "external_id": "TXN-2026-001" },
    "type": "access_log",
    "payload": { "first_access_at": "2026-04-01T16:02:11Z", "sessions": 3 },
    "captured_at": "2026-04-01T16:02:12Z"
  }'
```

## Response examples

### Success (201)

```json
{
  "data": {
    "id": "00000000-0000-0000-0000-0000000000e1",
    "transaction_id": "00000000-0000-0000-0000-000000000042",
    "type": "terms_acceptance"
  }
}
```

The returned `id` is the evidence's. Store it only if you are going to reference it; to list, the key is the transaction.

### Error: missing transaction reference (422)

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "transaction_id or transaction_ref is required"
  }
}
```

### Error: invalid `type` (422)

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid enum value. Expected 'terms_acceptance' | 'access_log' | 'delivery_confirmation' | 'usage_log' | 'communication' | 'other', received 'nao_existe'"
  }
}
```

### Error: transaction not found (404)

```json
{
  "error": {
    "code": "TRANSACTION_NOT_FOUND",
    "message": "Transaction not found"
  }
}
```

### Error: payload over the cap (422)

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "payload exceeds 32KB: evidence is a record, not a file"
  }
}
```

## Next steps

- [List evidence](https://doc.rapidchargeback.com/en/canais/evidence/consultar-evidencias/)
- [Response codes](https://doc.rapidchargeback.com/en/referencia/codigos-de-resposta/)