Skip to content
Cobalz Affiliate

Mercury payouts

Pay every affiliate from your Mercury account.

Cobalz is the only affiliate platform with a native Mercury Invoicing API integration. If your store banks with Mercury, you'll never wire an affiliate manually again.

Connect your Mercury accountProcess payouts

How it works

Invoices issued. Status reconciled. Audit trail intact.

  1. 1You paste a Mercury API key in Settings → Payouts. We validate it via GET /accounts and ask you to pick a destination account (checking or savings).
  2. 2An hourly cron checks your local timezone. When today is your scheduled payout day, the aggregator picks every affiliate above min_payout with approved commissions in the period.
  3. 3For each eligible affiliate we ensure a Mercury customer exists, then create an invoice (one line per commission, or aggregated, your choice). The Mercury hosted-pay URL goes into the payout row.
  4. 4Mercury sends the affiliate the invoice. They click pay, ACH funds move, Mercury fires a transaction.created webhook. We re-fetch the invoice for authoritative status, mark the payout paid.
  5. 515-minute reconciliation cron polls every open payout against Mercury. Catches anything the webhook missed (or in sandbox where webhooks don't fire).
# Cron output, hourly per merchant timezone
$ cobalz payouts run --merchant=acme

› checking schedule (timezone=America/New_York)
✓ today is monthly_first → due
› aggregating approved commissions [2026-04-01 → 2026-04-30]
› eligible affiliates: 47 ($184,720.00 USD)
› blocked: 2 (missing W-9)

# Per affiliate
› ensuring Mercury customer for affiliate=alice@example.com
✓ customer cached (id=cus_AB123)
› creating Mercury invoice (idempotency=payout-acme-alice-2604f1d3)
✓ invoice id=inv_X9k2 · status=Unpaid · hosted=https://app.mercury.com/pay/x9k2

# After Mercury webhook fires
› transaction.created received · re-fetching invoice
✓ status=Paid · payout marked paid · commissions cleared
✓ payout.paid webhook delivered to 3 endpoints

What ships

The whole payout pipeline.

Per-merchant Vault

API keys + webhook secrets stored in Supabase Vault, scoped to your merchant_id.

Sandbox + production

Configurable per merchant. We never confuse the two.

Account validation

Live GET /accounts call when you paste your key. We tell you immediately if it's wrong.

Idempotency keys

Deterministic payout-{merchant}-{affiliate}-{period_hash} prevents double-invoicing on retry.

Hourly cron

Vercel cron checks every merchant in their local timezone. No "missed your window" drama.

15-min reconciliation

Catches missed webhooks. Required in sandbox. Belt-and-suspenders in production.

Mercury customers cached

First invoice creates the Mercury customer; subsequent invoices reference the same id.

Per-line or aggregated

Choose invoice line strategy: one line per commission (granular) or one aggregated line.

Hosted pay URL

We surface the Mercury hosted-pay URL on the payout detail page. Your affiliate doesn't need a Mercury login.

Quick start

Connect Mercury in three steps.

  1. 1

    Generate a Mercury API key

    In Mercury, go to Settings → API, create a new token with Invoicing + Read accounts scopes. Copy it once — Mercury shows it exactly once.
  2. 2

    Paste it in Cobalz

    Settings → Payouts → Connect Mercury. We validate it live, then ask you to pick a checking/savings destination account.
  3. 3

    Register the webhook

    One-click "Register webhook" creates the Mercury webhook subscription pointing at /api/mercury/webhook/[merchantId], captures the signing secret into your Vault.
See the full payout walkthrough →

Why this matters

The differentiation in two sentences.

Goaffpro pays affiliates via PayPal Mass Payments. Refersion does manual ACH and charges 2.5% per transaction. FirstPromoter exports a CSV you upload to your bank.

Cobalz issues real Mercury invoices automatically, with idempotency keys, status reconciliation, and audit trail. If you bank with Mercury, this turns payday from a 4-hour task into a one-click confirmation.

  • Yes No payroll software
  • Yes No CSV exports
  • Yes No manual ACH wires
  • Yes No transaction-fee tax on every commission

FAQ

Mercury integration questions.

Do I need a Mercury account to use Cobalz?+
No. Mercury is one of four payout rails. You can launch your program on PayPal, Stripe Connect, or Wise without ever connecting Mercury. But if you do bank with Mercury, our integration is genuinely native — invoices issued, sent, reconciled, and audited end to end.
How are Mercury API keys stored?+
Per-merchant in Supabase Vault. We never see them in plaintext after the initial paste, never log them, and the platform reads them only inside the payout flow at the bottom of the call stack.
What if Mercury sends a webhook but our reconciliation cron beats it?+
No-op. Both paths funnel through the same applyMercuryStatusTransition function, gated by current payout status. We never re-mark a payout that's already paid.
How do you prevent double-invoicing on retry?+
Every payout row carries a deterministic idempotency key (payout-{merchant}-{affiliate}-{period_hash}) enforced as a UNIQUE constraint. Mercury invoice creation is the same idempotency key, so retries collapse correctly at both layers.
Mercury sandbox doesn't deliver webhooks. How do you test?+
Polling. The 15-minute reconciliation cron is the only path that detects Paid in sandbox. In production both paths run; whichever fires first wins.
Can I send a payout outside the schedule (ad-hoc)?+
Yes — there's a "Run payouts now" button on /m/{slug}/payouts. Same code path as the scheduled cron, just with mode="manual" + actor_user_id stamped on the payout_run row.
What about non-USD?+
Mercury invoices are USD only. For non-USD merchants we apply your configured fx rate (or daily OpenExchangeRates) to convert commission amounts to USD before invoicing. Affiliates outside the US should use PayPal / Stripe Connect / Wise instead.

Ready to stop wiring affiliates one at a time?

Connect your Mercury account in 60 seconds and run your first payout.

Start free trialTalk to sales