Send an event from the server

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.

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)	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.

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:

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:

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)

{ "accepted": true }

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

Error: missing credential (401)

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

Error: missing `merchant_id` (422)

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

Error: invalid type (422)

{
  "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`
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`, which accepts a free-form payload