Payments

The admin payments surface onboards your app to accept payments, configures the platform fee, creates charges server-side, and reports your balance + payouts. Your app is the seller; Amba is the platform that takes a configurable fee; the money settles to your own connected account. See the Payments guide for the end-to-end flow.

All routes mount under /v1/admin/projects/:projectId/payments/* and require developer credentials (a PAT or console session) — payments configuration is an owner action. The end-user (app-side) intent surface is documented at Client API — payments.

Endpoints

POST /admin/projects/:projectId/payments/accounts

Creates the project's connected account. Idempotent — if an account already exists it is returned unchanged (one project → one account).

Request

Response 201

{
  "data": {
    "stripe_account_id": "acct_…",
    "account_type": "express",
    "onboarding_status": "pending",
    "charges_enabled": false,
    "payouts_enabled": false,
    "details_submitted": false,
    "capabilities": {},
    "country": "US",
    "default_platform_fee_bps": null
  }
}

An idempotent return of an existing account responds 200 with the same shape.

Errors

• 400 INVALID_BODY — body is not valid JSON.
• 503 PAYMENTS_NOT_ENABLED — Amba Payments is not enabled on this platform yet.
• 503 CONTROL_PLANE_UNAVAILABLE — could not read/persist the account; retry.
• 502 STRIPE_UNAVAILABLE — the payment provider is unavailable; retry.

POST /admin/projects/:projectId/payments/accounts/link

Generates a hosted onboarding setup link the developer opens to finish account setup (business + bank details). The URL is single-use and short-lived — request a fresh one each time. Surface it to the human as a copy box.

Response 200

{ "data": { "url": "https://…", "expires_at": 1730000000 } }

Errors

• 409 NO_CONNECTED_ACCOUNT — create the account first (POST /payments/accounts).
• 503 PAYMENTS_NOT_ENABLED — Amba Payments is not enabled on this platform yet.
• 503 CONTROL_PLANE_UNAVAILABLE — could not read the account; retry.
• 502 STRIPE_UNAVAILABLE — the payment provider is unavailable; retry.

GET /admin/projects/:projectId/payments/accounts

Reads connected-account status from Amba's own state. Not gated (no money moves) — returns connected_account: null when no account exists yet so an agent can branch on it.

Response 200

{
  "data": {
    "connected_account": {
      "stripe_account_id": "acct_…",
      "account_type": "express",
      "onboarding_status": "active",
      "charges_enabled": true,
      "payouts_enabled": true,
      "details_submitted": true,
      "capabilities": { "card_payments": "active", "transfers": "active" },
      "country": "US",
      "default_platform_fee_bps": 250
    }
  }
}

charges_enabled must be true before you can create a charge.

Errors

• 503 CONTROL_PLANE_UNAVAILABLE — could not read the account; retry.

PUT /admin/projects/:projectId/payments/config

Sets the default platform fee taken on every charge, in basis points (250 = 2.5%). Pass null to clear the default (each charge must then specify its own fee). A per-charge fee always overrides the default.

Request

Response 200

{ "data": { "default_platform_fee_bps": 250 } }

Errors

• 400 INVALID_BODY — body missing default_platform_fee_bps or not valid JSON.
• 400 INVALID_FEE — fee is not an integer 0–10000 (or null).
• 409 NO_CONNECTED_ACCOUNT — create the account first.
• 503 CONTROL_PLANE_UNAVAILABLE — could not update config; retry.

POST /admin/projects/:projectId/payments/charges

Creates a charge (a destination charge with an application fee) on behalf of the connected account: the net (amount minus the platform fee) routes to the connected account, which is the settlement merchant. Returns a client_secret your app completes on-device with the platform's standard payment sheet.

Request

A fee is required: pass application_fee_amount, platform_fee_bps, or configure a default via PUT /payments/config. The fee must be less than the amount.

Response 200

{
  "data": {
    "payment_intent_id": "pi_…",
    "client_secret": "pi_…_secret_…",
    "status": "requires_payment_method",
    "amount": 1999,
    "currency": "usd",
    "application_fee_amount": 50
  }
}

Errors

• 400 INVALID_BODY — body is not valid JSON.
• 400 INVALID_AMOUNT — amount is not a positive integer.
• 400 INVALID_CURRENCY — currency is not a lowercase 3-letter ISO code.
• 400 INVALID_FEE — a fee field is out of range.
• 400 NO_PLATFORM_FEE — no fee resolved (pass one or set a default).
• 400 FEE_EXCEEDS_AMOUNT — the fee is not less than the amount.
• 409 NO_CONNECTED_ACCOUNT — create the account first.
• 409 CHARGES_NOT_ENABLED — onboarding incomplete; charges aren't enabled yet.
• 503 PAYMENTS_NOT_ENABLED — Amba Payments is not enabled on this platform yet.
• 503 CONTROL_PLANE_UNAVAILABLE — could not read the account; retry.
• 502 STRIPE_UNAVAILABLE — the payment provider is unavailable; retry.

GET /admin/projects/:projectId/payments/balance

Reads the connected account's balance.

Response 200

{
  "data": {
    "available": [{ "amount": 4200, "currency": "usd" }],
    "pending": [{ "amount": 900, "currency": "usd" }]
  }
}

Errors

• 409 NO_CONNECTED_ACCOUNT — create the account first.
• 503 PAYMENTS_NOT_ENABLED — Amba Payments is not enabled on this platform yet.
• 503 CONTROL_PLANE_UNAVAILABLE — could not read the account; retry.
• 502 STRIPE_UNAVAILABLE — the payment provider is unavailable; retry.

GET /admin/projects/:projectId/payments/payouts

Lists the connected account's payouts, newest first.

Query parameters

Response 200

{
  "data": [
    {
      "id": "po_…",
      "amount": 4200,
      "currency": "usd",
      "status": "paid",
      "arrival_date": 1730000000,
      "created": 1729900000
    }
  ]
}

Errors

• 409 NO_CONNECTED_ACCOUNT — create the account first.
• 503 PAYMENTS_NOT_ENABLED — Amba Payments is not enabled on this platform yet.
• 503 CONTROL_PLANE_UNAVAILABLE — could not read the account; retry.
• 502 STRIPE_UNAVAILABLE — the payment provider is unavailable; retry.

Reference

• Payments guide — the end-to-end onboarding + charging flow.
• Client API — payments — the end-user intent surface.