Connect a payment provider
Starts connecting a payment provider to the account. Runledger works with several providers at once, and your provider still collects the money. In the sandbox the provider’s test mode connects directly and status is connected. Connecting a provider in live isn’t open yet and answers 409 with invalid_state. When it opens, the response carries a connect_session with a hosted url that a person opens to sign in at the provider, so provider credentials never pass through the API, and the first live provider waits in awaiting_confirmation until an Admin confirms it in the dashboard after the going-live review. An agent can start the connection and can’t confirm it. Needs providers:connect.
Authentication
A secret key (rl_sk_test_..., rl_sk_live_...) or a restricted key with limited scopes (rl_rk_test_..., rl_rk_live_...). A restricted key can carry agent: true and an expires_at, and is what a coding agent should hold. Keys end in a checksum so secret scanners can recognize them. People create, roll and revoke keys in the dashboard; GET /v1/api_keys lists them, masked.
Headers
Send true to see what the write would do without doing it. The response is the normal body with dry_run: true, changes (path, before, after), warnings and errors added, and nothing is stored. Validation runs as it would for a real write. The request is kept in request logs, tagged Dry run. When the same change is then made for real, its audit event has dry_run_preceded: true.
Request
The provider’s name, such as stripe, adyen or airwallex.
Response
test is the provider’s own test mode, used in the sandbox.
pending: waiting for a person to finish the hosted connection. awaiting_confirmation: the first live provider, connected at the provider and waiting for an Admin to confirm it in the dashboard after a successful sandbox test payment. It takes no payments until then. connected: ready. error: the provider refused the credentials or stopped responding. removed: taken off by DELETE, kept so payments and reconciliations that name it still resolve; it takes no new payments.
ISO 3166-1 alpha-2 billing countries it can take.
Who made a change. Runledger fills it in from the credential, so a client can’t claim to be someone else: an API key always acts as itself, the dashboard calls the API as the signed-in person, and the MCP server passes the client’s name and the person it acts for. A request that sends a Runledger-Actor header is refused with 400 parameter_unknown.