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
Section titled “Endpoint”https://api.rapidchargeback.com/api/v1/capture/eventsAuthentication
Section titled “Authentication”Basic Auth with client_id:client_secret. See Authentication.
Authorization: Basic base64(client_id:client_secret)Content-Type: application/jsonDo 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
Section titled “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 or number | Order identifier in your system, up to 100 characters | Yes |
event_id | string or number | 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_idis required, because the credential identifies the company and not the merchantcaptured_atis respected, so a batch routine can send the real time of each factevent_idis optional, but send your own: it is what makes resending safe
Idempotency
Section titled “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.
To fix an event sent with the wrong order_ref, or one that was discarded because the transaction arrived after the correlation window, resend it with the same event_id and the right order_ref: the new send replaces the previous one. If the previous one is still being processed, the response is 503; resend after Retry-After. An event that has already become evidence is not replaced.
If you omit event_id, each call generates a new identifier, and the same call repeated becomes two records.
Validations
Section titled “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 |
device_id over 100 characters, device_fingerprint over 255 or another payload text field over 512 | 422 VALIDATION_ERROR: payload_too_large |
merchant_id that is not from your company | 422 VALIDATION_ERROR: invalid_merchant_id |
captured_at that is not an ISO 8601 date, or more than 5 minutes in the future | 422 VALIDATION_ERROR: invalid_captured_at |
| Merchant with too many server events waiting for the transaction (ceiling separate from the browser) | 429 TOO_MANY_PENDING_EVENTS |
| Capture temporarily unavailable | 503 CAPTURE_TEMPORARILY_UNAVAILABLE, with Retry-After |
On a 503, resend the event after the number of seconds in the Retry-After header. With the same event_id, a resend never duplicates the evidence.
A nonexistent order_ref does not cause an error in the call: the event is accepted and discarded at correlation if none of your transactions has that identifier.
Request example
Section titled “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
Section titled “Response examples”Success (202)
Section titled “Success (202)”{ "accepted": true }202 means the event entered the queue. Correlation with the transaction happens later, through order_ref.
Error: missing credential (401)
Section titled “Error: missing credential (401)”{ "error": { "code": "UNAUTHORIZED", "message": "Missing or invalid Authorization header" }}Error: missing merchant_id (422)
Section titled “Error: missing merchant_id (422)”{ "error": { "code": "VALIDATION_ERROR", "message": "merchant_id required" }}Error: invalid type (422)
Section titled “Error: invalid type (422)”{ "error": { "code": "VALIDATION_ERROR", "message": "invalid_type" }}Capture or evidence
Section titled “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 |