> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Connect provider with the tenant's client credentials > Connects the tenant to the banking provider. It checks that the provider client credentials configured for the tenant can obtain an access token, stores that token, and resolves the provider company_id from the organization named in X-Organization-Id. On a deployment that verifies provider accounts, it also verifies that the credentials resolve to exactly one usable provider account, and account_verified in the answer says whether the account was verified. The tenant's provider client credentials must be configured before this call. X-Organization-Id is required. It names the Midaz organization whose legalDocument (CNPJ) becomes the provider company_id; that organization owns the tenant's provider account. A request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025 and nothing is sent to the provider. Connecting again with a different organization replaces the company_id: the last successful connect wins. Send an empty JSON object as the body: {}. The body is required: a request with no body, or with null, is refused with 400, and any field in it is rejected. Account verification failures: 422 means the account setup at the provider must be corrected — there is no default account, there is more than one, or the default account is locked or not active. 502 means the provider returned an invalid answer, or the account does not belong to the credentials that would pay for it. account_verified reports whether the provider account was verified. When it is true, provider_account_id identifies the verified account. When it is false, the connection is established but the account was NOT verified on this deployment and provider_account_id is absent: a successful connection is not evidence that the credentials resolve to the correct account. Do not treat the account as validated; contact support to have verification enabled. MULTI-TENANT DEPLOYMENTS ONLY: the answer also carries webhook_url and webhook_signing_key. webhook_url is this tenant's inbound address for provider deliveries, and the token it contains identifies the tenant. webhook_signing_key is the key the provider uses to compute the HMAC-SHA256 of each delivery body, sent in the x-webhook-baas-signature header. It is a signing key, not a bearer token: never place it in an Authorization header. The two are registered together at the provider; webhook_subscription_registered reports whether this call registered them. Both fields are absent in single-tenant deployments. THE SIGNING KEY IS SHOWN EXACTLY ONCE. No endpoint returns it again, so record it when you read it. Calling connect again ROTATES the connection: it issues a new webhook_url and a new webhook_signing_key, and the previous pair keeps authenticating deliveries for a grace window so that deliveries already in flight are not lost. If the webhook URL or the signing key may have been exposed, call connect again with the same `X-Organization-Id`. A successful call rotates both. The exposed pair keeps working until its grace window closes, 30 minutes by default. After a failed call, the exposed pair stays in use. THIS OPERATION IS NOT IDEMPOTENT. An Idempotency-Key header is ignored and does not replay a previous answer. Retrying a connect whose response you did not receive issues a new connection and replaces the one the provider may already be using, which then authenticates only until its grace window closes. ## OpenAPI ````yaml /pt/openapi/v3-current/payments.yaml post /v1/admin/providers/connect openapi: 3.1.0 info: description: >- API for the Lerian Payments interface via BTG. It covers boleto issuance, cancellation, and queries; bill payments (bankslip, utilities, and DARF) and queries; aggregated boleto and payment dashboards; provider connection and outbound webhook configuration; and the provider webhook receiver for settlement events. ERROR BODIES. A failed request arrives in one of two shapes, and which one you get depends on where the service catches the failure. A failure that the request pipeline catches before the API layer sees it answers a flat JSON body on application/json; the idempotency check is the pipeline rule you meet most often. Authentication and authorization refusals follow the response contract documented by the operation. Everything the API layer catches answers an RFC 9457 problem document on application/problem+json. Read the media type to tell the two apart. Branch on the code member. A license refusal carries an LCS code, listed in the License Manager error list. title: Payments — via BTG API version: 1.0.0 servers: - url: https://api.example.com description: >- Replace the example host with the URL provided during environment onboarding. security: [] tags: - description: >- Tenant-level setup: connecting the banking provider and configuring where status notifications are delivered. name: Admin - description: Issuing, querying and cancelling boletos, and retrieving the rendered PDF. name: Boletos - description: >- Aggregated counts, amounts and breakdowns over a period, for boletos and for payments. name: Dashboards - description: >- Paying bankslips, utility bills and DARF tax slips, and querying those payments. name: Payments - description: >- The webhook the payment provider posts settlement events to. Authenticated with a credential agreed with the provider, not with the platform identity used by the rest of this API. name: Settlement paths: /v1/admin/providers/connect: post: tags: - Admin summary: Connect provider with the tenant's client credentials description: >- Connects the tenant to the banking provider. It checks that the provider client credentials configured for the tenant can obtain an access token, stores that token, and resolves the provider company_id from the organization named in X-Organization-Id. On a deployment that verifies provider accounts, it also verifies that the credentials resolve to exactly one usable provider account, and account_verified in the answer says whether the account was verified. The tenant's provider client credentials must be configured before this call. X-Organization-Id is required. It names the Midaz organization whose legalDocument (CNPJ) becomes the provider company_id; that organization owns the tenant's provider account. A request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025 and nothing is sent to the provider. Connecting again with a different organization replaces the company_id: the last successful connect wins. Send an empty JSON object as the body: {}. The body is required: a request with no body, or with null, is refused with 400, and any field in it is rejected. Account verification failures: 422 means the account setup at the provider must be corrected — there is no default account, there is more than one, or the default account is locked or not active. 502 means the provider returned an invalid answer, or the account does not belong to the credentials that would pay for it. account_verified reports whether the provider account was verified. When it is true, provider_account_id identifies the verified account. When it is false, the connection is established but the account was NOT verified on this deployment and provider_account_id is absent: a successful connection is not evidence that the credentials resolve to the correct account. Do not treat the account as validated; contact support to have verification enabled. MULTI-TENANT DEPLOYMENTS ONLY: the answer also carries webhook_url and webhook_signing_key. webhook_url is this tenant's inbound address for provider deliveries, and the token it contains identifies the tenant. webhook_signing_key is the key the provider uses to compute the HMAC-SHA256 of each delivery body, sent in the x-webhook-baas-signature header. It is a signing key, not a bearer token: never place it in an Authorization header. The two are registered together at the provider; webhook_subscription_registered reports whether this call registered them. Both fields are absent in single-tenant deployments. THE SIGNING KEY IS SHOWN EXACTLY ONCE. No endpoint returns it again, so record it when you read it. Calling connect again ROTATES the connection: it issues a new webhook_url and a new webhook_signing_key, and the previous pair keeps authenticating deliveries for a grace window so that deliveries already in flight are not lost. If the webhook URL or the signing key may have been exposed, call connect again with the same `X-Organization-Id`. A successful call rotates both. The exposed pair keeps working until its grace window closes, 30 minutes by default. After a failed call, the exposed pair stays in use. THIS OPERATION IS NOT IDEMPOTENT. An Idempotency-Key header is ignored and does not replay a previous answer. Retrying a connect whose response you did not receive issues a new connection and replaces the one the provider may already be using, which then authenticates only until its grace window closes. operationId: connectProvider parameters: - description: >- Midaz organization whose legalDocument (CNPJ) is provisioned as the provider company_id. Required: absent, blank or not a canonical UUID is refused with 400 PBP-0025. in: header name: X-Organization-Id schema: description: >- Midaz organization whose legalDocument (CNPJ) is provisioned as the provider company_id. Required: absent, blank or not a canonical UUID is refused with 400 PBP-0025. type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ProviderConnectRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ProviderConnectResponse' description: OK '400': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' application/problem+json: schema: $ref: '#/components/schemas/Detail' text/plain: schema: type: string description: >- Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is either `application/json` with error code `PBP-0003` or `application/problem+json` (RFC 9457); read the `Content-Type` to parse it. The `text/plain` media type listed for this status is not returned. Obtain a valid bearer token and send the request again. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' text/plain: schema: type: string description: >- The authenticated principal is not allowed to perform this request. The error body is `application/json` with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed. The `text/plain` media type listed for this status is not returned. '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Not Found '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error '502': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Bad Gateway '503': description: >- Service Unavailable. PBP-0008 means the tenant's storage could not be resolved. The request was not processed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] components: schemas: ProviderConnectRequest: additionalProperties: false type: object ProviderConnectResponse: additionalProperties: false properties: account_verified: type: boolean company_id: type: string provider_account_id: type: string provider_type: type: string status: type: string webhook_signing_key: type: string webhook_subscription_registered: description: >- Whether the subscription pointing the provider at webhook_url was written at the provider. ABSENT means no per-tenant webhook connection was issued, so there was nothing to register. TRUE means the provider has been told. FALSE means the connect succeeded and the credentials in this body are valid, but the provider was not told where to deliver events, so deliveries to webhook_url may not arrive yet. Depending on the cause, the registration is retried automatically or needs an operator. Do not reconnect: that rotates the signing key you just received. If deliveries do not start, call POST /v1/admin/providers/webhooks/{provider_type}/resubscribe or contact support. type: boolean webhook_url: type: string required: - status - provider_type - account_verified type: object Detail: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object ErrorResponse: additionalProperties: false properties: code: type: string details: additionalProperties: {} type: object message: type: string title: type: string required: - code - title - message type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.