> ## Documentation Index
> Fetch the complete documentation index at: https://docs.affixo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect any payment processor

> A step-by-step guide for merchants who take payments outside Stripe: report sales, refunds and disputes from your server, with recipes for PayPal, Square, Paddle, Lemon Squeezy and WooCommerce.

Affixo connects to Stripe directly. For every other processor, it works the other way round: **your server tells Affixo about each sale, refund and dispute**. Your processor already sends your server a webhook when money moves. You pass the useful parts on to Affixo with one small API call, and Affixo works out which affiliate earned the commission.

```mermaid theme={null}
flowchart TD
  A["Affiliate link"] --> B["Your site with the Affixo snippet"]
  B --> C["Checkout at your processor (visitor id carried along)"]
  C --> D["Your server's webhook handler"]
  D --> E["Affixo /v1/track/*"]
  E --> F["Commission"]
```

This page is the guided path. For every field and edge case, see [No Stripe: book sales from your server](https://docs.affixo.dev/integrate.md#no-stripe-book-sales-from-your-server) and the [API reference](https://docs.affixo.dev/api-reference).

## Before you start

You need:

* **The snippet installed** on every page of your site, as described in [Integrate Affixo tracking](https://docs.affixo.dev/integrate.md).
* **A program with a commission set**, so there is something to pay.
* **Someone who can run server code**, even a small function. Any language works: you only make HTTPS calls.

> [!NOTE]
>
> **Using Stripe?** Use the native Stripe connection instead (**Settings → Payments & products**). It needs no code. A workspace takes its sales from Stripe or from this API, never both, so pick one processor per account.

## Step 1: Create a secret key

1. Open **Settings → Developer & API**.
2. Create a key with the `track` scope. (`write` also works, but `track` is all you need.)
3. Copy the key when it is created and keep it somewhere safe. Affixo stores keys as hashes, so treat it like a password you can't look up later.
4. Store it as a server environment variable, for example `AFFIXO_API_KEY`.

You can also create the key from the setup screen. On **Settings → Payments & products**, choose **Another processor, or my own backend**, then **Create a key for sales**. It shows the key once and stores only its fingerprint, and the same screen lists the calls from this guide ready to paste. You can switch back to Stripe until your first real sale.

> [!WARNING]
>
> This key can create and reverse commissions. Keep it on your server only: never in your page, your mobile app or a public repository. See [Authentication](https://docs.affixo.dev/authentication.md).

## Step 2: Carry the visitor id to your server

The snippet remembers each visitor in their browser. To credit the right affiliate, your server needs that visitor's id when the payment arrives. The trick is to read the id on your page, send it to your server with the order, and store it in a free-form field your processor lets you attach to the payment. The processor then hands it back in its webhook.

```js theme={null}
// In the browser, when the visitor starts checkout
const visitorId = await window.Affixo.ready(); // resolves to the visitor id
// Send visitorId to your server along with the order,
// or write it into your processor's free-form field (see the table below).
```

`Affixo.getVisitorId()` returns the same id without waiting. Use `ready()` when you need to be sure it is there. See [sa.js](https://docs.affixo.dev/sa-js.md).

Where to put it, by processor:

| Processor | Free-form field to use |
| - | - |
| PayPal | `custom_id` on the purchase unit when you create the order |
| Square | Payment `reference_id` (max 40 characters), or `note` (for Payment Links, `payment_note`) |
| Paddle Billing | `custom_data` on the checkout (comes back as `data.custom_data.<your key>` on the transaction) |
| Lemon Squeezy | Checkout URL parameter `checkout[custom][visitor_id]` (comes back as `meta.custom_data.visitor_id`) |
| WooCommerce | Order meta (we use the key `affixo_visitor_id`), saved when checkout creates the order |

The processor usually hands it back in its webhook. The recipes further down show where to find it for each one, and what to confirm in a sandbox.

## Step 3: Report each paid sale

When your processor confirms a payment, call `POST /v1/track/sale` from your server.

```bash curl theme={null}
curl https://go.affixo.dev/v1/track/sale \
  -H "Authorization: Bearer $AFFIXO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "pay_8f3k2",
    "visitor_id": "v_abc",
    "email": "buyer@example.com",
    "amount_cents": 9900,
    "currency": "usd"
  }'
```

```js node theme={null}
// A small helper you can reuse for every call
async function affixo(action, body) {
  const res = await fetch(`https://go.affixo.dev/v1/track/${action}`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.AFFIXO_API_KEY}`, // server only
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(body),
  })
  if (!res.ok) {
    // Include the status and body so a failed call is never silent
    throw new Error(`Affixo ${action} failed: ${res.status} ${await res.text()}`)
  }
  return res.json()
}

// Inside your webhook handler, after you have verified the signature
// and picked out a paid payment:
await affixo('sale', {
  external_id: payment.id,        // the processor's payment or order id
  visitor_id:  stored.visitorId,  // the id you carried through checkout
  email:       payment.email,
  amount_cents: payment.amountInSmallestUnit,
  currency:    payment.currency,
})
```

The rules that matter:

* **`external_id` is the processor's payment or order id.** Use the same id on every later call for that payment (refund, chargeback). Retries with the same id never book a second commission.
* **Send the amount one way, never both.** `amount_cents` is in the currency's smallest unit (`9900` is \$99.00 in USD, 9,900 yen in JPY). `amount` is in major units (`99.00`). Sending both returns `400 amount_conflict`. See the amount notes in [the reference](https://docs.affixo.dev/integrate.md#no-stripe-book-sales-from-your-server).
* **Numbers, not strings.** `amount_cents`, `refunded_amount` and `refunded_amount_cents` must be numbers (convert with `Number(...)`). `amount` also accepts a plain numeric string such as `"29.35"`.
* **Send the buyer's `email`** when you have it. It lets Affixo match later payments from the same customer.
* **Report only paid sales.** Call it from the payment-confirmed event, not from checkout start.
* **Don't lose a failed call.** The helper above throws on any non-2xx response. If you answer your processor before calling Affixo, queue the call and retry it on a `429` or `5xx`, because the processor won't resend it.
* **Testing in a sandbox?** Send `"is_test": true` (for example from an environment flag) and start from a `?_sa_test=1` visit. A live sale only matches live clicks. See [Check that it works](#check-that-it-works).

### Subscriptions, interval and products

For recurring billing, send the same `subscription_id` on every payment, plus `billing_interval` (`one_time`, `month` or `year`). Each renewal goes to the affiliate who referred the first payment. Send `subscription_id` and `customer_id` on the first call for each payment, because a later call with the same `external_id` won't add them.

To pay different rates per product, send `product_id` (your own id for the plan) and, optionally, `product_name` as a label. Products are registered separately and never automatically. Details are in [Subscriptions and renewals](https://docs.affixo.dev/integrate.md#subscriptions-and-renewals) and [Products](https://docs.affixo.dev/integrate.md#products).

```json theme={null}
{
  "external_id": "pay_8f3k3",
  "amount_cents": 4900,
  "currency": "usd",
  "subscription_id": "sub_123",
  "customer_id": "cus_456",
  "billing_interval": "month",
  "product_id": "plan_pro",
  "product_name": "Pro plan"
}
```

## Step 4: Report refunds and disputes

```bash curl theme={null}
# Refund: send the TOTAL refunded so far on that payment
curl https://go.affixo.dev/v1/track/refund \
  -H "Authorization: Bearer $AFFIXO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "pay_8f3k2", "refunded_amount_cents": 2500, "currency": "usd" }'

# A dispute opens: reverse the commission
curl https://go.affixo.dev/v1/track/chargeback \
  -H "Authorization: Bearer $AFFIXO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "pay_8f3k2" }'

# You win the dispute: restore it
curl https://go.affixo.dev/v1/track/dispute_won \
  -H "Authorization: Bearer $AFFIXO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "pay_8f3k2" }'
```

```js node theme={null}
await affixo('refund',      { external_id: payment.id, refunded_amount_cents: totalRefundedCents, currency: payment.currency })
await affixo('chargeback',  { external_id: payment.id })
await affixo('dispute_won', { external_id: payment.id })
```

* **`/refund` takes the running total.** If you refunded $20 and then $30, the second call sends $50, not $30. Below the sale amount it is a partial refund and the commission shrinks in proportion. Leave the amount out for a full refund. A running total also means a repeated or out-of-order webhook does no harm.
* **Send `currency` with every refund too** (it must match the sale's). A refund with an amount that arrives before its sale needs it, or you get `422 currency_required`. A different currency from the sale's gets `422 currency_mismatch`.

> [!WARNING]
>
> **Send the refund on the same basis as the sale.** If you reported the sale before tax (or before tip or shipping) but your processor reports refunds including them, scale the refund first: refunded × (the sale amount you reported ÷ the processor's total), rounded. Or report the processor's full total as the sale amount, which pays commission on the tax too. Example: you reported a sale of 1000 (before tax), the processor's total is 1200, and half is refunded (600 in the processor's figures). Send 500 (600 × 1000 ÷ 1200), not 600. Sending 600 against a sale of 1000 would claw back 60% instead of 50%.

* **`/chargeback` and `/dispute_won` need only the `external_id`.** A won dispute restores the commission to what it was before the chargeback. An earlier partial refund still counts.

Full behaviour is in [Refunds](https://docs.affixo.dev/integrate.md#refunds) and [Chargebacks and won disputes](https://docs.affixo.dev/integrate.md#chargebacks-and-won-disputes).

## Check that it works

Affixo credits a sale by finding a click from the same visitor. Test sales only look at **test clicks**, and live sales only look at **live clicks**. They never mix. So a test sale needs a test visit first.

1. **Make a test visit.** In a browser, open your site through one of your affiliates' referral links with `_sa_test=1` added, for example `https://yoursite.com/?ref=jane&_sa_test=1`. The snippet records that visit as a test click. The test flag lasts 30 minutes in that browser. See [Test links](https://docs.affixo.dev/sa-js.md#test-links).
2. **Read the visitor id** in the same browser. Open the browser console and run `await Affixo.ready()`.
3. **Send a test sale** from your terminal, with `is_test: true` and a fresh `external_id`:

```bash theme={null}
curl https://go.affixo.dev/v1/track/sale \
  -H "Authorization: Bearer $AFFIXO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "test_001",
    "visitor_id": "PASTE_THE_ID_HERE",
    "amount_cents": 9900,
    "currency": "usd",
    "is_test": true
  }'
```

What the response tells you:

| Response | Meaning |
| - | - |
| `{ "ok": true, "attributed": true, "conversion_id": "..." }` | Affixo found the affiliate and booked the sale. |
| `{ "ok": true, "attributed": false, "visitor_id": "..." }` | The call worked, but no affiliate matched. Two common causes: there is no test click for that visitor id (repeat step 1 and use the id from that browser), or a sandbox sale was sent without `"is_test": true`, so it looked only for live clicks. |
| A `warning` of `"external_id_missing"` | You sent only `amount` and `currency` with no `external_id`. Always send it. |
| `400 external_id_required` | You sent `amount_cents`, or any subscription, customer, product or interval field, without an `external_id`. |
| `400`, `401` or `403` with an `error` code | Fix the request. For example, `amount_conflict` means you sent both `amount` and `amount_cents`, and `insufficient_scope` means the key lacks the `track` scope (it is also returned for connector tokens, which can't report sales). |
| `422 currency_required` or `422 currency_mismatch` | Refund calls only. Send the sale's currency with the refund. |

Test data never reaches payouts, alerts or reports. Use a new `external_id` each time you retest, because a repeated id is treated as the same payment.

> [!TIP]
>
> **Check from the dashboard too.** On **Settings → Payments & products**, the **Check it works** box has two things. **Send a test sale** drops a test sale on Referrals with a test commission. That checks the Affixo side, not your server. **Last sale call received** is how you see your own server's call arrive: send the `is_test` sale above and it appears within a few seconds with a **Test** badge. It only shows calls that booked a sale, so a call whose response says `"attributed": false` won't appear there. Use the response to debug that case.

Once a test sale attributes, run the same flow with your processor's sandbox and a real webhook before you go live. Start from a `?_sa_test=1` visit and send `"is_test": true` for those sandbox sales too, for example from an environment flag.

## Hosted checkouts and payment links

Sometimes you can't add code to the checkout page, for example a hosted payment link. You still have two options:

1. **Carry the visitor id in the processor's free-form field**, where the processor gives you one (see the table in step 2). For a payment link, that usually means adding it to the link's URL or settings. Check your processor's docs for how.
2. **Fall back on the buyer's email.** If no visitor id arrives, Affixo can match the buyer's email to an earlier lead for 365 days, when email matching is enabled in your attribution settings (it is on by default). To make that work, capture the buyer's email as a lead on a signup page before they pay, as described in [Track signups](https://docs.affixo.dev/integrate.md#step-2-track-signups-leads). See [Attribution](https://docs.affixo.dev/attribution.md) for the full order of matching.

Email matching is weaker than a visitor id, so use it as a safety net, not the plan.

## Recipes by processor

We checked the details below against each processor's own developer docs in November 2026. Processors change their events and fields, so confirm each one with a test event in the processor's sandbox before you rely on it. Where something is not confirmed, the recipe says so.

> [accordion] PayPal
>
> Docs: [Webhooks](https://developer.paypal.com/api/rest/webhooks/), [event names](https://developer.paypal.com/api/rest/webhooks/event-names/), [Payments v2](https://developer.paypal.com/api/payments/v2/schema.json), [Orders v2](https://developer.paypal.com/api/orders/v2/schema.json), [Disputes](https://developer.paypal.com/api/customer-disputes/v1/schema.json).
>
> **Event to listen for:** `PAYMENT.CAPTURE.COMPLETED` for one-time payments.
>
> | PayPal | Affixo |
> | - | - |
> | `resource.id` (the capture id) | `external_id` |
> | `resource.amount.value` (a string in major units, such as `"500.00"`) | `amount` (a numeric string is accepted) |
> | `resource.amount.currency_code` | `currency` |
> | `custom_id` you set on the purchase unit | `visitor_id` |
> | Not in the webhook. Look up the order and read `payer.email_address` | `email` |
> | `resource.supplementary_data.related_ids.order_id` | Useful for the order lookup |
>
> The amount is in major units. Zero-decimal currencies such as JPY come back as whole-number strings, and some currencies have three decimals, so pass the value exactly as PayPal sends it.
>
> Whether the webhook's `resource` includes `custom_id` is not confirmed: PayPal's official capture response includes it, but its webhook samples do not. In your sandbox, check the event. If it is missing, fetch the order by its order id and read `custom_id` from the capture there.
>
> ```js theme={null}
> // resource: the "resource" object of a verified PAYMENT.CAPTURE.COMPLETED event
> await affixo('sale', {
>   external_id: resource.id,
>   amount:      resource.amount.value,        // e.g. "500.00", major units
>   currency:    resource.amount.currency_code,
>   visitor_id:  customId,                     // from resource, or from the order lookup
>   email:       payerEmail,                   // from the order lookup
> })
> ```
>
> **Refunds:** listen for `PAYMENT.CAPTURE.REFUNDED`. Here `resource.id` is the refund's id and `resource.amount` is only this refund. The running total is `resource.seller_payable_breakdown.total_refunded_amount` (in PayPal's example, a $20 and then a $30 refund gives a total of 50). The original capture id is in the `links` entry with `rel: "up"`; its href ends in the capture id. Send `external_id` = capture id, `refunded_amount` = `Number(total_refunded_amount.value)` and `currency` = `total_refunded_amount.currency_code`.
>
> **Disputes and chargebacks:** listen for `CUSTOMER.DISPUTE.CREATED` and `CUSTOMER.DISPUTE.RESOLVED`. Send `/chargeback` when a dispute is created. When it resolves, `dispute_outcome.outcome_code` of `RESOLVED_SELLER_FAVOUR` means you won, so send `/dispute_won`. `RESOLVED_BUYER_FAVOUR` means the customer won: do nothing more. The codes `CANCELED_BY_BUYER` and `RESOLVED_WITH_PAYOUT` also exist. If the dispute ended with you keeping the money, send `/dispute_won`. Check each outcome against your PayPal balance in the sandbox. A `dispute_channel` of `EXTERNAL` means the customer went to their bank. To find your sale, the dispute carries a `seller_transaction_id`, but whether that equals the capture id is not confirmed. Check which id the dispute carries in your sandbox and match it to the capture id you stored.
>
> **Subscriptions and renewals:** PayPal Subscriptions payments arrive as `PAYMENT.SALE.COMPLETED`, not `PAYMENT.CAPTURE.COMPLETED`, and refunds as `PAYMENT.SALE.REFUNDED`. We could not confirm the field names in those payloads. Map the sale id to `external_id`, the amount to `amount` and the subscription reference to `subscription_id`, and confirm the field names with a sandbox event. You can set `custom_id` on the subscription (max 127 printable ASCII characters) to carry the visitor id.
>
> **Signature check:** verify each webhook with [PayPal's verification guide](https://developer.paypal.com/api/rest/webhooks/rest/), either through the verify-webhook-signature API or locally from the `paypal-transmission-*` headers.
>
> **Retries and duplicates:** PayPal retries any non-2xx response up to 25 times over 3 days. Whether the event id stays the same across retries is not confirmed, so dedupe on the capture id. Affixo does this for you through `external_id`.

> [accordion] Square
>
> Docs: [Payments webhooks](https://developer.squareup.com/docs/payments-api/webhooks), [Refunds webhooks](https://developer.squareup.com/docs/refunds-api/webhooks), [Process disputes](https://developer.squareup.com/docs/disputes-api/process-disputes), [Webhooks overview](https://developer.squareup.com/docs/webhooks/overview), [Refund payments](https://developer.squareup.com/docs/payments-api/refund-payments).
>
> **Event to listen for:** `payment.updated`. It fires when a payment completes and also on other changes, so the same payment can arrive more than once. Act only when the payment object inside the event's `data.object` has `status` of `COMPLETED`. Check the exact path in a sandbox event.
>
> | Square | Affixo |
> | - | - |
> | Payment `id` | `external_id` |
> | `amount_money.amount` (an integer in the smallest currency unit, tip not included) | `amount_cents` |
> | `amount_money.currency` | `currency` |
> | `reference_id` or `note` you set | `visitor_id` |
> | `buyer_email_address` (may be absent), or look up the customer by `customer_id` | `email` |
>
> Square's `total_money` includes the tip. `amount_money` does not, so it is the figure to commission on.
>
> For Point of Sale payments, the webhook does not include a note, though a note set in a CreatePayment call does come back. Order `metadata` and the order's `reference_id` live on the order, so fetch it by `order_id`. The `customer_id` can be filled in later, so a customer lookup may need a short delay.
>
> ```js theme={null}
> // payment: the payment object from the event, once its status is COMPLETED
> await affixo('sale', {
>   external_id:  payment.id,
>   amount_cents: payment.amount_money.amount,   // excludes the tip
>   currency:     payment.amount_money.currency,
>   visitor_id:   payment.reference_id,
>   email:        payment.buyer_email_address,   // may be absent
> })
> ```
>
> **Refunds:** listen for `refund.created` and `refund.updated`. The refund object (at `data.object.refund`) has its own `id`, a `payment_id`, an `amount_money` for this refund only, and a `status`. When the status is `COMPLETED`, fetch the payment and send its `refunded_money.amount`, which Square defines as the total refunded to date. Send `external_id` = payment id and `refunded_amount_cents` = that number. A payment can have several partial refunds, up to 20. `amount_money` excludes the tip, and whether `refunded_money` can include a refunded tip is not confirmed, so check in your sandbox first whether a refunded tip is included in `refunded_money`. Scale the refund as described in step 4 only if it is.
>
> **Disputes and chargebacks:** `dispute.created` (the dispute is at `data.object.dispute`, with `disputed_payment.payment_id`) means send `/chargeback`. `dispute.state.updated` fires as the state changes. When the bank decides, the state becomes `WON` or `LOST`: on `WON`, send `/dispute_won`. Use `disputed_payment.payment_id` as `external_id`. Don't use `dispute.state.changed`: Square has deprecated it.
>
> **Subscriptions and renewals:** a Square Payment has no `subscription_id`. The Subscriptions API puts it on the invoice, and the event to track is `invoice.payment_made`. How an invoice links to its payment is not confirmed, so check in your sandbox which field connects them.
>
> **Signature check:** the `x-square-hmacsha256-signature` header is an HMAC-SHA-256 over the notification URL plus the raw body, using your signature key. See [Square's guide](https://developer.squareup.com/docs/webhooks/step3validate). Their SDKs include a helper.
>
> **Retries and duplicates:** if you don't answer with a 2xx within 10 seconds, Square retries with exponential backoff for up to 24 hours (11 attempts). Square says webhooks can be sent more than once, that the `event_id` is stable for deduplication, and that delivery order is not guaranteed. Running-total refunds are safe against that.

> [accordion] Paddle (Paddle Billing)
>
> This recipe is for Paddle Billing. Paddle Classic is an older platform with different event names, and is not covered here.
>
> Docs: [transaction.completed](https://developer.paddle.com/webhooks/transactions/transaction-completed), [adjustment.created](https://developer.paddle.com/webhooks/adjustments/adjustment-created), [custom data](https://developer.paddle.com/build/transactions/custom-data), [adjustments](https://developer.paddle.com/build/transactions/create-transaction-adjustments), [respond to webhooks](https://developer.paddle.com/webhooks/about/respond-to-webhooks).
>
> **Event to listen for:** `transaction.completed`. Transactions reach completed after they are paid. Don't use `transaction.paid`: it fires before processing finishes and payout totals may be missing.
>
> | Paddle | Affixo |
> | - | - |
> | `data.id` (`txn_...`) | `external_id` |
> | `data.details.totals.subtotal` (before tax) or `total` (after tax), a string in the lowest denomination | `amount_cents` (convert with `Number(...)`) |
> | `data.currency_code` | `currency` |
> | `data.custom_data.<your key>` (set at checkout) | `visitor_id` |
> | Not in the event. Look up `data.customer_id` with `GET /customers/{id}` and read `email` | `email` |
> | `data.subscription_id` | `subscription_id` |
>
> Totals are strings in the lowest denomination, so 10 USD is `"1000"`. To avoid paying commission on tax, use `subtotal`. Whether `subtotal` already reflects a discount is not confirmed: check in your sandbox. The `fee` and `earnings` totals are Paddle's cut and your net, not the sale amount.
>
> Set `custom_data` when you open the checkout (Paddle.js `customData`, or the `data-custom-data` attribute). A completed transaction can't be edited. Paddle copies custom data from the transaction to the subscription and onto later renewal transactions. Paddle's size limit for custom data is not confirmed, but a visitor id is short.
>
> ```js theme={null}
> const t = event.data
> await affixo('sale', {
>   external_id:  t.id,
>   amount_cents: Number(t.details.totals.subtotal),
>   currency:     t.currency_code,
>   visitor_id:   t.custom_data?.visitor_id,   // whatever key you used at checkout
>   subscription_id: t.subscription_id ?? undefined,
> })
> ```
>
> **Refunds:** listen for `adjustment.created` and `adjustment.updated`. An adjustment with `data.action` of `refund` starts as `pending_approval` and only counts once its `status` is `approved`. A `rejected` refund never counts. A transaction can have several adjustments. Each adjustment is one refund, so add up the approved refund adjustments for the transaction and send the running total. `data.transaction_id` gives the transaction. Whether `totals.total` on an adjustment is for that adjustment alone is not stated in the docs we read, so confirm in your sandbox, or read the transaction's adjusted totals instead. Send `external_id` = transaction id, `refunded_amount_cents` = the running total and `currency`. Which basis an adjustment's `totals.total` uses (whether it includes tax) is not confirmed, so check in your sandbox. If it includes tax and you reported the sale as `subtotal`, scale the refund first (see the rule in step 4).
>
> **Disputes and chargebacks:** adjustments cover these too. An `action` of `chargeback` means send `/chargeback`, and so does `chargeback_warning`, an early warning that is also refunded. A won dispute shows as `chargeback_reverse`, and one status description spells it `chargeback_reversal`, so match both and send `/dispute_won`. Whether a warning and a later chargeback both occur for the same dispute is not confirmed: Affixo is idempotent per `external_id`, so sending `/chargeback` twice does no harm.
>
> **Subscriptions and renewals:** each transaction carries `data.subscription_id`. The `data.origin` values include `web` and `api` (a first purchase), `subscription_recurring` (a renewal), and `subscription_update` and `subscription_payment_method_change`, which can be zero-value, so skip any transaction with an amount of 0. Set `billing_interval` from your own plan cadence (`month` or `year`).
>
> **Signature check:** the `Paddle-Signature` header carries a timestamp (`ts`) and a hash (`h1`): an HMAC-SHA256 of `ts:rawBody` with your notification destination's secret. See [Paddle's guide](https://developer.paddle.com/webhooks/signature-verification).
>
> **Retries and duplicates:** a non-200 response, or no reply within 5 seconds, is retried (live mode: up to 60 attempts over about two days). Paddle's docs say to use `event_id` to skip events you've already processed, and there is no ordering guarantee.

> [accordion] Lemon Squeezy
>
> Docs: [Event types](https://docs.lemonsqueezy.com/help/webhooks/event-types), [webhook requests](https://docs.lemonsqueezy.com/help/webhooks/webhook-requests), [signing requests](https://docs.lemonsqueezy.com/help/webhooks/signing-requests), [the order object](https://docs.lemonsqueezy.com/api/orders/the-order-object), [the subscription invoice object](https://docs.lemonsqueezy.com/api/subscription-invoices/the-subscription-invoice-object), [passing custom data](https://docs.lemonsqueezy.com/help/checkout/passing-custom-data), [refunds and chargebacks](https://docs.lemonsqueezy.com/help/payments/refunds-chargebacks).
>
> **Event to listen for:** `order_created`.
>
> | Lemon Squeezy | Affixo |
> | - | - |
> | `data.id` (the order id) | `external_id` |
> | `data.attributes.subtotal` (before tax) or `total` (after tax), an integer in cents | `amount_cents` |
> | `data.attributes.currency` | `currency` |
> | `meta.custom_data.<your key>` (set at checkout) | `visitor_id` |
> | `data.attributes.user_email` | `email` |
> | `data.attributes.test_mode` | `is_test` (a `test_mode` order only matches a test click, so start from a `?_sa_test=1` visit) |
>
> Amounts are in cents in the order's currency. One official sample shows fractional EUR amounts, so round to a whole number before you send. The `total_usd` and `subtotal_usd` fields also exist.
>
> To carry the visitor id, add `?checkout[custom][visitor_id]=...` to the checkout URL, or set `checkout_data.custom` when you create the checkout through the API. It arrives as `meta.custom_data` on order, subscription and license events.
>
> ```js theme={null}
> const a = order.data.attributes
> await affixo('sale', {
>   external_id:  order.data.id,
>   amount_cents: Math.round(a.subtotal),
>   currency:     a.currency,
>   email:        a.user_email,
>   visitor_id:   order.meta.custom_data?.visitor_id,
>   is_test:      a.test_mode,
> })
> ```
>
> **Refunds:** listen for `order_refunded` (a full or partial refund) and `subscription_payment_refunded`. `refunded_amount` is in cents in the order currency. `refunded` is true only for a full refund, and a partial refund can leave `status` as `paid` in the docs' example, so compare `refunded_amount` with `total` instead of trusting `status`. Whether `refunded_amount` is a running total across several partial refunds is not confirmed: test two partial refunds in test mode. For a first purchase, send `external_id` = order id, `refunded_amount_cents` = `refunded_amount` and `currency`. For a renewal, use the subscription invoice's `data.id` as `external_id` (see below). `refunded_amount` is compared with `total`, which includes tax, so if you reported the sale as `subtotal`, scale the refund first (see the rule in step 4).
>
> **Disputes and chargebacks:** Lemon Squeezy has **no dispute or chargeback webhook event**, and its docs don't say which event reports a chargeback. It handles chargebacks itself and says it will, in most cases, refund on your behalf. So a chargeback reaches you only if it shows up as a refund. If you learn about a chargeback another way, send `/chargeback` yourself.
>
> **Subscriptions and renewals:** the first payment of a subscription sends both `order_created` and `subscription_payment_success`. Count revenue once: use `order_created` for the first payment. Renewals arrive as `subscription_payment_success` with `billing_reason` of `renewal` (the other values are `initial` and `updated`). Use the subscription invoice's own id (`data.id` of the invoice event) as `external_id` for each renewal, and the same invoice id for `subscription_payment_refunded`, not the order id. The invoice carries `subscription_id`, `total` and `subtotal` in cents, `currency` and `status`. `subscription_payment_recovered` always arrives alongside a `subscription_payment_success`, so don't count it again. The visitor id is not documented on subscription-invoice events, so for renewals rely on `subscription_id`. Whether the order event for the first payment carries the subscription id is not confirmed: check a sandbox event, because the first call needs the same `subscription_id` your renewals will use.
>
> **Signature check:** the `X-Signature` header is the HMAC-SHA256 hex digest of the raw body, using your signing secret. See [signing requests](https://docs.lemonsqueezy.com/help/webhooks/signing-requests).
>
> **Retries and duplicates:** a non-200 response is retried up to three more times with exponential backoff (5, 25 and 125 seconds), then marked failed. You can resend from the dashboard. No delivery id or idempotency guarantee is documented, so dedupe on your side. Affixo's `external_id` does it for sales.

> [accordion] WooCommerce
>
> WooCommerce is a store plugin, not a processor. The money moves through a payment gateway (PayPal, Square, Stripe and others). So orders come from WooCommerce webhooks, and chargebacks come from the gateway: use that gateway's recipe for disputes. WooCommerce's webhook topics cover coupons, customers, orders and products, not disputes.
>
> Docs: [Webhooks](https://woocommerce.com/document/webhooks/), [Subscriptions](https://woocommerce.com/document/subscriptions/), and the [WooCommerce source](https://github.com/woocommerce/woocommerce).
>
> **Event to listen for:** the webhook topics `order.created` and `order.updated`. `order.created` normally carries a still-`pending` order, so don't treat it as paid. `order.updated` fires on status changes and on refunds. Treat an order as paid when its `status` is `processing` or `completed` and `date_paid` is not null. The same order arrives several times, which is fine: Affixo dedupes on `external_id`.
>
> | WooCommerce | Affixo |
> | - | - |
> | Order `id` (an integer) | `external_id` (send it as a string) |
> | `total`, a string in major units such as `"29.35"` | `amount` |
> | `currency` | `currency` |
> | `billing.email` | `email` |
> | An entry in `meta_data` (`{key, value}`) that you saved at checkout | `visitor_id` |
>
> If you don't pay commission on tax and shipping, send `total` minus `total_tax` minus `shipping_total` instead.
>
> To carry the visitor id, save it on the order when checkout creates it. The `woocommerce_checkout_create_order` hook fires just before the order is saved, and `$order->update_meta_data( $key, $value )` is the official way to write order meta (it works with High-Performance Order Storage). It then appears in the webhook's `meta_data` array. Fill a hidden field at checkout from `Affixo.getVisitorId()` and read it in that hook. Name the key `affixo_visitor_id` (no leading underscore); whether underscore keys still appear in the webhook payload is not confirmed.
>
> ```js theme={null}
> if (['processing', 'completed'].includes(order.status) && order.date_paid) {
>   const visitor = order.meta_data.find(m => m.key === 'affixo_visitor_id')
>   await affixo('sale', {
>     external_id: String(order.id),
>     amount:      order.total,              // major units, e.g. "29.35"
>     currency:    order.currency,
>     email:       order.billing.email,
>     visitor_id:  visitor?.value,
>   })
> }
> ```
>
> **Refunds:** refunds appear in the order's `refunds` array. Each has an `id`, a `reason` and a `total` that is a negative string such as `"-10.00"`. The running total is the sum of their absolute values. Send `external_id` = order id, `refunded_amount` = that sum, as a number, and `currency`. Refunds are on the order-total basis and can be any amount or chosen line items, so if you reported the sale as `total` minus `total_tax` and `shipping_total`, scale the refund first (see the rule in step 4). Refunds trigger `order.updated`.
>
> **Disputes and chargebacks:** not reported by WooCommerce. Use the recipe for the gateway that took the payment. The order's `transaction_id` usually holds the gateway's payment id; check one of your orders. Map the gateway's dispute to your WooCommerce order id, because that is the `external_id` your sale was booked under, and send `/chargeback` with it. If your store takes payments through Stripe, check whether the native Stripe connection fits instead (one processor per account).
>
> **Subscriptions and renewals:** with the WooCommerce Subscriptions extension, every recurring payment creates a renewal order. `wcs_order_contains_subscription( $order, 'renewal' )` tells you an order is a renewal, and `wcs_get_subscriptions_for_order( $order_id )` returns its subscription or subscriptions. A subscription's own id is a normal WordPress post id, usable as `subscription_id`. The webhook payload alone may not carry it, so look it up in code that runs on your side. We did not confirm the subscription webhook topics.
>
> **Signature check:** the `X-WC-Webhook-Signature` header is the base64 of an HMAC-SHA256 of the raw body, using the webhook secret.
>
> **Failures and retries:** WooCommerce disables a webhook automatically after more than five consecutive delivery failures (anything other than a 2xx, 301 or 302), and there is no documented retry. Your endpoint must answer fast with a `200`, and you should watch for the webhook turning to **Disabled**. If you answer before calling Affixo, queue the call and retry it on a `429` or `5xx`, because WooCommerce won't resend it. Deliveries are queued, and the request timeout is 60 seconds.

## Checklist

* [ ] The snippet is on every page of your site
* [ ] A secret key with the `track` scope is stored on your server only
* [ ] The visitor id is carried from the browser, through checkout, into your processor's free-form field
* [ ] Every sale call sets `external_id` to the processor's payment or order id
* [ ] Amounts use one unit: `amount_cents` in the smallest unit, or `amount` in major units, never both
* [ ] Refunds send the **running total**, on the same basis as the sale, with `currency`
* [ ] Chargebacks call `/chargeback`, and won disputes call `/dispute_won`
* [ ] Your handler verifies the processor's signature
* [ ] Your handler answers with a `200` quickly, and failed Affixo calls are retried
* [ ] Each payment is counted once, even when the processor sends several events for it
* [ ] A test sale with `is_test: true` returned `attributed: true`, and sandbox sales are sent with `is_test: true`

## Common mistakes

| Mistake | What happens | Fix |
| - | - | - |
| No `external_id` | A retry can book the sale twice | Use the processor's payment or order id on every call |
| Sending `amount` and `amount_cents` together | `400 amount_conflict` | Send only one |
| Passing an amount as a string to `amount_cents` or `refunded_amount` | `400 invalid_amount` | Convert with `Number(...)` first |
| Sending only this refund's amount | Commission shrinks too little | Send the total refunded so far |
| Refund figure includes tax but the sale didn't | Commission is clawed back too much | Scale the refund to the sale's basis (see step 4) |
| Sandbox sale sent without `is_test: true` | `attributed: false` | Send `is_test: true` and start from a `?_sa_test=1` visit |
| Visitor id not carried through checkout | `attributed: false`, no commission | Store it in the processor's free-form field |
| Reporting one payment from two events under different ids | The sale is booked twice | Choose one event per payment (for example Lemon Squeezy's `order_created` for the first subscription payment) |
| Calling `/sale` before the payment is confirmed | Failed payments create commissions | Call it from the paid event only |
| Secret key in browser code | Anyone can create or reverse commissions | Keep it on your server |
| Skipping signature checks | Anyone can post fake events to your handler | Verify with the processor's official method |
| Slow handler | The processor retries, or WooCommerce disables the webhook | Answer quickly, but queue the Affixo call and retry it on `429` or `5xx` so a failure is never lost |

## Not a developer?

A no-code option, where you paste a link into your processor's settings instead of writing code, is planned but not available yet.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.