Connect Stripe

Connecting Stripe lets Siren Cloud record the payments your Stripe account takes, credit them to the collaborators who referred them, and reverse commission when a payment is refunded. Stripe sends each payment to Siren Cloud through a webhook you add in your Stripe dashboard. You don’t give Siren Cloud a Stripe API key to record sales. Paying collaborators through Stripe is separate, and it needs your secret key.

Admins and Platform Managers can connect Stripe. Each Property holds one Stripe account. To connect a second account, use a second Property.

Start the setup

Open the setup in one of two ways.

• From the Property: on its page, click “Add integration”, then “Stripe” (Admins only).
• From Settings > Integrations: click “Connect” on the Stripe card, or “Manage” once a Property has Stripe. With one Property, or when one Property already has Stripe, the setup opens straight away. With no Property, Siren Cloud asks you to add one. With several, it lists them: click “Connect here” on the one you want.

To connect Stripe on a second Property, use that Property’s own “Add integration”.

The setup screen numbers its steps, and these sections follow them.

1. Add a webhook endpoint

Click “Start setup”. Siren Cloud shows the webhook URL for this Property, and the Property’s Integrations card lists Stripe with “Waiting for its signing secret”. The setup screen also lists the steps below and an “Events to tick” box with the ten events Stripe has to send.

“Events to tick” groups the ten events by what they do:

• Sales: checkout.session.completed and checkout.session.async_payment_succeeded. The second one credits bank debits such as ACH and SEPA, which Stripe confirms a few days after checkout.
• Subscription renewals and refunds: invoice.paid, charge.refunded, and invoice_payment.paid. The invoice payment event lets Siren Cloud find a refunded renewal on newer Stripe versions.
• Products: product.created, product.updated, and product.deleted. These keep your Stripe products and their names in Siren Cloud.
• Promotion codes: promotion_code.created and promotion_code.updated. These list your promotion codes in Siren Cloud. Without them, Siren Cloud knows a promotion code only by its ID.

2. Paste the signing secret

In Stripe, open the endpoint you made. Under “Signing secret”, click “Reveal” and copy the value that starts with whsec_. Paste it into “Signing secret” in Siren Cloud and click “Connect”. The Integrations card now shows Stripe as “Connected”.

3. Add the tracking line to your website

The setup shows the Property’s tracking line for Admins, or a longer script under “Copy script” for Platform Managers, and either one works. Paste it on every page of the site where your Payment Links, buy buttons, or checkout live, right above </head>. It records referral visits and passes each visit on to Stripe.

4. Check how your site takes payments

• If you use Payment Links, buy buttons, or pricing tables, there’s nothing more to do. The tracking line adds the visit to each one.
• If your developer built your checkout, your server reads the siren_visit cookie and passes its value to Stripe as the Checkout Session’s client_reference_id. If your checkout already uses client_reference_id for something else, pass the value as metadata.siren_tracking_id instead.

A Payment Link that already carries a client_reference_id of your own is left alone, so its payments aren’t credited to a collaborator.

5. Make a test purchase

Open one of your collaborator’s referral links, then buy through it. In Siren Cloud, open Track > Conversions. The payment appears, credited to that collaborator.

To try it without real money, connect test mode first. To watch your programs credit a sale before any store is connected, send a test sale from your dashboard, as Test Your Setup Before Going Live describes.

What Siren Cloud records

• A paid Checkout Session becomes a sale, with its subtotal, discount, shipping, and tax lines. Payment Links, buy buttons, and pricing tables all use Checkout Sessions. A bank payment that settles later is recorded once, when it settles.
• For a subscription, the first payment is a sale when it’s paid through a Checkout Session. A Checkout that takes no payment, such as a free trial sign-up, isn’t recorded as a sale, and neither is a subscription started outside Checkout. Each later billing-cycle invoice is a renewal of that sale, credited to the collaborator who earned the first one. An invoice whose first payment Siren Cloud didn’t record counts as a sale instead when the customer is already tied to a referral or a product owner claims it.
• A full refund reverses the commission. A partial refund is recorded on the transaction, and each reward that hasn’t been paid out is recalculated for what the customer kept, as Partial refunds describes. Siren Cloud keeps a refund that arrives before its order for up to 30 days and applies it once the order is recorded.
• Each promotion code or coupon on a payment counts as a coupon use, so a code linked to a collaborator credits them. Link codes under Track > Coupon codes, as Manage Coupon Codes describes.
• Your Stripe products appear under Track > Products, where you choose who owns each one, as Manage Products on Siren Cloud describes.
• A later order from a Stripe customer Siren Cloud already knows lands on that customer’s earlier visit, even without a new click. A program that pays lifetime commissions pays again on it, and a program whose engagement already turned into a sale pays nothing more. The customer appears under Track > Customers, with their email kept only as a keyed hash.

