Skip to main content
Authenticated API

This endpoint requires a valid JWT Bearer token with integration_admin or manager roles. Accessible via the API gateway at /v1/integrations/*.

Stripe Connect API

Manage Stripe Connect marketplace payments, merchant onboarding, and payout operations.

Overview​

AttributeValue
Base Path/api/v1/integrations/stripe-connect
AuthenticationBearer Token
Required Rolespos_staff, payment_admin, tenant_admin, platform_admin, system_admin, super_admin

Account Types​

TypeDescriptionUse Case
standardFull Stripe dashboard accessLarge merchants
expressSimplified onboardingMost merchants
customFull platform controlWhite-label

Merchant Onboarding​

Create Connected Account​

Initiate merchant onboarding to Stripe.

POST /api/v1/integrations/stripe-connect/accounts

Request Body

{
  "merchant_id": "merchant_123",
  "account_type": "express",
  "business_type": "company",
  "country": "US",
  "email": "owner@restaurant.com",
  "business_profile": {
    "name": "Downtown Grill",
    "mcc": "5812",
    "url": "https://downtowngrill.com"
  },
  "capabilities": {
    "card_payments": true,
    "transfers": true
  }
}

Response

{
  "account_id": "acct_1234567890",
  "merchant_id": "merchant_123",
  "status": "pending",
  "onboarding_url": "https://connect.stripe.com/setup/...",
  "onboarding_expires_at": "2026-01-25T19:00:00Z",
  "created_at": "2026-01-24T19:00:00Z"
}

Get Account Status​

GET /api/v1/integrations/stripe-connect/accounts/{account_id}

Response

{
  "account_id": "acct_1234567890",
  "merchant_id": "merchant_123",
  "status": "active",
  "charges_enabled": true,
  "payouts_enabled": true,
  "details_submitted": true,
  "capabilities": {
    "card_payments": "active",
    "transfers": "active"
  },
  "requirements": {
    "currently_due": [],
    "eventually_due": [],
    "past_due": [],
    "disabled_reason": null
  },
  "business_profile": {
    "name": "Downtown Grill",
    "support_email": "support@downtowngrill.com"
  },
  "payout_schedule": {
    "interval": "daily",
    "delay_days": 2
  }
}

Account Status Values​

StatusDescription
pendingOnboarding not complete
activeFully active
restrictedLimited functionality
disabledAccount disabled

Create new onboarding or update link.

POST /api/v1/integrations/stripe-connect/accounts/{account_id}/onboarding-link

Request Body

{
  "return_url": "https://app.example.com/settings/payments",
  "refresh_url": "https://app.example.com/settings/payments/refresh",
  "type": "account_onboarding"
}

Create link to Stripe Express dashboard.

POST /api/v1/integrations/stripe-connect/accounts/{account_id}/dashboard-link

Response

{
  "url": "https://connect.stripe.com/express/...",
  "expires_at": "2026-01-24T19:05:00Z"
}

Payment Processing​

Create Payment Intent​

Create a payment with automatic split.

POST /api/v1/integrations/stripe-connect/payments

Request Body

{
  "account_id": "acct_1234567890",
  "amount": 2500,
  "currency": "usd",
  "order_id": "ord_xyz",
  "customer_email": "customer@example.com",
  "payment_method_types": ["card"],
  "application_fee_amount": 75,
  "metadata": {
    "order_number": "42",
    "location_id": "loc_123"
  }
}

Response

{
  "payment_intent_id": "pi_abc123",
  "client_secret": "pi_abc123_secret_xyz",
  "status": "requires_payment_method",
  "amount": 2500,
  "application_fee": 75,
  "destination_amount": 2425
}

Capture Payment​

Capture an authorized payment.

POST /api/v1/integrations/stripe-connect/payments/{payment_intent_id}/capture

Request Body

{
  "amount_to_capture": 2500
}

Refund Payment​

Issue a refund.

POST /api/v1/integrations/stripe-connect/payments/{payment_intent_id}/refund

Request Body

{
  "amount": 500,
  "reason": "customer_request",
  "refund_application_fee": true
}

Response

{
  "refund_id": "re_abc123",
  "amount": 500,
  "status": "succeeded",
  "application_fee_refunded": 15
}

Transfers​

Create Transfer​

Transfer funds to a connected account.

POST /api/v1/integrations/stripe-connect/transfers

Request Body

{
  "account_id": "acct_1234567890",
  "amount": 10000,
  "currency": "usd",
  "description": "Weekly tip payout",
  "metadata": {
    "pay_period": "2026-01-15 to 2026-01-21"
  }
}

Response

{
  "transfer_id": "tr_abc123",
  "amount": 10000,
  "currency": "usd",
  "status": "pending",
  "arrival_date": "2026-01-26"
}

Reverse Transfer​

Reverse a transfer.

POST /api/v1/integrations/stripe-connect/transfers/{transfer_id}/reverse

Request Body

{
  "amount": 5000,
  "description": "Partial reversal - error correction"
}

Payouts​

Get Payout Schedule​

GET /api/v1/integrations/stripe-connect/accounts/{account_id}/payouts/schedule

Response

{
  "interval": "daily",
  "delay_days": 2,
  "anchor_day": null,
  "next_payout_date": "2026-01-26"
}

Update Payout Schedule​

PUT /api/v1/integrations/stripe-connect/accounts/{account_id}/payouts/schedule

Request Body

{
  "interval": "weekly",
  "weekly_anchor": "friday",
  "delay_days": 2
}

List Payouts​

GET /api/v1/integrations/stripe-connect/accounts/{account_id}/payouts

Response

{
  "data": [
    {
      "payout_id": "po_abc123",
      "amount": 125000,
      "currency": "usd",
      "status": "paid",
      "arrival_date": "2026-01-24",
      "method": "standard",
      "bank_account": {
        "last4": "1234",
        "bank_name": "Chase"
      }
    }
  ]
}

Payout Status Values​

StatusDescription
pendingPayout created
in_transitFunds on the way
paidFunds deposited
failedPayout failed
canceledPayout cancelled

Platform Fees​

Get Fee Configuration​

GET /api/v1/integrations/stripe-connect/fees

Response

{
  "default_fee_percent": 2.9,
  "default_fee_fixed": 30,
  "fee_tiers": [
    {
      "volume_min": 0,
      "volume_max": 10000,
      "fee_percent": 3.0,
      "fee_fixed": 30
    },
    {
      "volume_min": 10001,
      "volume_max": 50000,
      "fee_percent": 2.5,
      "fee_fixed": 25
    }
  ],
  "per_merchant_overrides": [
    {
      "merchant_id": "merchant_123",
      "fee_percent": 2.0,
      "fee_fixed": 20,
      "reason": "Enterprise agreement"
    }
  ]
}

Update Fee Configuration​

PUT /api/v1/integrations/stripe-connect/fees

Balance​

Get Platform Balance​

GET /api/v1/integrations/stripe-connect/balance

Response

{
  "available": [
    {"amount": 150000, "currency": "usd"}
  ],
  "pending": [
    {"amount": 25000, "currency": "usd"}
  ],
  "connect_reserved": [
    {"amount": 5000, "currency": "usd"}
  ]
}

Get Account Balance​

GET /api/v1/integrations/stripe-connect/accounts/{account_id}/balance

Disputes​

List Disputes​

GET /api/v1/integrations/stripe-connect/disputes

Response

{
  "data": [
    {
      "dispute_id": "dp_abc123",
      "payment_intent_id": "pi_xyz",
      "account_id": "acct_1234567890",
      "amount": 2500,
      "reason": "fraudulent",
      "status": "needs_response",
      "evidence_due_by": "2026-02-05T23:59:59Z",
      "created_at": "2026-01-24T10:00:00Z"
    }
  ]
}

Dispute Status Values​

StatusDescription
needs_responseEvidence required
under_reviewBank reviewing
wonDispute resolved in favor
lostDispute lost

Submit Evidence​

POST /api/v1/integrations/stripe-connect/disputes/{dispute_id}/evidence

Request Body

{
  "evidence": {
    "customer_name": "John Doe",
    "customer_email": "john@example.com",
    "receipt": "file_abc123",
    "service_documentation": "Order was fulfilled and picked up by customer"
  },
  "submit": true
}

Webhooks​

EventDescription
stripe.account_updatedAccount status changed
stripe.payout_paidPayout completed
stripe.payout_failedPayout failed
stripe.payment_succeededPayment successful
stripe.payment_failedPayment failed
stripe.dispute_createdNew dispute opened
stripe.dispute_updatedDispute status changed

Error Responses​

StatusCodeDescription
400invalid_account_typeAccount type not supported
400insufficient_balanceNot enough funds
401account_not_onboardedOnboarding incomplete
404account_not_foundStripe account not found
409payout_in_progressPayout already processing
502stripe_errorStripe API error