Payments

Amba Payments lets your app collect money from its users. Your app is the seller; Amba is the platform that takes a small, configurable fee on each payment; the money settles to your own connected account. You stay the merchant of record for your sales — Amba never holds your funds.

The flow is two parts:

1. Onboarding (developer, one time) — create your connected account and complete a hosted setup link. This collects your business + bank details directly; Amba never sees identity documents.
2. Charging (runtime) — your backend creates a payment for an order and gets back a client secret; your app completes the payment on-device with the standard payment sheet, using that client secret.

Onboarding

Create the account and get a hosted setup link in one command:

amba payments setup --country US

This prints your account status and a setup URL — open it to finish (business details + bank account). Status updates automatically when setup completes.

Agents can do the same with two MCP tools:

• amba_payments_account_create — create the connected account.
• amba_payments_create_onboarding_link — get the hosted setup URL (surface it to the human as a copy box).

Check progress any time:

amba payments status

{
  "connected_account": {
    "onboarding_status": "active",
    "charges_enabled": true,
    "payouts_enabled": true,
    "default_platform_fee_bps": 250
  }
}

charges_enabled must be true before you can take a payment.

The platform fee

Amba takes a platform fee on every payment, and your project's tier sets its minimum. The percentage part is rounded up, and the fixed part is in the payment currency's smallest unit (30 = $0.30 on a USD payment):

You can raise the fee. Set a default taken on every payment, in basis points (1000 = 10%):

amba payments set-fee 1000

A per-charge fee (application_fee_amount or platform_fee_bps) overrides the default. Whatever you ask for, a payment takes at least the tier minimum: a lower fee, a fee of 0, or no fee at all is raised to it. Pass off to clear the default, and every payment then takes the minimum. A payment too small to cover the minimum is refused with 400 FEE_EXCEEDS_AMOUNT. The account read (amba_payments_account_status) shows your tier's minimum as platform_fee_minimum.

A refund (amba_payments_refund) returns the refunded amount to your customer from your balance. Amba keeps the platform fee it took on the payment.

Taking a payment

Create the payment from your backend (server key) so the amount and fee are never set by the client:

POST /v1/client/payments/intents
X-Api-Key: <your server key>

{ "amount": 1999, "currency": "usd", "client_reference": "order_123" }

amount is in the smallest currency unit (cents). The response carries a client_secret:

{ "data": { "payment_id": "...", "client_secret": "...", "status": "requires_payment_method" } }

Pass the client_secret to your app and complete the payment on-device with the platform's standard payment sheet — the client_secret is accepted by any Stripe-compatible mobile/web payment SDK (e.g. the native payment sheet on iOS and Android, or Stripe.js on the web). Amba does not ship its own confirm method; you drive the standard payment UI with the secret. Read a payment's status with GET /v1/client/payments/intents/:id.

Balance & payouts

See what you've earned and what's been paid out to your bank:

amba payments balance
amba payments payouts --limit 10

Or via MCP: amba_payments_balance, amba_payments_payouts.

Reference

Developer-side routes mount under /v1/admin/projects/:projectId/payments/* and require developer credentials (a PAT or console session) — payments configuration is an owner action.