Payments that don’t go through Stripe Checkout, such as a custom form built on Payment Intents, aren’t recorded. For those, your server can send each sale to Siren Cloud itself with an API key, which an Admin creates under Settings > Developer > API keys.

Sales are recorded in the currency Stripe charged. Siren Cloud doesn’t convert them, so when an order has a line in a currency a percentage program doesn’t pay in, the program’s whole reward is worked out at face value and held for review, as Sales in another currency describes. A program that pays in that currency pays those sales without a hold. A distributor leaves out lines in a currency it doesn’t pay in, and a note on the transaction says so. A program or distributor that pays in a custom currency earns on lines in your organization’s currency.

Test mode

Test mode is a second Stripe connection on the same Property, with its own webhook URL and signing secret. Stripe’s test payments reach it, and Siren Cloud lists each one with what it would do, without recording a sale. Live and test mode can be connected at the same time, so you can keep test mode when you go live.

Switch to the “Test mode” tab on the setup screen and click “Start test mode setup” to get the test-mode webhook URL. Then add a second endpoint in Stripe, this time in test mode.

Stripe then shows the new test-mode endpoint. Under “Signing secret”, click “Reveal”, copy the value that starts with whsec_, paste it into “Test signing secret” in Siren Cloud, and click “Connect test mode”. It’s a different secret from your live one. If you closed the page, open Stripe webhooks in test mode again and click the endpoint.

To run a test checkout, keep the tracking line from the “Live” tab on your website. Open your website through a referral link, then pay through a test-mode Payment Link or buy button with Stripe’s test card 4242 4242 4242 4242. If your developer creates Checkout Sessions, they pass the siren_visit cookie as client_reference_id with your test keys.

The payment appears in the “Recent test events” card on the test-mode tab, with what it would do, such as “Would record a sale” or “Would be ignored”, and the collaborator a live sale would credit. The card refreshes every 10 seconds while you watch, and “Clear” empties it. Test events never create sales, commissions, payouts, or reports, never count toward your usage, and never email your collaborators.

Siren Cloud records nothing for a test event sent to the live URL, or a live event sent to the test URL, and lists it as “Refused, wrong mode”.

“Disconnect test mode” stops Siren Cloud accepting test events and invalidates the test webhook URL. Your live connection keeps working.

Test Your Setup Before Going Live covers test mode alongside test sales, which credit a collaborator without any store.

If payments don’t show up

“Connected” means only that a signing secret is saved. Siren Cloud doesn’t test it. If payments don’t appear:

1. In Stripe, open the webhook endpoint and look at its event deliveries.
2. If deliveries fail with “Invalid signature”, the secret is wrong. Copy it again and use “Replace signing secret” in Siren Cloud. Replacing the secret keeps the same webhook URL and tracking line.
3. If deliveries fail with “Inbound source is not configured”, the URL is out of date. Copy the current URL from the setup screen into the endpoint.
4. If deliveries succeed but the payment isn’t credited, check that the tracking line is on the page where the shopper paid, and that they arrived through a referral link.

Disconnect Stripe

“Disconnect Stripe” on the setup screen, or removing Stripe from the Property, stops Siren Cloud accepting the webhook at once, and the tracking line stops working too. Conversions already recorded stay. Connecting again gives the Property a new webhook URL and a new tracking line, so update both.

Limits

• One Stripe account per Property. Don’t point the same Stripe account at two Properties, or each payment may be recorded twice.
• The event destination listens to your own Stripe account, so payments taken on accounts connected to your Stripe platform don’t arrive.
• Stripe payouts to collaborators are a separate setup, on the Plus and Pro plans. It needs your Stripe secret key, and it shows whether a webhook signing secret is saved on your Stripe connections, with a link to Integrations, Stripe. See Set Up Automatic Payouts.