Record evidence

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.

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:

// 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

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:

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)

{
  "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)

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

Error: invalid `type` (422)

{
  "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)

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

Error: payload over the cap (422)

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