Connect a payment provider to your Telegram subscription bot or Discord subscription bot. Start with provider discovery to get this project's available providers and their current installation requirements.
POST/v2/projects/{project_id}/merchant-accounts
Authorization
Bearer API KeyRequired
API key access: Unrestricted project API key required. Restricted keys cannot call this endpoint.
Retries: save the initial response. Completed keyed successes are not replayed; a repeated Idempotency-Key returns 409 IDEMPOTENCY_RESPONSE_NOT_REPLAYABLE. Check account state before starting another installation attempt.
Path Parameters
project_idstringrequired
The unique identifier of the project.
Request Body
providerstringrequired
Provider ID returned as a key in the discovery response's data object. Availability depends on the project.
environmentstring
Required when discovery reports multiple_environments_supported: true; use sandbox or production. Omit it for production-only providers.
labelstring|null
Optional label (3–120 characters), or null. For generated labels, use ASCII letters/digits, spaces, hyphens, underscores or dots, starting and ending with a letter/digit.
Call GET /v2/projects/{project_id}/merchant-accounts before building the installation request. Each key in its data object is a provider ID; that provider's entry describes the fields to collect:
Discovery field
How to use it
required_params
Declared credential field names. Some may be optional; also check optional_params.
optional_params
Optional field names, when supplied. Collect these only when needed.
credential_help
Optional translated instructions keyed by credential name; guidance may not cover every field.
multiple_environments_supported
Whether to send environment with sandbox or production.
Fields listed in required_params but absent from optional_params are required. Treat an omitted optional_params as an empty list. Use the returned field names exactly.
Add the selected provider's credential fields as top-level string fields alongside provider, environment and label. For example, the Stripe request below uses stripe_secret_key. Credential names come from discovery, so new providers can be supported without maintaining a separate field list.
Send the fields advertised for the selected provider. Unsupported installation fields return 422 VALIDATION_ERROR.
When multiple_environments_supported is true, omitting environment returns 400 BAD_REQUEST. An invalid value returns 422 VALIDATION_ERROR. When the flag is false, omit the field: the provider is production-only, and sending sandbox does not enable a sandbox environment.
Use the returned merchant_account_id with Get Merchant Account to retrieve account details. If webhook_setup is present, finish the provider setup using its instructions. webhook_recovery, when returned, identifies webhooks removed during provider-capacity recovery; review deleted_foreign for other integrations that may need reconfiguration.
When the credentials already belong to an account in this project, installation returns 422 VALIDATION_ERROR with error.reason: "DUPLICATE_CREDENTIALS". Each error.details entry identifies the existing merchant_account_id and its active state. Use that ID to inspect the existing connection; changing the label does not create a separate connection for the same credentials.
