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.

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

Response (200):

{
  "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.

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

Response (200):

{
  "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.

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

Response (200):

{
  "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.

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

Response (200):

{
  "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.

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):

{
  "earnings": [...],
  "limit": 20,
  "offset": 0,
  "count": 20
}

GET /overview

Alias for /earnings. Returns the same earnings summary.

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

GET /breakdown

Returns earnings grouped by time period.

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

Response (200):

{
  "total_earned_cents": 245000,
  "unpaid_cents": 45000,
  "paid_cents": 200000,
  "breakdown": []
}

GET /transactions

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

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.

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

Response (200):

{
  "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.

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:

{
  "success": true,
  "message": "Payout initiated. Processing in background.",
  "amount_cents": 42750,
  "transfer_id": null,
  "task_id": "abc123-celery-task-id"
}

Response (200) -- below threshold:

{
  "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.

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

Response (200):

{
  "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.

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.

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).

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

Response (200):

{
  "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.

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

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

Response (200):

{
  "email_on_payout_sent": true,
  "email_on_payout_paid": true,
  "email_on_payout_failed": true,
  "sms_on_payout_paid": false
}

POST /settings/notifications

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.

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

Response (200):

{
  "url": "https://connect.stripe.com/express/acct_1234/login"
}

GET /payment-methods

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

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

Response (200):

[
  {
    "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.

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

Response (200):

[
  {
    "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

Earnings accrue -- each API call by your app's users generates an earning record (markup minus platform fee).
Threshold check -- when unpaid balance reaches $10, you become eligible for payout.
Payout triggered -- either manually via POST /payout or automatically on the weekly schedule.
Celery task -- a background worker calls stripe.Transfer.create to move funds to your Connect account.
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

Revenue Model​

Onboarding Flow​

1. Start Connect Onboarding​

2. Check Connect Status​

3. Generate Account Link (Re-onboarding)​

Earnings Endpoints​

GET /earnings​

GET /earnings/history​

GET /overview​

GET /breakdown​

GET /transactions​

Balance & Payouts​

GET /balance​

POST /payout​

GET /payout/history​

GET / (list payouts)​

Payout Settings​

GET /payout-schedule​

GET /settings/auto​

POST /settings/auto​

Notification Preferences​

GET /settings/notifications​

POST /settings/notifications​

Dashboard & Payment Methods​

POST /connect/dashboard-link​

GET /payment-methods​

Tax Forms​

GET /tax-forms​

POST /tax-forms​

GET /tax-forms/{form_id}/download​

Webhook Handling​

Payout Lifecycle​

Error Codes​

Revenue Model

Onboarding Flow

1. Start Connect Onboarding

2. Check Connect Status

3. Generate Account Link (Re-onboarding)

Earnings Endpoints

GET /earnings

GET /earnings/history

GET /overview

GET /breakdown

GET /transactions

Balance & Payouts

GET /balance

POST /payout

GET /payout/history

GET / (list payouts)

Payout Settings

GET /payout-schedule

GET /settings/auto

POST /settings/auto

Notification Preferences

GET /settings/notifications

POST /settings/notifications

Dashboard & Payment Methods

POST /connect/dashboard-link

GET /payment-methods

Tax Forms

GET /tax-forms

POST /tax-forms

GET /tax-forms/{form_id}/download

Webhook Handling

Payout Lifecycle

Error Codes