How Clive Works

End-to-end transaction architecture

Clive is an orchestration layer between partner systems and payout rails.

Partner Backend -> Clive /transactions/initialize
Partner Backend -> Stripe create PaymentIntent
Partner Backend -> Clive /transactions/attach-intent
Customer Frontend -> Stripe confirm payment
Stripe -> Clive /webhooks/stripe
Clive -> Partner webhook_url (signed status callback)
Clive settlement engine -> batch + payout

PaymentIntent ownership

Production partner integration:

• Partner backend creates Stripe PaymentIntent.
• Partner backend sets statement_descriptor_suffix.
• Clive stores and tracks transaction state via initialize/attach + webhooks.

Sandbox integration:

• /sandbox/checkout-intent is a test helper endpoint that creates a Stripe PaymentIntent for demo/testing only.
• Do not model production ownership from sandbox helpers.

Transaction statuses

Status	Meaning
initialized	Transaction created in Clive but not yet linked to Stripe intent
pending	Stripe PaymentIntent linked, awaiting final payment outcome
succeeded	Payment confirmed, fees and payout values computed
failed	Payment failed
refunded	Payment later refunded
chargeback	Dispute/chargeback opened

Settlement statuses

Field	Values	Description
settlementStatus on transaction	unsettled, queued, paid	Indicates whether transaction has entered and completed settlement
status on settlement batch	pending, sent, failed	Indicates payout progression for a batch

Security model

• API key gate for partner endpoints.
• HMAC signature validation for mutation endpoints.
• Idempotency replay store for safe retries.
• Stripe webhook signature validation on Clive side.
• Signed partner notifications (X-Clive-Signature) from Clive.

Fee model

On successful transaction:

• stripeFeePercent defaults to 2.9 with an additional fixed $0.30 processor fee
• partnerFeePercent comes from partner profile
• partnerPayoutPercent = 100 - partnerFeePercent
• cliveEarningPercent = partnerFeePercent - stripeFeePercent

Computed amounts are stored and exposed in reporting/admin endpoints.