Payments API

Record payments from any provider with POST /api/payment and optional visitor attribution fields.

Use the Payments API when you process orders outside Stripe/Polar — WordPress plugins, Paddle webhooks, manual backends — and still want revenue in XPmetric with optional visitor attribution.

Get your API secret

Open Settings → Integrations for the site.
Generate an API secret (xpm_sk_…) — shown once; store it securely.
Never use your public site token (data-site in p.js) for this endpoint.

Record a payment

curl -X POST https://xpmetric.com/api/payment \
  -H "Authorization: Bearer xpm_sk_YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 2900,
    "currency": "usd",
    "external_id": "order_123",
    "type": "one_time",
    "visitor_id": "VISITOR_HASH_FROM_xpmetric.v",
    "session_id": "SESSION_ID_FROM_xpmetric.s"
  }'

Request body

Field	Required	Description
`amount_cents`	Yes	Integer cents (negative for refunds)
`currency`	Yes	ISO code, e.g. `usd`
`external_id`	Yes	Your unique charge/order id
`type`	No	`new`, `renewal`, `one_time`, `refund` (default `one_time`)
`visitor_id`	No	`window.xpmetric.v` at purchase time
`session_id`	No	`window.xpmetric.s` at purchase time
`occurred_at`	No	ISO 8601 timestamp (default now)

Auth & limits

Header: Authorization: Bearer xpm_sk_…
Rate limit: 120 requests/minute per site
Idempotent on (source, external_id) — safe to retry

Attribution

When visitor_id is set, XPmetric looks up first-touch channel, referrer, UTM, and landing path from ClickHouse and stores them on the PaymentEvent row.

XP

New non-refund payments award +100 XP to the site (same as Stripe/Polar sync).

Stripe Checkout — zero-code path for Stripe
Custom goals — track the conversion event before payment