Skip to navigation
API ReferenceProviders and paymentsPayment providers

Update a payment provider

Makes this provider the account default, or changes the currencies and countries Runledger will route to it. The old default stops being the default. Customers who already saved a payment method stay with the provider that holds it.

Authentication

AuthorizationBearer

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.

Path parameters

payment_provider_idstringRequired

The payment provider ID (pp_...).

Headers

Runledger-Dry-RunbooleanOptional

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

This endpoint expects an object.
is_defaultbooleanOptional
currencieslist of stringsOptional
countrieslist of stringsOptional

Response

The provider connection.
idstring
object"payment_provider"
providerstring
The provider's name, unique within an environment. New providers may be added.
modeenum

test is the provider’s own test mode, used in the sandbox.

Allowed values:
statusenum

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.

Allowed values:
is_defaultboolean
Used when the customer has no override and no routing rule matches.
currencieslist of strings
Lowercase ISO 4217 codes the provider can take.
countrieslist of strings

ISO 3166-1 alpha-2 billing countries it can take.

capabilitieslist of enums
What Runledger can do through this provider. Runledger collects by cards and payment links.
Allowed values:
livemodeboolean
created_atdatetime
connect_sessionobjectOptional
Present while a person still has to finish connecting in live mode.
actorobjectOptional

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.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error