---
title: "Stripe Connect Integration"
description: "Earn revenue from your apps with Stripe Connect Express payouts"
canonical: "https://docs.ainative.studio/docs/developer-program/stripe-connect"
last-updated: "2026-10-13T21:42:35.442Z"
---

# Stripe Connect Integration

Source: https://docs.ainative.studio/docs/developer-program/stripe-connect

> Earn revenue from your apps with Stripe Connect Express payouts

# Stripe Connect Integration

Monetize your apps built on AINative by setting a markup on API usage. Revenue flows through Stripe Connect Express, with automated weekly payouts.

**Base path:** `/api/v1/developer/earnings`

## Revenue Model

| Parameter | Value |
|-----------|-------|
| Developer markup range | 0% -- 40% on API calls |
| Platform fee | 5% of developer earnings |
| Payout schedule | Weekly (automated via Celery) |
| Minimum payout | $10.00 (1000 cents) |
| Currency | USD |

When your app's end-users make API calls, AINative calculates your markup, deducts the 5% platform fee, and credits the remainder to your earnings balance. Once your unpaid balance reaches the $10 minimum, you become eligible for payout.

## Onboarding Flow

### 1. Start Connect Onboarding

Creates a Stripe Connect Express account (or returns a new onboarding link for an existing one) and redirects the developer to Stripe's hosted onboarding form.

```bash
curl -X POST https://api.ainative.studio/api/v1/developer/earnings/connect/onboard \
  -H "Authorization: Bearer $TOKEN"
```

**Response (200):**
```json
{
  "onboarding_url": "https://connect.stripe.com/setup/e/acct_1234/abc",
  "account_id": "acct_1234",
  "message": "Stripe Connect account created. Complete onboarding to receive payouts."
}
```

Open the `onboarding_url` in a browser to complete identity verification, bank account linking, and tax form submission.

### 2. Check Connect Status

Poll this endpoint to determine whether onboarding is complete and payouts are enabled.

```bash
curl https://api.ainative.studio/api/v1/developer/earnings/connect/status \
  -H "Authorization: Bearer $TOKEN"
```

**Response (200):**
```json
{
  "account_id": "acct_1234",
  "connect_enabled": true,
  "onboarding_complete": true,
  "verified_at": "2026-05-15T10:30:00",
  "payouts_enabled": true,
  "charges_enabled": true
}
```

| Field | Description |
|-------|-------------|
| `connect_enabled` | Whether Connect is active on the user record |
| `onboarding_complete` | `true` when `charges_enabled`, `payouts_enabled`, and `details_submitted` are all true |
| `payouts_enabled` | Whether Stripe can send funds to the developer's bank account |
| `charges_enabled` | Whether Stripe can accept charges on behalf of this account |

### 3. Generate Account Link (Re-onboarding)

If onboarding was interrupted, generate a fresh link to resume.

```bash
curl -X POST https://api.ainative.studio/api/v1/developer/earnings/connect/account-link \
  -H "Authorization: Bearer $TOKEN"
```

**Response (200):**
```json
{
  "url": "https://connect.stripe.com/setup/e/acct_1234/xyz"
}
```

## Earnings Endpoints

### GET /earnings

Returns an aggregate summary of all earnings: total earned, unpaid balance, paid out, and payout eligibility.

```bash
curl https://api.ainative.studio/api/v1/developer/earnings/earnings \
  -H "Authorization: Bearer $TOKEN"
```

**Response (200):**
```json
{
  "total_earned_cents": 245000,
  "unpaid_cents": 45000,
  "paid_cents": 200000,
  "total_transactions": 1523,
  "average_per_transaction": 160,
  "eligible_for_payout": true,
  "minimum_threshold_cents": 1000
}
```

### GET /earnings/history

Paginated transaction-level earnings history.

```bash
curl "https://api.ainative.studio/api/v1/developer/earnings/earnings/history?limit=20&offset=0" \
  -H "Authorization: Bearer $TOKEN"
```

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | int | 50 | Results per page (1--100) |
| `offset` | int | 0 | Pagination offset |
| `status` | string | -- | Filter by status |

**Response (200):**
```json
{
  "earnings": [...],
  "limit": 20,
  "offset": 0,
  "count": 20
}
```

### GET /overview

Alias for `/earnings`. Returns the same earnings summary.

