Skip to content

↑↓ navigate ↵ open Ctrl↵ new tab esc close

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.

POST https://api.rapidchargeback.com/api/v1/capture/{token}/events

None. The publishable token in the URL identifies the merchant.

Content-Type: application/json

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

FieldTypeDescription
tokenstringMerchant’s publishable token, generated in the dashboard
FieldTypeDescriptionRequired
typestring (enum)checkout, terms_acceptance, access_log or usage_logYes
order_refstring or numberOrder identifier in your system, up to 100 charactersYes
event_idstring or numberEvent identifier, generated by you, up to 64 charactersYes
payloadobjectData about the fact, with a closed list of fieldsNo

The full reference of accepted values is in Types and payload.

Two points specific to this channel:

  • event_id is required here. Generate a UUID per event
  • captured_at sent 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.

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.

RuleResponse
Unknown or inactive token, or token without a merchant404 NOT_FOUND
type missing, or not one of the four accepted in this channel422 VALIDATION_ERROR: invalid_type
order_ref missing, empty or over 100 characters422 VALIDATION_ERROR: invalid_order_ref
event_id missing, empty or 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
Event coming from a site that is not among the sites the token works on (see)403 ORIGIN_NOT_ALLOWED
Over 120 requests per minute429 Too Many Requests
Merchant with too many events waiting for the transaction429 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.

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.

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

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

202 means the event entered the queue, not that it has already become evidence. Correlation with the transaction happens later.

{ "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": {
"code": "VALIDATION_ERROR",
"message": "invalid_event_id"
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "payload_too_large"
}
}