Record a payment or refund

Send a normalized server-side payment with a stable provider transaction ID.

POST/api/v1/webhooks/payment

Access: Workspace API key · server only · Permission details

JSON request body

JSON request fields
Field	Type	Description
`siteId`Required	`string`	Website ID, not a domain.
`provider`	`string`	Supported provider label; do not send an arbitrary custom string. Values: stripe, shopify, lemonsqueezy, polar, woocommerce, paddle, paypal. Default: `stripe`.
`externalTxId`Required	`string`	Stable transaction ID. Deduplication uses website, provider and this ID.
`amountCents`Required	`integer`	Integer cents. Refunds are stored as negative absolute amounts.
`currency`	`string`	Three-letter transaction currency. Default: `USD`.
`txType`	`string`	Transaction type. Values: one_time, subscription_new, subscription_renewal, refund. Default: `one_time`.
`visitorId`	`string`	Observed visitor ID, when available.
`customerEmail`	`string`	Email for matching a previously identified visitor.
`customerName`	`string`	Optional customer name.

Request examples

Examples run from your server or terminal. Configure ATTRIBOO_TOKEN privately for authenticated requests. Replace example website IDs and values with your own. The examples make real requests when you run them.

cURL request

curl -X POST "https://www.attriboo.com/api/v1/webhooks/payment" \
  -H "Authorization: Bearer $ATTRIBOO_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "siteId": "site_example",
  "provider": "woocommerce",
  "externalTxId": "order_123",
  "amountCents": 5000,
  "currency": "USD",
  "txType": "one_time",
  "visitorId": "v_example"
}'

Response

Illustrative response. This endpoint returns raw JSON. Optional coverage, notes and continuation fields vary by report.

Response fields
Field	Type	Description
`ok`	`boolean`	Whether the request succeeded.
`attributedToVisitor`	`string \| null`	Resolved visitor ID or null.

JSON response

{
  "ok": true,
  "attributedToVisitor": "v_example"
}

Record a partial refund

cURL request

curl -X POST "https://www.attriboo.com/api/v1/webhooks/payment" \
  -H "Authorization: Bearer $ATTRIBOO_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "siteId": "site_example",
  "provider": "woocommerce",
  "externalTxId": "refund_123_1",
  "amountCents": 1000,
  "currency": "USD",
  "txType": "refund",
  "visitorId": "v_example"
}'

JSON response

{
  "ok": true,
  "attributedToVisitor": "v_example"
}

Behavior and limits

Response uses { ok, attributedToVisitor }, not the report status/data envelope. Errors use { error: string }.

Unmatched payments stay unattributed. No transaction timestamp parameter is supported: this endpoint is not a historical-import API.

Use stable IDs when retrying. Give a separate refund its own stable ID so it does not overwrite the original sale. Avoid sending the same payment through overlapping native and custom paths.

Built-in payment connections manage their own provider-specific webhooks. This endpoint accepts the normalized fields shown here, not native provider payloads.

HTTP status	Meaning
400	Missing fields, unsupported provider/type, or payment could not be recorded.
401	Invalid or missing workspace key.
404	Unknown website.

Errors and retries OpenAPI JSON