Stripe automatic payments

Stripe automatic is the recommended path when Stripe is the payment source for a product. Affiliate links open a Stripe-hosted Payment Link, and AffiHQ receives the resulting payment, subscription, refund and dispute information automatically.

You do not need an AffiHQ product API key, fingerprint key or Stripe SDK for this mode. You also do not forward Stripe webhooks from your application. AffiHQ verifies the Stripe delivery and applies the result to the exact product, account, Payment Link and affiliate click that belong together.

Before you configure the product

Stripe automatic uses an existing eligible Stripe Connect Standard account through OAuth. The account must own the Payment Link you want to use.

AffiHQ deployments use one Stripe mode at a time:

• a development or test deployment uses Stripe test data;
• a production deployment uses Stripe live data.

Do not connect a live account or select a live Payment Link in a test deployment, and do not use test data in production. A Payment Link from the other mode is not available for selection.

Payment Link requirements

The chooser can use only an active Stripe-hosted URL on buy.stripe.com with all of these properties:

• exactly one line item;
• a fixed price and quantity 1;
• a positive amount;
• one currency, matching the line item price;
• either a one-time payment or a subscription;
• for subscriptions, a monthly or annual interval only.

Inactive, malformed, multi-item, variable-quantity or otherwise unsupported links remain unavailable in the chooser. Each AffiHQ product has one selected Payment Link. AffiHQ keeps the selected link’s amount, currency and billing cadence as the product’s validation snapshot, so a Checkout or invoice must continue to match that snapshot.

Configure Stripe automatic

1. Open Products and edit the product.
2. In Stripe payments, select Stripe automatic.
3. Select Connect Stripe and authorize the Standard account that owns the Payment Link.
4. Confirm that the account is in the expected Test mode or Live mode.
5. Choose one available Payment Link. The list shows its amount and cadence; links marked inactive or not supported cannot be selected.
6. Select Use this Payment Link. AffiHQ saves the choice immediately.

The product should show the connected account and Ready beside the selected link. The product’s currency and its selected link’s currency must agree.

What an affiliate click does

An affiliate link under /r/ first records the click. In Stripe automatic mode, it then opens the selected Payment Link and adds an opaque client_reference_id such as clk_… to the URL.

AffiHQ preserves the Payment Link’s other query parameters. If the URL already has client_reference_id, the AffiHQ click reference replaces that value so the Checkout can be matched to the recorded click.

If the native configuration is invalid or unavailable at redirect time, the link safely falls back to the product’s historical destination and adds affihq_ref there. That fallback is an API-style destination, not an automatic Stripe payment path: your server must capture the reference, create the attribution and report payment facts through the API/SDK advanced flow.

How payments become commissions

One-time Payment Links

A paid Checkout that completes immediately creates the payment used for the commission. Some payment methods complete asynchronously:

• Checkout can record the click and attribution before the payment is final;
• an asynchronous payment success creates the payment and commission;
• an asynchronous payment failure does not create a commission.

AffiHQ does not credit a payment that cannot be matched to the product, selected Payment Link, Stripe account, customer and affiliate click. Recheck that the link was generated from the product’s /r/ URL and that the product is still configured for that Payment Link.

Subscription Payment Links

A subscription Checkout locks the attribution to the subscription. The selected Payment Link determines whether the cadence is monthly or annual. Each invoice.paid for that subscription creates the corresponding recurring payment, subject to the product’s commission duration and validation rules.

The Checkout itself establishes the subscription attribution; later recurring commissions come from paid invoices. An unpaid or failed invoice does not create a successful payment.

Refunds and disputes

AffiHQ adjusts native financials from the status of the Stripe adjustment, not from a request that was merely created.

Refunds

Only a refund with a successful Stripe status corrects financials. Pending, action-required, failed or canceled refunds do not create a correction yet.

Partial refunds and several refunds for the same payment are combined cumulatively. AffiHQ allocates the tax portion deterministically, reduces the commissionable amount accordingly and never corrects more than the original payment amount. The same original amount also limits corrections from lost disputes.

Disputes

When a dispute is open, AffiHQ can reserve or correct the related amount at most once. If the dispute is won, it resolves without an additional financial correction. If it is lost, AffiHQ applies the correction. A terminal dispute outcome is resolved once, so later duplicate deliveries do not create another correction.

What AffiHQ handles for you

In native mode, AffiHQ automatically handles:

• Stripe Connect webhook signature verification;
• ownership checks for the connected Standard account and product;
• test/live mode checks;
• durable receipt, retries and idempotence for Stripe deliveries;
• matching a payment, refund or dispute to the exact attributed payment.

Your application does not need to receive or forward Stripe webhooks. Continue to keep the product’s rules, currency and selected Payment Link current, and use the troubleshooting guide when a product is not ready.

Merchant of record and payouts

You remain the merchant of record on your Stripe Standard account. AffiHQ’s own subscription billing is separate from your customer payments. AffiHQ records the commission and the payout obligation; it does not transfer affiliate funds through Stripe. Send affiliate payouts through your chosen process as described in Commissions and payouts.

Switching or revoking access

Switching a product to API/SDK advanced stops the selected native Payment Link from driving that product’s /r/ redirects and automatic payment flow. The Stripe account remains connected. The product’s historical destination and affihq_ref resume, so the API/SDK flow must complete attribution and payment reporting.

To revoke AffiHQ’s access to the Stripe account, remove the connected application from Stripe. Native processing then stops, and the product should be reconnected and configured again before you use Stripe automatic. Revoking access is different from switching one product to API mode: switching does not disconnect the account.

For a broader comparison of both integration paths, read the integration overview.