Skip to main content
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. This page is the guided path. For every field and edge case, see No Stripe: book sales from your server and the API reference.

Before you start

You need:
  • The snippet installed on every page of your site, as described in Integrate Affixo tracking.
  • 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.
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.
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.

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.
Affixo.getVisitorId() returns the same id without waiting. Use ready() when you need to be sure it is there. See sa.js. Where to put it, by processor: 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.
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.
  • 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.

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 and Products.

Step 4: Report refunds and disputes

  • /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.
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 and 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.
  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:
What the response tells you: 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.
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. 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. See Attribution 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.
Docs: Webhooks, event names, Payments v2, Orders v2, Disputes.Event to listen for: PAYMENT.CAPTURE.COMPLETED for one-time payments.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.
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, 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.
Docs: Payments webhooks, Refunds webhooks, Process disputes, Webhooks overview, 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’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.
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. 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.
This recipe is for Paddle Billing. Paddle Classic is an older platform with different event names, and is not covered here.Docs: transaction.completed, adjustment.created, custom data, adjustments, 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.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.
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.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.
Docs: Event types, webhook requests, signing requests, the order object, the subscription invoice object, passing custom data, refunds and chargebacks.Event to listen for: order_created.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.
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.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.
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, Subscriptions, and the WooCommerce source.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.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.
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

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.