Start

Platform

App store purchases

Auth

Builds

Database

Flags

Hosting

Jobs and cron

Localization

Monitoring

Network

Notifications

Organizations

Payments

Queues

Events

Realtime

Runners

Sandboxes

Storage

Webhooks

Workflows

Getting Started

Installation

Authentication

AI Services

KV Store

Overview

Webhooks

Deploy & Infrastructure

Reference

On this page

Request
Response
MerchantAccount
ResourceMeta
Errors
Examples

Reference

Connect a merchant account

Starts connecting a Stripe account: returns the processor's authorisation URL for an org owner to open, which the processor's redirect…

Checked 2026-09-28

Starts connecting a Stripe account: returns the processor's authorisation URL for an org owner to open, which the processor's redirect completes. With a restricted key in the request the account connects at once instead, and the connected merchant account comes back in the response.

Path POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/merchant_accounts:connect
Scope billing:write
Effect write — a successful call changes state.
Collection merchant_accounts

#Request

Field	Type	What it is
`parent`	`string`	The environment whose seller this becomes. Required.
`merchant_account_id`	`string`	The merchant account id; default `default`.
`return_url`	`string`	Where the browser returns after the processor, with `status` and, on success, `merchant_account` in the query. HTTPS only. Required for the OAuth connection; unused, and so optional, with `restricted_key`.
`restricted_key`	`string`	A Stripe restricted key (`rk_test_…` or `rk_live_…`); when set, no OAuth happens: the account is read and connected at once. Write-only: sealed on write, never returned, never logged. A secret key (`sk_…`) is refused, because a restricted key can be limited to what payments need. Never returned again.

#Response

Field	Type	What it is
`authorize_url`	`string`	The processor's authorisation page for an owner of the account to open; empty when the connection completed in this call.
`expire_time`	`timestamp`	When the link stops working; unset when the connection completed in this call.
`merchant_account`	`MerchantAccount`	The merchant account, connected; set when the connection completed in this call, which is every connection made with a restricted key.

#MerchantAccount

Field	Type	What it is
`name`	`string`	`orgs/{org}/projects/{project}/envs/{env}/merchant_accounts/{merchant_account}`; the environment's seller is `default`.
`uid`	`string`	`mac_<cell><ulid>`; never reused. Output only.
`meta`	`ResourceMeta`	Resource metadata.
`processor`	`string`	The processor: `stripe`. Output only.
`account_id`	`string`	The connected account id, for example `acct_1Nv…`. Output only.
`livemode`	`bool`	Whether the connection is in live mode (false is test mode). Output only.
`state`	`string`	`connected` or `disconnected`. Output only.
`charges_enabled`	`bool`	Whether the account can take payments now. Output only.
`payouts_enabled`	`bool`	Whether the account can be paid out. Output only.
`business_name`	`string`	The business name the processor holds for the account. Output only.
`region_code`	`string`	ISO 3166-1 alpha-2 country of the account. Output only.
`default_currency_code`	`string`	ISO 4217 default currency of the account, upper case. Output only.
`refresh_time`	`timestamp`	When the processor last confirmed these fields. Output only.
`credential`	`string`	How the account is called at the processor: `connect` (the platform's key acts for a connected account) or `restricted_key` (the account's own key, held sealed). Output only.

#ResourceMeta

Field	Type	What it is
`generation`	`int64`	Increases by one on every change to `spec`. Output only.
`etag`	`string`	Strong ETag (AIP-154): changes on any change to spec, status, or metadata. Send it back as `If-Match` or `etag` to make Update and Delete conditional; a mismatch fails with ABORTED / 409 `ETAG_MISMATCH`. Output only.
`create_time`	`timestamp`	When the Resource was created. Output only.
`update_time`	`timestamp`	When the Resource last changed. Output only.
`delete_time`	`timestamp`	Set while the Resource is being deleted. Output only.
`labels`	`map<string, string>`	Caller-writable, indexed labels (AIP-122 label rules).
`annotations`	`map<string, string>`	Caller-writable, unindexed annotations.
`display_name`	`string`	Caller-writable human-readable name.
`creator`	`string`	The principal that created the Resource. Output only.

#Errors

UNAUTHENTICATED — No valid key or token was presented.
PERMISSION_DENIED — The key lacks the method's permission.
INVALID_FIELD — A field failed validation.
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 describes.

#Examples

curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/merchant_accounts:connect" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Was this page helpful?

Tell us what is missing, wrong, or unclear — this opens a real inbox.

Send feedback

Platform links