Skip to content

↑↓ navigate ↵ open Ctrl↵ new tab esc close

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.

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

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.

FieldTypeDescriptionRequired
merchant_idstring (UUID)Merchant the event belongs to, within your company (see List merchants)Yes
typestring (enum)The four browser types plus delivery_confirmation, scan and delivery_gpsYes
order_refstring or numberOrder identifier in your system, up to 100 charactersYes
event_idstring or numberEvent identifier, up to 64 characters. If omitted, Rapid generates oneNo
payloadobjectData about the fact, with a closed list of fieldsNo
captured_atstring (ISO 8601)When the fact happened. If omitted, the time of the call is usedNo

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

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.

RuleResponse
Missing or invalid credential401 UNAUTHORIZED
merchant_id missing422 VALIDATION_ERROR: merchant_id required
type missing or outside the enum422 VALIDATION_ERROR: invalid_type
order_ref missing, empty or over 100 characters422 VALIDATION_ERROR: invalid_order_ref
event_id over 64 characters422 VALIDATION_ERROR: invalid_event_id
device_id over 100 characters, device_fingerprint over 255 or another payload text field over 512422 VALIDATION_ERROR: payload_too_large
merchant_id that is not from your company422 VALIDATION_ERROR: invalid_merchant_id
captured_at that is not an ISO 8601 date, or more than 5 minutes in the future422 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 unavailable503 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.

Confirmed delivery:

Terminal window
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:

Terminal window
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"
}'
{ "accepted": true }

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

{
"error": {
"code": "UNAUTHORIZED",
"message": "Missing or invalid Authorization header"
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "merchant_id required"
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "invalid_type"
}
}

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

SituationUse
The transaction is already at Rapid and you have its UUIDPOST /evidence
You only have your own order identifier, or the fact happens before the transaction is sentthis endpoint
The fact needs a field outside the closed payload listPOST /evidence, which accepts a free-form payload