Stripe Connect Marketplace & Transaction Flow
Integrate two-party agreed transactions, embedded seller onboarding via Stripe Connect Express, customizable platform fees, and cryptographically signed outbound webhooks.
Architecture Overview
Payeny provides marketplaces and multi-party commerce platforms with direct onboarding and checkout capabilities. Under the Connect marketplace architecture:
- Express Connected Accounts: Sellers are onboarded to Stripe Express connected accounts for payouts and account management (merchant of record model is TBD).
- Embedded Onboarding: Onboarding is embedded inline in your platform UI using Stripe Connect web components with secure, transient account sessions.
- Two-Party Agreement: Transactions enforce seller consent and buyer agreement before payment links can be issued, logging timestamped consent events.
- Zero Sensitive Data Storage: Payeny never stores government IDs, Social Security Numbers, EINs, or bank account routing numbers. Sensitive verification is handled directly by Stripe.
Seller Accounts API
/api/v1/connect/accounts
Create a new Express connected account for a marketplace seller with prefilled profile details.
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Seller email address. |
name | string | No | Full legal name or business display name. |
business_type | string | No | individual (default) or company. |
business_profile[url] | string | No | Seller public profile or storefront URL. |
country | string | No | Two-letter ISO country code (default US). |
Example Request
curl -s -X POST https://payeny.com/api/v1/connect/accounts \
-H "Authorization: Bearer sec_test_merchant_sandbox_key" \
-d email=seller@example.com \
-d name="Sarah Jenkins" \
-d "business_profile[url]=https://florencefinder.com/u/seller"
Example Response (201 Created)
{
"data": {
"id": "acct_XXXXXXXX",
"object": "account",
"type": "express",
"email": "seller@example.com",
"status": "action_needed",
"status_badge": "Action needed",
"status_reason": "Action needed: Missing required onboarding information: bank account or payout method, photo ID or SSN, address.",
"livemode": false
},
"livemode": false
}
Embedded Onboarding Sessions
/api/v1/connect/accounts/{id}/onboarding_session
Generate a transient client secret to mount the embedded Stripe Connect onboarding component in your frontend.
HTTP 403 Forbidden. Client secrets are never written to logs or stored in the database.
Example Request
curl -s -X POST https://payeny.com/api/v1/connect/accounts/acct_XXXXXXXX/onboarding_session \
-H "Authorization: Bearer sec_test_merchant_sandbox_key"
Example Response (201 Created)
{
"data": {
"object": "account_session",
"client_secret": "set_1UTxxx_secret_xxx",
"account": "acct_XXXXXXXX",
"livemode": false
},
"livemode": false
}
Account Requirements & Status Badges
The status and badges returned by GET /api/v1/connect/accounts/{id} strictly adhere to verification requirements:
| Status Badge | Status Code | Triggering Conditions |
|---|---|---|
| Action needed | action_needed |
requirements.past_due or requirements.currently_due is non-empty, or disabled_reason is set. Returns a plain-English message itemizing the missing requirements. |
| Pending | pending |
Only eventually_due is non-empty, or pending_verification is non-empty. Indicates verification is currently being processed by Stripe. |
| Active | active |
Both charges_enabled and payouts_enabled are true and no verification requirements are pending or due. |
Two-Party Agreement Transactions
In classifieds, peer-to-peer commerce, and services marketplaces, orders require bilateral agreement before funds can be collected.
/api/v1/transactions
Initiate a two-party transaction in initial pending_seller status.
Example Request
curl -s -X POST https://payeny.com/api/v1/transactions \
-H "Authorization: Bearer sec_test_merchant_sandbox_key" \
-H "Content-Type: application/json" \
-d '{
"seller_account_id": "acct_XXXXXXXX",
"item_title": "Solid Oak Kitchen Table",
"amount_cents": 4500,
"platform_fee": { "amount": 25, "mode": "buyer_pays" }
}'
State Machine & 409 Conflict Errors
Transactions transition sequentially: pending_seller → pending_buyer → agreed → paid → completed.
- Pre-Agreement Payment Link Block: Requesting
GET /api/v1/transactions/{id}/payment_linkbefore status reachesagreedreturnsHTTP 409 Conflict(code:agreement_incomplete). - Out-of-Order Consents: Attempting buyer agreement while still in
pending_sellerreturnsHTTP 409 Conflict. - Consent Endpoints: Submit
POST /api/v1/transactions/{id}/agreewith{"actor": "seller"}then{"actor": "buyer"}. Every consent is audit-logged with actor, timestamp, and IP address.
Platform Fee Modes (buyer_pays vs merchant_absorbs)
Payeny platform fee is $0.25 per transaction for fee-enabled transactions (merchants with fees disabled pay 0). Dual fee modes are supported:
| Fee Mode | Buyer Total | Seller Net | Stripe Fee Collection |
|---|---|---|---|
buyer_pays |
Base price + fee (itemized as separate "Service fee" line item) | Base price minus Stripe processing fee | Collected as application_fee_amount into platform balance |
merchant_absorbs |
Base price (no extra buyer surcharge) | Base price minus Stripe fee minus platform fee | Collected as application_fee_amount deducted from seller payout |
Mode-Scoped Balance API
/api/v1/balance
Retrieve available and pending settlement balances for the authenticated merchant account.
Example Request
curl -s -H "Authorization: Bearer sec_test_merchant_sandbox_key" https://payeny.com/api/v1/balance
Example Response (200 OK)
{
"data": {
"object": "balance",
"available": [{ "amount": 0, "currency": "usd" }],
"pending": [{ "amount": 26466, "currency": "usd" }],
"livemode": false
},
"livemode": false
}
Outbound Webhook Events & Signatures
When transaction states change, hosted checkouts finish, or subscriptions activate, signed outbound webhooks are dispatched to your configured endpoint URL:
checkout.completed: Customer completes payment or subscription signup on hosted checkout (or Stripe checkout.session.completed).checkout.session.completed: Embedded or custom checkout session is completed and order fulfilled.payment.created: A new direct payment or charge attempt is initiated via API.payment.succeeded: Direct payment or checkout payment is successfully settled and confirmed.payment.captured: An authorized payment is captured.payment.canceled: An uncaptured payment or authorization is canceled.payment.failed: A payment intent or card authorization attempt fails.refund.created: Full or partial refund is issued via API, admin dashboard, or Stripe sync.subscription.created: A new recurring subscription is created via API, hosted checkout, or sync.subscription.updated: Subscription plan changes, cancellation is scheduled, subscription is resumed, or status updates.subscription.canceled: Subscription is canceled immediately or reaches the end of its billing cycle.subscription.renewed: Subscription successfully renews for a subsequent billing period.subscription.payment_failed: Recurring subscription billing cycle charge attempt fails.invoice.created: A new customer billing invoice is generated.invoice.paid: Initial or recurring subscription invoice payment succeeds.invoice.payment_failed: Invoice charge attempt fails (e.g. card declined or insufficient funds).dispute.created: Customer files a payment dispute or chargeback with issuing bank.dispute.closed: Dispute inquiry is resolved, won, or lost.payout.status: Payout transfer to seller external bank account updates status (paid, failed, pending).transaction.agreed: Both buyer and seller complete mutual agreement on a marketplace transaction.merchant.created: A new connected merchant workspace is created.merchant.updated: Connected merchant profile, status, or payout capability updates.portal.session.created: Customer billing management portal session is created.portal.session.accessed: Customer accesses their self-service billing portal session.usage.recorded: Metered usage event is recorded for a subscription customer.usage.invoiced: Aggregated metered usage is finalized and invoiced.
Idempotency & Event Deduplication
Every webhook payload carries a unique, canonical 20-hex event identifier matching ^evt_[0-9a-f]{20}$. Because networks may retry deliveries, always deduplicate incoming webhooks by recording or checking the event.id in your database before provisioning resources. If an event ID has already been processed, return HTTP 200 OK immediately without re-executing business logic.
Example Payload: checkout.completed
{
"id": "evt_3a1b2c3d4e5f6a7b8c9d",
"object": "event",
"type": "checkout.completed",
"created": 1792700000,
"livemode": false,
"merchant": "florencefinder",
"data": {
"object": {
"session_id": "cs_7f8e9d0a1b2c3d4e5f6a7b8c",
"order_reference": "ORD-261022-7F8E9",
"subscription_id": "sub_4b5c6d7e8f9a0b1c2d3e",
"stripe_subscription_id": "sub_test_1UTSubFake0001",
"customer_id": "cus_1a2b3c4d5e6f7a8b9c0d",
"payment_id": "pay_356c860bac52fa30ec10",
"client_reference_id": "client_ref_123",
"amount_cents": 2900,
"amount_total": 2900,
"currency": "usd",
"status": "succeeded"
}
}
}
Example Payload: subscription.created
{
"id": "evt_9f8e7d6c5b4a3f2e1d0c",
"object": "event",
"type": "subscription.created",
"created": 1792700001,
"livemode": false,
"merchant": "florencefinder",
"data": {
"object": {
"subscription_id": "sub_4b5c6d7e8f9a0b1c2d3e",
"stripe_subscription_id": "sub_test_1UTSubFake0001",
"customer_id": "cus_1a2b3c4d5e6f7a8b9c0d",
"plan_name": "Pro Seller Membership",
"amount_cents": 2900,
"currency": "usd",
"status": "active"
}
}
}
Payload Signature Verification
Every webhook request includes a Payeny-Signature header with timestamp t and HMAC-SHA256 signature v1:
Payeny-Signature: t=1792701200,v1=9b1e9564b7324fa9cb90728c3c2b8c5a246876...
To prevent replay attacks, verify the timestamp tolerance window is within 300 seconds (5 minutes) of current time:
<?php
$payload = file_get_contents('php://input');
$sigHeader = $_SERVER['HTTP_PAYENY_SIGNATURE'] ?? '';
// Parse timestamp and v1 signature
preg_match('/t=(\d+),v1=([a-f0-9]+)/', $sigHeader, $matches);
$timestamp = (int)($matches[1] ?? 0);
$signature = $matches[2] ?? '';
// 300-second tolerance window check
if (abs(time() - $timestamp) > 300) {
http_response_code(400);
exit('Webhook timestamp outside acceptable tolerance window.');
}
// Compute expected signature
$signedPayload = "{$timestamp}.{$payload}";
$expectedSig = hash_hmac('sha256', $signedPayload, $webhookSecret);
if (!hash_equals($expectedSig, $signature)) {
http_response_code(401);
exit('Invalid signature.');
}
// Process valid webhook event
$event = json_decode($payload, true);
http_response_code(200);