# Stripeflare X Money OAuth Provider

OVERVIEW
OAuth provider with X integration, client-specific budgets, and automatic webhook notifications. Developers can use this to facilitate social payments in their app.

CLIENT BUDGETS
- Each user has separate balance pools per client
- Charges/budgets only use funds allocated to that client
- Total balance = sum of all client balances

PAYMENT FLOW
- 5% rake goes to platform
- Remaining amount distributed according to payout percentages
- If no payout specified, 100% goes to client_username
- Budgets can be charged multiple times until depleted or expired
- All payout amounts must be non-negative

CLIENT REQUIREMENTS:

- Implement OAUTH FLOW:
1. Redirect users to: https://x.stripeflare.com/authorize?client_id=DOMAIN&redirect_uri=URI&state=STATE
2. User completes X OAuth
3. User is redirected to your redirect_uri with authorization code
4. Exchange code for tokens at: POST /token

- Implement stripeflare config: `GET /.well-known/stripeflare.json`; should return JSON with: {"username": "your_x_username"}
- Implement payment webhook: `GET /stripeflare/{username}/{metadata}`: called when a payment completes, with bearer authorization access_token

TOKEN ENDPOINT
POST https://x.stripeflare.com/token
Content-Type: application/x-www-form-urlencoded

Parameters:
- grant_type: "authorization_code"
- code: authorization code from callback
- client_id: your domain

Response:
{
  "access_token": "uuid-token",
  "token_type": "bearer"
}


## DEPOSIT FLOW:

A. **USER VISITS DEPOSIT URL**:

GET https://x.stripeflare.com/deposit/{username}/{client_id}?message=MESSAGE&amount_usd=USD&metadata=METADATA

Example: https://x.stripeflare.com/deposit/alice/example.com?message=Order%20Payment&amount_usd=25.00&metadata=order123

Redirects to Stripe payment. Funds are allocated to the specified client_id.

- username: X username to receive funds
- client_id: domain of client (must host stripeflare.json)
- message: custom description for payment
- amount_usd: payment amount (min $0.50, max $999999)
- metadata: optional data passed to webhook

B. **When a deposit completes, webhook is called**:

1. Funds are added to user's balance for the specified client
2. System calls: GET https://{client_id}/stripeflare/{username}/{metadata}
3. Client can verify available `client_balance` via 'GET /user' endpoint (Authorization bearer token is provided to webhook)

## OTHER ENDPOINTS

USER INFO ENDPOINT
GET /user
Authorization: 'Bearer YOUR_ACCESS_TOKEN' or 'Bearer YOUR_BUDGET_URL'

Response:
{
  "x_user_id": "user_id",
  "username": "handle",
  "name": "Display Name",
  "profile_image_url": "https://...",
  "verified": true/false,
  "balance": 50.0,  // total balance in USD
  "client_balance": 20.0  // balance available for this client in USD
}

BUDGET ENDPOINT
POST /budget
Authorization: 'Bearer YOUR_ACCESS_TOKEN' or 'Bearer YOUR_BUDGET_URL'
Content-Type: application/json

Body: {
  "amount_usd": 10.0,
  "validity_seconds": 300  // optional, defaults to 300 (5 minutes)
  "client_id": string // optional, only needed if not the same client as authorization. DOMAIN of the client that creates the new budget.
}

Response: {
  "success": true,
  "budget_url": "string",
  "expires_at": "2024-01-01T12:00:00Z"
}

Creates a budget using funds from the user's balance allocated to your client.

GET BUDGET ENDPOINT (equals 'YOUR_BUDGET_URL')
GET /budget/{secret}

Response: {
  "budget_url": "https://x.stripeflare.com/budget/{secret}",
  "x_user_id": "user_id",
  "client_id": "domain",
  "client_username": "client_x_username",
  "amount_usd": 10.0,
  "remaining_amount": 8.5,
  "expires_at": "2024-01-01T12:00:00Z",
  "created_at": "2024-01-01T11:55:00Z"
}

CHARGE ENDPOINT
POST /charge
Content-Type: application/json

Authorization: 'Bearer YOUR_ACCESS_TOKEN' or 'Bearer YOUR_BUDGET_URL'
X-Budget-URL: YOUR_BUDGET_URL (optional, alternative to Authorization) //NB: charges exceeding budget remaining amount require user authorization.
Body: {
  "invalidate_budget": true|false, // optional - only if authorized with budget url - 'true' will also invalidate the rest of the budget after charging
  "client_id": string, // optional - only if budget url is tied to another client
  "amount_usd": 10.0,
  "payout": {  // optional - defaults to client_username 100%
    "username1": 0.5,  // 50% of amount after rake
    "username2": 0.3   // 30% of amount after rake
  },
  "detail": "Custom transaction description"  // optional
}

INVALIDATE BUDGET ENDPOINT
POST /invalidate
Authorization: 'Bearer YOUR_ACCESS_TOKEN' or 'Bearer YOUR_BUDGET_URL'
X-Budget-URL: YOUR_BUDGET_URL // if not provided in authorization

Invalidates budget returning remaining funds to the client budget

Response: { "success": true }

TRANSACTIONS ENDPOINT
GET /transactions?limit=100&offset=0
Authorization: Bearer YOUR_ACCESS_TOKEN or Bearer YOUR_BUDGET_URL

Response: {
  "transactions": [
    {
      "id": 123,
      "from_user_id": "456",
      "to_user_id": "789",
      "client_id": "example.com",
      "amount_usd": 5.25,
      "detail": "Payment for services",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}