Types and payload

Reference of the values accepted in the two capture channels. Applies to POST /capture/{token}/events and POST /capture/events.

Event fields

Field	Type	Limit	Required
type	string (enum)	see table below	Yes
order_ref	string	100 characters	Yes
event_id	string	64 characters	Yes in the browser, optional on the server
payload	object	see accepted fields	No
captured_at	string (ISO 8601)	-	No, and only the server channel uses it
merchant_id	string (UUID)	-	Server channel only

order_ref

It is the order identifier in your system, and it is the only thing that links the event to a transaction. Rapid looks, within your company and the given merchant, for:

1. a transaction with external_id equal to order_ref
2. if not found, a transaction with order_number equal to order_ref

Always send the same value you used in external_id when creating the transaction. A wrong order_ref does not cause an error in the call: the event is accepted, finds no transaction and is discarded after the correlation window.

event_id

Event identifier, generated by you. It works as an idempotency key: resending the same event_id for the same merchant does not create duplicate evidence.

In the browser channel it is required (the snippet generates a UUID per event). In the server channel, if you omit it, Rapid generates one. Send your own whenever you might resend the same call, that is what guarantees idempotency.

Do not use : in event_id. The character is removed before internal use, which would make two different ids collide.

captured_at

When the fact happened, in ISO 8601.

Channel	Behavior
Browser	ignored. Rapid records the time the event arrived
Server	used as sent. If omitted, the time of the call is used

If the fact happened before the call (a nightly batch process, for example), use the server channel and send captured_at.

type values

Value	What it records	Browser	Server
checkout	Purchase completion, with device data	Yes	Yes
terms_acceptance	Acceptance of terms, policy or contract	Yes	Yes
access_log	Access to the product or the logged-in area	Yes	Yes
usage_log	Actual use of the product or service	Yes	Yes
delivery_confirmation	Delivery confirmed	No	Yes
scan	Tracking code scan in transit	No	Yes
delivery_gps	Delivery coordinate	No	Yes

The last three exist only in the server channel: they are facts of your operation, not of the buyer’s browser. Using them in the browser channel returns 422 invalid_type.

payload fields

payload has a closed list of fields. A key outside the list is silently discarded, with no error, so check the spelling.

Field	Type	Use in
device_id	string	checkout
device_fingerprint	string	checkout
fp	string	checkout, indicates the origin of the identification (pro or fallback)
fp_request_id	string	checkout, required to validate the identification
url	string	terms_acceptance, access_log, usage_log
note	string	any type
carrier	string	delivery_confirmation, scan
tracking	string	delivery_confirmation, scan
lat	number	delivery_gps
lng	number	delivery_gps

Rules:

• scalar values only (string, number, boolean). Objects and lists are discarded
• a string over 512 characters returns 422 payload_too_large
• a missing or empty payload is accepted

The checkout event

checkout is the only type that writes data directly to the transaction, and not just as an attached record. It fills in the transaction’s device and IP only when those fields are empty: an earlier capture is never overwritten.

What each channel can write:

Transaction data	Browser	Server
device_id	does not write	writes
device_fingerprint	only with validated identification	writes
ip_address	only with validated identification	writes

The difference exists because the browser token is publishable: anyone who has it can send events. Unvalidated data never touches the fields that back the defense.

Validated identification means: you sent fp_request_id and device_id in the payload, and Rapid confirmed the pair against Fingerprint on the server side. In that case the event also generates a device verification record, with bot, VPN and incognito window signals. Without fp_request_id, the event still counts as a record, just without the device part.

Each fp_request_id is valid for one transaction. The same pair reused in another order is treated as a replay and ignored.

Correlation window

The event can arrive before the transaction exists. It stays in the queue and is retried for about 68 hours, at increasing intervals. Once the window passes with no matching transaction, the event is discarded.

In practice: sending checkout at the exact moment of the purchase works, even if your routine only sends the transaction to Rapid hours later.

Next steps

• Install the snippet
• Send an event from the browser
• Send an event from the server