Payments

Create a payment intent for an order from your backend and read its status — your app completes the payment on-device with the returned client secret.

The client payments surface creates a payment for an order and reads its status. Your app is the seller; Amba is the payments rail. Your backend creates the payment and gets back a client_secret; your app then completes the payment on-device with the platform's standard payment sheet using that secret. See the Payments guide for the end-to-end flow and Admin API — payments for onboarding + reporting.

Creating a payment requires a server key — call POST /intents from your backend, never from client code. The amount and fee are money-moving inputs and must originate from your server. A client key is rejected with 403 SERVER_KEY_REQUIRED.

Amba Payments availability is enabled per platform. Creation returns 503 PAYMENTS_NOT_ENABLED until the platform owner finishes enabling it. Check amba payments status.

Endpoints

Method	Path	Description
POST	`/client/payments/intents`	Create a payment intent for an order. Server key.
GET	`/client/payments/intents/:id`	Read a payment's current status.

POST /client/payments/intents

Creates a payment intent for an amount your app is collecting and returns a client_secret. Pass the client_secret to your app and complete the payment on-device with any Stripe-compatible client SDK (the native payment sheet on iOS and Android, or Stripe.js on the web). Amba does not ship its own confirm method.

Request

Field	Type	Required	Description
`amount`	integer	yes	Positive integer in the smallest currency unit (e.g. cents).
`currency`	string	yes	Three-letter ISO currency code, lowercase (e.g. `usd`).
`application_fee_amount`	integer	no	Explicit platform fee (smallest unit). Overrides `platform_fee_bps` and the default.
`platform_fee_bps`	integer	no	Platform fee in basis points `0`–`10000`. Used if `application_fee_amount` is absent.
`client_reference`	string	no	Your order reference (≤255 chars). When set, makes a retried create idempotent on this key.

Response 200

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

Errors

403 SERVER_KEY_REQUIRED — called with a client key; create from your backend with a server key.
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 via the admin config).
400 FEE_EXCEEDS_AMOUNT — the fee is not less than the amount.
409 PAYMENTS_NOT_SET_UP — payments aren't set up for this app yet.
409 PAYMENTS_NOT_READY — 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 PAYMENT_PROVIDER_UNAVAILABLE — the payment provider is temporarily unavailable; retry.

Curl:

curl -X POST '${BASE_URL}/client/payments/intents' \
  -H 'X-Api-Key: ${SERVER_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{ "amount": 1999, "currency": "usd", "client_reference": "order_123" }'

GET /client/payments/intents/:id

Reads a payment's current status off Amba's own ledger (scoped to this project, so an app can't read another project's payment).

Response 200

{
  "data": {
    "payment_id": "pi_…",
    "status": "succeeded",
    "amount": 1999,
    "currency": "usd",
    "client_reference": "order_123"
  }
}

Errors

404 PAYMENT_NOT_FOUND — no payment with that id for this project.
503 CONTROL_PLANE_UNAVAILABLE — could not read the payment; retry.

Curl:

curl -X GET '${BASE_URL}/client/payments/intents/pi_123' \
  -H 'X-Api-Key: ${SERVER_API_KEY}'

Reference

Payments guide — the end-to-end onboarding + charging flow.
Admin API — payments — onboarding, fees, balance, payouts.

On this page