Connect a payment provider
Requires billing:connect, which is owner-only. Deliberately not billing:write: editing the catalogue is product operation, while this is what makes an environment able to take money at all.
Pasting the keys again is how they are rotated, and the rotation resets status to pending — a new credential has never been asked about, so inheriting the previous one’s health is exactly the state a botched rotation would hide.
Storing and verifying are two acts. This one stores; POST .../health asks the provider and is the only thing that writes a status.
webhook_secret is optional and omitting it leaves whatever was stored: the provider mints it when the endpoint is registered and rotates it on its own schedule, so folding it into a secret-key rotation would erase a working webhook.
A credential whose mode does not match the environment is refused before it leaves the server — most gateways put the mode in the key’s own prefix, and live keys on a test environment charge real cards from a staging deploy.
The secret key is encrypted at rest and never returned.
Autorizações
A staff session token, uk_st_…. Minted by sign-up, sign-in or the two-factor exchange.
Cabeçalhos
The organization the caller is acting on — the org_… code that appears in the panel URL. It identifies; the membership JOIN is what authorizes, so a forged code reads nothing. Absent, the session's default organization answers.
Parâmetros de caminho
The environment's id.
The payment gateway. stripe today. A gateway UserKit has no adapter for is refused here rather than stored, because a connection nothing can charge is discovered at somebody's checkout.
stripe Corpo
Resposta
Connected. status is pending until the health check runs.
One payment gateway, as this environment holds it. Both secrets are absent by design: the secret key is write-only, and webhook_secret_set is the only thing said about the webhook secret.
connected and status answer different questions — a connection that exists and is unhealthy is not the same as no connection, and neither is a provider this server has no adapter for (adapter_available).
"stripe"
Whether credentials have been stored for this provider in this environment. The fields below it are present only when true.
Whether this server can talk to the gateway at all. False means the health check answers 501 whatever else is reported here.
What a gateway can do beyond the minimum every gateway can do. Every flag defaults to false, so a provider that declares nothing is treated as the weakest one — silence is never a claim. Read it to stop offering an act that would be refused.
Every flag below is always present. The object is emitted whole or not at all: absent means this server has no adapter loaded for the gateway, and it never means "some flags were left out". A reader must therefore distinguish false from missing rather than testing for falsiness — a key that is not here is not a gateway that cannot do something, it is a question nobody asked.
The connection's id. It is what a webhook endpoint is addressed by.
Each value that is not connected names a different repair — see the endpoint description.
pending, connected, invalid_credentials, mode_mismatch, account_not_ready The gateway's own sentence, for a person to read. The status says which repair; this says why. Never parse it.
The merchant account the credentials open, as the gateway names it. Empty until a health check has asked, and never erased by a later refusal — the catalogue's price mappings join by this value.
The gateway's browser-side key, where it has one. Public by design.
Whether a webhook endpoint has been registered at the gateway.
Null means the gateway has never been asked. It moves even when the check could not be completed, which is what separates a fresh pending from a stale connected.