Integration overview

AffiHQ supports two product integration modes. Choose the mode that owns the payment journey for that product; do not send the same product’s native and advanced payment facts as if they were separate sales.

Decision matrix

Start with the Stripe automatic guide when Stripe is your payment source. Use API authentication and the Server SDK for the advanced path.

Stripe automatic end to end

1. In Products, choose Stripe automatic and connect the Stripe Standard account that owns the Payment Link.
2. Select one active buy.stripe.com Payment Link with exactly one fixed-price line, quantity 1, a positive amount, one currency and either one-time or subscription billing. Subscription links must be monthly or annual.
3. An affiliate’s /r/ link records the click, then opens that Payment Link with an opaque client_reference_id=clk_*. Existing URL parameters are kept and a previous client_reference_id is replaced.
4. For one-time billing, a successful immediate Checkout or later asynchronous payment success creates the payment. An asynchronous failure creates no commission.
5. For subscriptions, Checkout locks the attribution and each invoice.paid creates a recurring payment using the selected monthly or annual link.
6. AffiHQ applies the campaign’s commission and validation rules and handles Stripe signatures, account ownership, test/live mode, durable receipt, retries, idempotence and matching automatically.
7. Successful refunds and dispute outcomes create the applicable cumulative correction. Ready commissions can then be included in a payout that you send separately.

If native state is invalid or unavailable, /r/ falls back to the historical destination with affihq_ref. That fallback requires the advanced server flow to complete attribution and payment reporting.

API/SDK advanced end to end

1. Configure the product for API/SDK advanced and keep its API key and fingerprint key in your server secret store.
2. Capture the opaque affihq_ref in the browser or accept a manual partner code according to your consent and storage rules. Never put a product secret in browser code.
3. When your application creates the customer or prospect, your server creates the attribution with a stable opaque customer ID and product-scoped fingerprint. The first qualified attribution remains authoritative.
4. Your server completes its own signup or Checkout, verifies the original payment-provider webhook and sends the verified payment with a stable provider event identity.
5. Send verified refunds and dispute outcomes with the original payment identity when the provider reports them.
6. AffiHQ creates or corrects the matching commission. Retry temporary failures without changing the original event identity; review stable business rejections instead of changing financial data automatically.

The advanced path is appropriate when AffiHQ cannot receive the payment directly from the selected Stripe Payment Link or when your business event is not a Stripe payment. Continue with Browser referral capture, Server SDK, Billing events and Durable delivery.

Credentials, webhooks and responsibilities

Stripe automatic requires no AffiHQ product API key, fingerprint key or Stripe SDK. AffiHQ receives and verifies the connected account’s Stripe deliveries. You remain the merchant of record on your Stripe Standard account, and AffiHQ’s own subscription billing is separate. AffiHQ records affiliate payout obligations but does not transfer the funds through Stripe.

API/SDK advanced requires the product API and fingerprint keys on your server. Your server must verify the original provider webhook before sending a billing event, keep customer email out of AffiHQ payloads and use stable idempotency identities for retries. The browser should carry only the opaque referral reference.

For native errors and safe fallback behavior, see Stripe automatic troubleshooting. For access boundaries, see Workspace permissions.