Subscriptions

​

Concepts

• Plan — amount in USD-pegged USDC (6 decimals), interval (day|week|month|year), optional trial, optional max cycles, accepted chains/assets. Price is immutable: create a new plan to change it.
• Subscription — one customer on one plan. States: incomplete → trialing → active → past_due → unpaid, plus paused, canceled, expired.
• Mandate — the customer’s on-chain authorization. Solana: a capped SPL delegate approval (never unlimited).
• Invoice — one per billing period. Gross, platform fee and net are stored in integer base units.
• Charge attempt — one signed send with a unique idempotency key. Ambiguous sends are reconciled on-chain before any retry.
• Delegate wallet — a dedicated Solana hot wallet that customers approve to pull USDC. It pays network fees and must hold SOL. It is never the vault or treasury key.

​

How Solana subscriptions work

1. Merchant creates a plan.
2. Merchant sends the hosted subscribe link (or creates a checkout through the API).
3. Customer connects a Solana wallet and reviews the exact amount, interval, first charge and maximum authorization.
4. Customer signs one ApproveChecked transaction granting the Tribridge delegate a capped allowance: amount × min(max_cycles, default_cap_cycles). The default cap is 12 cycles.
5. Backend verifies the delegate, allowance, balance and token account.
6. No trial: the first invoice is charged immediately. Trial: first charge at trial_end.
7. On renewal: re-check the mandate, then the delegate signs one TransferChecked for exactly one cycle to the treasury.
8. If the delegate was replaced or revoked, the allowance is too low, or the balance is insufficient, the backend does not send and starts dunning + a needs-reauthorization notice.

​

Create a plan

curl -X POST https://api.tribridge.xyz/v1/plans \
  -H "x-api-key: tri_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro",
    "amount_usd": "9.99",
    "interval": "month",
    "trial_days": 7,
    "max_cycles": 12,
    "accepted_chains": ["solana"],
    "accepted_assets": ["USDC"]
  }'

​

Create a hosted subscription checkout

curl -X POST https://api.tribridge.xyz/v1/subscriptions/checkout \
  -H "x-api-key: tri_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "PLAN_UUID",
    "customer_ref": "user_123",
    "customer_email": "user@example.com",
    "success_url": "https://merchant.example/thanks"
  }'

​

API vs dashboard

​

Lifecycle

1. Customer reviews the terms and authorizes in their wallet.
2. No trial: first invoice charged immediately. Failure → incomplete (expires after 24h).
3. Trial: trialing; first invoice at trial_end.
4. Renewals: invoice at next_billing_at, mandate re-verified, charge executed.
5. Failures: typed reason, retry at +1/+3/+5 days, past_due after the first failure, invoice.failed webhook, then canceled/unpaid per plan policy.
6. max_cycles reached → expired.

​

Endpoints

​

Webhooks

​

Fees and ledger

​

Test mode

curl -X POST https://api.tribridge.xyz/v1/test/subscriptions/SUB_ID/advance \
  -H "x-api-key: tri_test_..." \
  -d '{"failure":"insufficient_balance"}'

​

Mainnet requirements (Solana)

SOLANA_NETWORK=mainnet
SOLANA_RPC_URL=https://mainnet.helius-rpc.com/?api-key=...
SOLANA_USDC_MINT=
HELIUS_API_KEY=...
HELIUS_WEBHOOK_ID=...
HELIUS_WEBHOOK_AUTH_SECRET=...

SUBSCRIPTIONS_ENABLED=true
SUBSCRIPTIONS_SOLANA_ENABLED=true
SUBSCRIPTIONS_SUI_ENABLED=false
WALLET_CONNECT_PAY_ENABLED=true
WALLET_CONNECT_SUI_ENABLED=false

SUBSCRIPTIONS_SOLANA_DELEGATE_PRIVATE_KEY=<base58 delegate secret>
SUBSCRIPTIONS_SOLANA_TREASURY_ADDRESS=<Solana treasury/vault address>
SUBSCRIPTIONS_SOLANA_DEFAULT_CAP_CYCLES=12

​

Refunds