```bash
curl https://api.ainative.studio/api/v1/developer/earnings/overview \
  -H "Authorization: Bearer $TOKEN"
```

### GET /breakdown

Returns earnings grouped by time period.

```bash
curl https://api.ainative.studio/api/v1/developer/earnings/breakdown \
  -H "Authorization: Bearer $TOKEN"
```

**Response (200):**
```json
{
  "total_earned_cents": 245000,
  "unpaid_cents": 45000,
  "paid_cents": 200000,
  "breakdown": []
}
```

### GET /transactions

Paginated transaction history with page-based pagination (alias for `/earnings/history`).

```bash
curl "https://api.ainative.studio/api/v1/developer/earnings/transactions?page=1&pageSize=10" \
  -H "Authorization: Bearer $TOKEN"
```

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | int | 1 | Page number |
| `pageSize` | int | 10 | Results per page (1--100) |

## Balance & Payouts

### GET /balance

Returns current payout balance broken down by available and pending amounts.

```bash
curl https://api.ainative.studio/api/v1/developer/earnings/balance \
  -H "Authorization: Bearer $TOKEN"
```

**Response (200):**
```json
{
  "available": 45000,
  "pending": 0,
  "total": 45000,
  "currency": "USD"
}
```

All amounts are in **cents**. Divide by 100 to get dollars.

### POST /payout

Request a manual payout. Requires Connect onboarding to be complete and earnings to meet the $10 minimum. The payout is processed asynchronously via a Celery task.

```bash
curl -X POST https://api.ainative.studio/api/v1/developer/earnings/payout \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"confirm": true}'
```

**Response (200) -- payout initiated:**
```json
{
  "success": true,
  "message": "Payout initiated. Processing in background.",
  "amount_cents": 42750,
  "transfer_id": null,
  "task_id": "abc123-celery-task-id"
}
```

**Response (200) -- below threshold:**
```json
{
  "success": false,
  "message": "Earnings below minimum threshold: $4.50 < $10",
  "amount_cents": 450,
  "transfer_id": null,
  "task_id": null
}
```

**Error (400):**
- `"Complete Stripe Connect onboarding first"` -- Connect not enabled
- `"Payout must be confirmed"` -- `confirm` field is `false`

### GET /payout/history

Paginated history of completed and pending payouts.

```bash
curl "https://api.ainative.studio/api/v1/developer/earnings/payout/history?limit=20&offset=0" \
  -H "Authorization: Bearer $TOKEN"
```

**Response (200):**
```json
{
  "payouts": [
    {
      "id": "uuid",
      "amount_cents": 42750,
      "stripe_transfer_id": "tr_1234",
      "status": "completed",
      "earnings_period_start": "2026-05-01T00:00:00",
      "earnings_period_end": "2026-05-07T23:59:59",
      "earnings_count": 312,
      "platform_fee_cents": 2250,
      "net_payout_cents": 42750,
      "created_at": "2026-05-08T06:00:00",
      "completed_at": "2026-05-08T06:01:23"
    }
  ],
  "limit": 20,
  "offset": 0,
  "count": 1
}
```

### GET / (list payouts)

Top-level GET on the earnings router. Alias for `/payout/history`.

```bash
curl "https://api.ainative.studio/api/v1/developer/earnings?limit=20&offset=0" \
  -H "Authorization: Bearer $TOKEN"
```

## Payout Settings

### GET /payout-schedule

Returns the current auto-payout configuration.

```bash
curl https://api.ainative.studio/api/v1/developer/earnings/payout-schedule \
  -H "Authorization: Bearer $TOKEN"
```

### GET /settings/auto

Returns auto-payout settings (schedule, threshold, delay).

```bash
curl https://api.ainative.studio/api/v1/developer/earnings/settings/auto \
  -H "Authorization: Bearer $TOKEN"
```

**Response (200):**
```json
{
  "enabled": false,
  "schedule": "weekly",
  "threshold": 100000,
  "delay_days": 2
}
```

| Field | Description |
|-------|-------------|
| `enabled` | Whether auto-payouts are active |
| `schedule` | One of `daily`, `weekly`, `monthly`, `manual` |
| `threshold` | Minimum balance in cents before auto-payout triggers |
| `delay_days` | Hold period in days before payout is released |

