---
# @generated by sylphx-gen 0.1.0 from contracts@e145cc7cf1bc9605f2b27439e5e17ed76a1a2fd7e7021906a013f7565e4a0cd5. Do not edit.
title: "Setup payment method on a billing account"
description: "`billing.billing_accounts.setup_payment_method` (POST /v1/{name}:setupPaymentMethod): Starts saving a payment method for the org: returns a client secret the console confirms with Stripe.js, so card data never reaches Sylphx."
type: reference
product: platform
summary: "Starts saving a payment method for the org: returns a client secret the console confirms with Stripe.js, so card data never reaches Sylphx."
updated: 2026-09-28
nav: false
---

> **This method is not served on the public API.** `api.sylphx.com` does not route this call: its backend is not deployed behind the public API, or does not implement the call. This page documents the contract. It is kept out of the sidebar and of search engines.

Starts saving a payment method for the org: returns a client secret the console confirms with Stripe.js, so card data never reaches Sylphx. The saved method becomes the account's default and is charged off-session for each finalized invoice.

**Not available yet.** Sylphx Billing is declared in the registry but no backend serves it: every call answers `501` with the problem code `UNIMPLEMENTED`.

- **Path** `POST https://api.sylphx.com/v1/orgs/acme/billing_accounts/billing-account:setupPaymentMethod`
- **Scope** `billing:admin`
- **Effect** `write` — a successful call changes state.
- **Collection** [billing_accounts](/docs/api/billing_accounts)

## Request

| Field | Type | What it is |
| --- | --- | --- |
| `name` | `string` | The billing account, `orgs/{org}/billing_accounts/default`. Required. |

## Response

| Field | Type | What it is |
| --- | --- | --- |
| `provider` | `string` | The provider, `stripe`. Output only. |
| `client_secret` | `string` | The provider's client secret for this setup; single use. Output only. |
| `publishable_key` | `string` | The provider's publishable key for its client library. Output only. |

## Errors

- [`UNAUTHENTICATED`](/docs/api/errors/UNAUTHENTICATED) — No valid key or token was presented.
- [`PERMISSION_DENIED`](/docs/api/errors/PERMISSION_DENIED) — The key lacks the method's permission.
- [`RESOURCE_NOT_FOUND`](/docs/api/errors/RESOURCE_NOT_FOUND) — The named Resource does not exist or is not visible.
- [`UNAVAILABLE`](/docs/api/errors/UNAVAILABLE) — The Resource store, the owning service's backend, or the key verifier's snapshot is unavailable; retry after Retry-After.

Every error arrives in the body [Errors](/docs/platform/errors) describes.

## Examples

**cURL**

```curl
curl -X POST "https://api.sylphx.com/v1/orgs/acme/billing_accounts/billing-account:setupPaymentMethod" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**TypeScript**

```ts
const response = await sylphx.billing.billingAccounts.setupPaymentMethod({ name: 'orgs/acme/billing_accounts/billing-account' })
```

**Rust**

```rust
let mut req = sylphx::billing::SetupPaymentMethodRequest::default();
req.name = "orgs/acme/billing_accounts/billing-account".to_string();
let response = sx.billing().billing_accounts().setup_payment_method(req).await?;
```

**CLI**

```bash
sylphx billing billing-accounts setup-payment-method orgs/acme/billing_accounts/billing-account
```

**MCP**

```json
{ "method_id": "billing.billing_accounts.setup_payment_method", "args": {"name":"orgs/acme/billing_accounts/billing-account"} }
```