Resources

Strimz exposes a small number of resources. Most have a lifecycle of statuses that's worth knowing before you start wiring webhooks.

Merchant

You, basically. Created by Privy on first login. Holds business info (name, sector, country, payout address) and configuration (active capabilities, agent settings). Most other resources hang off merchantId.

Customer

Anyone who has paid you. Strimz creates a Customer row automatically the first time a wallet pays one of your sessions or subscriptions. Unique on (merchantId, walletAddress). The same wallet across two merchants is two distinct rows.

PaymentSession

A one-shot checkout. You create one with an amount, currency, and (optional) description. Strimz returns a checkoutUrl. The customer pays. The session goes through:

created  →  awaiting_payment  →  submitted  →  confirmed
                    ↘  expired           ↘  failed

A session can also be cancelled. Sessions expire after 30 minutes by default; set expiresInMinutes (up to 1440) to change that. A session still created or awaiting_payment at its expiry moves to expired, fires payment.failed, and can no longer be paid. Refunds are tracked on the transaction, not as a session status.

Subscription + SubscriptionPlan

A SubscriptionPlan is the template (name, amount, interval, intervalCount). A Subscription is the instance: a specific customer subscribed to a specific plan.

trialing  →  active  →  at_risk  →  lapsed
                 ↓          ↓
             cancelled   cancelled

A failed charge moves a sub from active to at_risk, and the scheduler retries on a backoff. If the recovery agent is on, it emails the customer per your strategy. If no charge succeeds within 48 hours of the period end, the sub flips to lapsed and stops attempting charges. See Subscription lifecycle. The customer can also cancel directly from their wallet. The indexer projects SubscriptionCancelled and Strimz marks the row.

SubscriptionCharge

One charge attempt. The scheduler sends the charge when a sub is due, and the indexer writes the row from the contract's event. Idempotency comes from chargeAttemptId = keccak256(abi.encodePacked(onchainSubId, currentPeriodEndAt, attempt)); the contract skips a reused id with outcome duplicate.

pending  →  succeeded  ↦  Transaction(kind=subscription_charge)
       ↘   failed (with outcome enum)

Transaction

A confirmed on-chain payment. There are several kinds:

Transaction.amount is in smallest token units (USDC has 6 decimals). feeAmount is the Strimz platform fee at the merchant's tier. netAmount is what landed in the merchant's payout wallet.

Refund

Server-side intent, wallet-signed transfer.

awaiting_signature  →  submitted  →  completed
                                ↘  failed

You create the refund. Strimz validates the amount against Transaction.amount so cumulative refunds cannot exceed the original. On the dashboard, your Strimz wallet then signs and sends the ERC-20 transfer. The indexer sees the on-chain transfer and flips the row to completed.

strimz.refunds.create returns { refund, signingInstructions }: the refund and the transfer to sign.

Invoice

A bill with a number, line items and a due date, backed by a PaymentSession. Sending it emails the buyer the breakdown and a link to that session's hosted checkout. There is no separate hosted invoice page; a PDF is available from the dashboard.

draft  →  sent  →  paid
            ↘   overdue

Any unpaid invoice can be moved to void. A sent invoice that passes its dueAt unpaid flips to overdue (hourly cron) and fires invoice.overdue. An overdue invoice can still be paid.

WebhookEndpoint + WebhookDelivery

An Endpoint is a URL + event subscription list + signing secret. A Delivery is one attempt to POST a specific event to a specific endpoint:

pending  →  delivered                      (2xx response)
        ↘   retrying  →  permanently_failed (after max attempts)

Every delivery is one BullMQ job. The attempts stay visible in your dashboard so you can debug a flaky receiver row by row.

AgentJob

ERC-8183 escrow job. Used by the AutoPay Agent's commerce capability to pay vendors via on-chain escrow. Agent escrow (the commerce capability) is coming soon and not available at launch.

proposed  →  accepted  →  in_progress  →  delivered  →  approved  →  completed
                                                 ↘   disputed / cancelled

proposed means it's awaiting human approval (above your configured threshold). accepted auto-fires below threshold.