Send an event from the browser
Records a capture event using the publishable token. It is the endpoint the snippet calls, and you can call it directly if you prefer not to load the script.
Endpoint
Section titled “Endpoint”https://api.rapidchargeback.com/api/v1/capture/{token}/eventsAuthentication
Section titled “Authentication”None. The publishable token in the URL identifies the merchant.
Content-Type: application/jsonThe snippet sends the same JSON as text/plain, which the browser sends without a CORS preflight. Both types are accepted.
The token is not a secret and can stay in your store’s HTML. It only allows writing, and the event only becomes evidence if it matches a real order of yours.
URL parameters
Section titled “URL parameters”| Field | Type | Description |
|---|---|---|
token | string | Merchant’s publishable token, generated in the dashboard |
Request body
Section titled “Request body”| Field | Type | Description | Required |
|---|---|---|---|
type | string (enum) | checkout, terms_acceptance, access_log or usage_log | Yes |
order_ref | string or number | Order identifier in your system, up to 100 characters | Yes |
event_id | string or number | Event identifier, generated by you, up to 64 characters | Yes |
payload | object | Data about the fact, with a closed list of fields | No |
The full reference of accepted values is in Types and payload.
Two points specific to this channel:
event_idis required here. Generate a UUID per eventcaptured_atsent in the body is ignored. Rapid records the arrival time. To send the time of the fact, use the server channel
The delivery_confirmation, scan and delivery_gps types do not exist in this channel: they are facts of your operation, not of the buyer’s browser.
Rate limit
Section titled “Rate limit”120 requests per minute, per source IP and token. That is plenty for a real checkout and tight for anyone using the token outside your site. Counting by token too keeps buyers of different stores behind the same IP (mobile network) from sharing one limit.
On top of that, each merchant has a ceiling of browser events waiting for the transaction to show up. Above it, the event returns 429 TOO_MANY_PENDING_EVENTS until the queue moves. Normal use does not come close: the ceiling exists for the case of someone sending made-up orders with your token. Sending from the server has a separate ceiling, so that abuse does not block the events your backend sends.
Validations
Section titled “Validations”| Rule | Response |
|---|---|
| Unknown or inactive token, or token without a merchant | 404 NOT_FOUND |
type missing, or not one of the four accepted in this channel | 422 VALIDATION_ERROR: invalid_type |
order_ref missing, empty or over 100 characters | 422 VALIDATION_ERROR: invalid_order_ref |
event_id missing, empty or 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 |
| Event coming from a site that is not among the sites the token works on (see) | 403 ORIGIN_NOT_ALLOWED |
| Over 120 requests per minute | 429 Too Many Requests |
| Merchant with too many events waiting for the transaction | 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.
There is no error for a nonexistent order_ref. The event is accepted, stays in the queue and is discarded if no transaction matches within the correlation window. See Correlation window.
Request example
Section titled “Request example”curl -X POST https://api.rapidchargeback.com/api/v1/capture/your_publishable_token/events \ -H "Content-Type: application/json" \ -d '{ "type": "terms_acceptance", "order_ref": "TXN-2026-001", "event_id": "019b0000-1111-7000-8000-000000000001", "payload": { "url": "https://loja.exemplo.com/checkout" } }'Checkout event with device identification:
curl -X POST https://api.rapidchargeback.com/api/v1/capture/your_publishable_token/events \ -H "Content-Type: application/json" \ -d '{ "type": "checkout", "order_ref": "TXN-2026-001", "event_id": "019b0000-1111-7000-8000-000000000002", "payload": { "device_id": "8kJ2mQvR1nZxYb0T", "device_fingerprint": "8kJ2mQvR1nZxYb0T", "fp": "pro", "fp_request_id": "1712059781234.Xk9Lp2" } }'Response examples
Section titled “Response examples”Success (202)
Section titled “Success (202)”{ "accepted": true }202 means the event entered the queue, not that it has already become evidence. Correlation with the transaction happens later.
Error: unknown token (404)
Section titled “Error: unknown token (404)”{ "error": { "code": "NOT_FOUND" } }Error: type not available in this channel (422)
Section titled “Error: type not available in this channel (422)”{ "error": { "code": "VALIDATION_ERROR", "message": "invalid_type" }}Error: missing event_id (422)
Section titled “Error: missing event_id (422)”{ "error": { "code": "VALIDATION_ERROR", "message": "invalid_event_id" }}Error: payload field too long (422)
Section titled “Error: payload field too long (422)”{ "error": { "code": "VALIDATION_ERROR", "message": "payload_too_large" }}