### POST /settings/auto

Update auto-payout configuration.

```bash
curl -X POST https://api.ainative.studio/api/v1/developer/earnings/settings/auto \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "schedule": "weekly",
    "threshold": 50000,
    "delay_days": 2
  }'
```

## Notification Preferences

### GET /settings/notifications

```bash
curl https://api.ainative.studio/api/v1/developer/earnings/settings/notifications \
  -H "Authorization: Bearer $TOKEN"
```

**Response (200):**
```json
{
  "email_on_payout_sent": true,
  "email_on_payout_paid": true,
  "email_on_payout_failed": true,
  "sms_on_payout_paid": false
}
```

### POST /settings/notifications

```bash
curl -X POST https://api.ainative.studio/api/v1/developer/earnings/settings/notifications \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email_on_payout_sent": true,
    "email_on_payout_paid": true,
    "email_on_payout_failed": true,
    "sms_on_payout_paid": true
  }'
```

## Dashboard & Payment Methods

### POST /connect/dashboard-link

Generate a one-time login link to the Stripe Express dashboard where developers can view payout history, update bank details, and download tax forms.

```bash
curl -X POST https://api.ainative.studio/api/v1/developer/earnings/connect/dashboard-link \
  -H "Authorization: Bearer $TOKEN"
```

**Response (200):**
```json
{
  "url": "https://connect.stripe.com/express/acct_1234/login"
}
```

### GET /payment-methods

Returns external accounts (bank accounts and cards) linked to the Connect account.

```bash
curl https://api.ainative.studio/api/v1/developer/earnings/payment-methods \
  -H "Authorization: Bearer $TOKEN"
```

**Response (200):**
```json
[
  {
    "id": "ba_1234",
    "type": "bank_account",
    "bank_name": "Chase",
    "account_holder_name": "Jane Developer",
    "last4": "6789",
    "currency": "USD",
    "is_default": true,
    "status": "verified"
  }
]
```

## Tax Forms

### GET /tax-forms

List uploaded W9 and 1099-K forms.

```bash
curl https://api.ainative.studio/api/v1/developer/earnings/tax-forms \
  -H "Authorization: Bearer $TOKEN"
```

**Response (200):**
```json
[
  {
    "id": "uuid",
    "type": "W9",
    "year": 2026,
    "status": "approved",
    "file_url": "https://...",
    "submitted_at": "2026-01-15T12:00:00",
    "approved_at": "2026-01-16T09:00:00"
  }
]
```

### POST /tax-forms

Upload a tax form. Currently returns `501 Not Implemented` -- use the Stripe Connect dashboard instead.

### GET /tax-forms/\{form_id\}/download

Download a tax form. Currently returns `501 Not Implemented` -- use the Stripe Connect dashboard instead.

## Webhook Handling

AINative processes the following Stripe Connect webhook events:

| Event | Action |
|-------|--------|
| `account.updated` | Updates `connect_enabled`, `payouts_enabled`, and `verified_at` on the user record |
| `transfer.created` | Logs the transfer and updates payout status to `processing` |
| `transfer.paid` | Marks the payout as `completed` with `completed_at` timestamp |
| `transfer.failed` | Marks the payout as `failed` and triggers a failure notification |

Webhook signatures are verified using the `STRIPE_WEBHOOK_SECRET` environment variable before processing.

## Payout Lifecycle

1. **Earnings accrue** -- each API call by your app's users generates an earning record (markup minus platform fee).
2. **Threshold check** -- when unpaid balance reaches $10, you become eligible for payout.
3. **Payout triggered** -- either manually via `POST /payout` or automatically on the weekly schedule.
4. **Celery task** -- a background worker calls `stripe.Transfer.create` to move funds to your Connect account.
5. **Stripe processes** -- funds arrive in your bank account per Stripe's standard settlement schedule (typically 2 business days).

## Error Codes

| Status | Detail | Cause |
|--------|--------|-------|
| 400 | `Complete Stripe Connect onboarding first` | Connect not enabled on user |
| 400 | `Payout must be confirmed` | Missing `confirm: true` in request body |
| 400 | `No Stripe Connect account found` | No account created yet |
| 500 | `Failed to start onboarding` | Stripe API error during account creation |
| 500 | `Failed to get Connect status` | Stripe API error retrieving account |