> ## 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. # Configure the tenant's Pix receiver > Sets the Pix key of the tenant and the address of the receiver, the Pix receiver of the tenant's hybrid boletos (`type: HYBRID` on POST /v1/boletos), which carry a Pix QR code. The whole configuration is replaced: both members are required and there is no partial update. - The key must be a key of the tenant's collection account, in one of the Pix key formats. A key outside them, a CPF or CNPJ key with invalid check digits, a state outside the list or a zip code that is not 8 digits is refused with 400 PBP-0001, naming the member. - A CPF or CNPJ key must be the document of the holder of the collection account, who is the Pix receiver: another document is refused with 422 PBP-0120, naming `pixKey`, and nothing is written. When the holder's document cannot be read, the key is written and the check is left to the issuance of a boleto that carries a Pix QR code. - A random, e-mail or phone key is not looked up in the Pix directory and its ownership is not verified: confirm that it is a key of the tenant's collection account before configuring it. - The address is stored encrypted. It is returned by GET /v1/admin/pix-config and not by this operation. - A tenant with no provider credential is refused with 422 PBP-0017: connect the provider first with POST /v1/admin/providers/connect. - The write records who made it and when (`updatedBy`, `updatedAt`). ## OpenAPI ````yaml /en/openapi/v3-current/payments.yaml post /v1/admin/pix-config 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 as an RFC 9457 problem document on application/problem+json. 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/pix-config: post: tags: - Admin summary: Configure the tenant's Pix receiver description: >- Sets the Pix key of the tenant and the address of the receiver, the Pix receiver of the tenant's hybrid boletos (`type: HYBRID` on POST /v1/boletos), which carry a Pix QR code. The whole configuration is replaced: both members are required and there is no partial update. - The key must be a key of the tenant's collection account, in one of the Pix key formats. A key outside them, a CPF or CNPJ key with invalid check digits, a state outside the list or a zip code that is not 8 digits is refused with 400 PBP-0001, naming the member. - A CPF or CNPJ key must be the document of the holder of the collection account, who is the Pix receiver: another document is refused with 422 PBP-0120, naming `pixKey`, and nothing is written. When the holder's document cannot be read, the key is written and the check is left to the issuance of a boleto that carries a Pix QR code. - A random, e-mail or phone key is not looked up in the Pix directory and its ownership is not verified: confirm that it is a key of the tenant's collection account before configuring it. - The address is stored encrypted. It is returned by GET /v1/admin/pix-config and not by this operation. - A tenant with no provider credential is refused with 422 PBP-0017: connect the provider first with POST /v1/admin/providers/connect. - The write records who made it and when (`updatedBy`, `updatedAt`). operationId: configureAdminPixConfig parameters: - description: >- Tenant organization ID. Optional. The organization context is determined by the credentials you authenticate with; this header does not select or change it. in: header name: X-Organization-Id schema: description: >- Tenant organization ID. Optional. The organization context is determined by the credentials you authenticate with; this header does not select or change it. type: string - description: >- Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012. in: header name: Idempotency-Key required: true schema: description: >- Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012. type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ConfigurePixConfigRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ConfiguredPixConfigResponse' description: OK '400': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Bad Request '401': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again. '403': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+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. '409': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Conflict. While an earlier request under the same `Idempotency-Key` is still being processed, a request under that key is answered PBP-0007 and is not run. Send it again under the SAME key after a short wait: the key answers this code for at most five minutes after the earlier request arrived. Afterwards the same key answers with the earlier request's stored answer, with 500 PBP-0002 when that answer cannot be replayed, or, when no answer was kept, by running the request. Do not send it under a new key to get past this answer: the earlier request may still take effect. '413': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Request Entity Too Large '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error '503': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send the same request again with the same Idempotency-Key. security: - BearerAuth: [] components: schemas: ConfigurePixConfigRequest: additionalProperties: false properties: pixKey: description: >- Pix key of the tenant's collection account, the receiver of the Pix payment of the tenant's boletos that carry a Pix QR code. Accepted formats: random key (lowercase UUID), CPF (11 digits), CNPJ (14 digits), e-mail (lowercase, at most 77 characters) and phone (+, country code and number). A CPF or CNPJ key with invalid check digits is refused with 400 PBP-0001, and so is a CNPJ key in the alphanumeric format. A CPF or CNPJ key must be the document of the holder of the collection account, who is the Pix receiver: another document is refused with 422 PBP-0120, and nothing is written. When the holder's document cannot be read, the key is written and the check is left to the issuance of a boleto that carries a Pix QR code. A random, e-mail or phone key is not verified. examples: - f34f8ec2-a4b7-41b4-8200-b53a07e00bac maxLength: 77 pattern: >- ^([0-9]{11}|[0-9]{14}|[+][1-9][0-9][0-9]{1,14}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|[a-z0-9.!#$&'*+/=?^_`{|}~-]+@[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:[.][a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*)$ patternDescription: >- a Pix key: a random key (lowercase UUID), a CPF (11 digits), a CNPJ (14 digits), a lowercase e-mail or a phone (+, country code and number) type: string receiverAddress: $ref: '#/components/schemas/PixReceiverAddressRequest' description: >- Address of the holder of the account the key belongs to, the receiver of the Pix payment. A boleto that carries a Pix QR code requires it, and the account record does not provide it. required: - pixKey - receiverAddress type: object ConfiguredPixConfigResponse: additionalProperties: false properties: complete: description: >- Whether the configuration has every member a boleto that carries a Pix QR code needs from it; always true after a write, which requires them all. As on the read, it does not guarantee that an issuance is accepted. type: boolean pixKey: description: The configured Pix key. examples: - f34f8ec2-a4b7-41b4-8200-b53a07e00bac type: string updatedAt: description: When this write was recorded, in UTC. examples: - '2026-10-13T15:04:05Z' format: date-time type: string updatedBy: description: >- Identifier of the authenticated principal that made this write: the subject of its access token. type: string required: - pixKey - complete - updatedAt - updatedBy 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 PixReceiverAddressRequest: additionalProperties: false properties: city: description: City. examples: - SAO PAULO minLength: 1 type: string state: description: State code (UF), two upper-case letters. enum: - AC - AL - AM - AP - BA - CE - DF - ES - GO - MA - MG - MS - MT - PA - PB - PE - PI - PR - RJ - RN - RO - RR - RS - SC - SE - SP - TO examples: - SP type: string street: description: Street and number, on one line. examples: - Avenida Paulista 1000 minLength: 1 type: string zipCode: description: >- CEP with 8 digits and no hyphen: 01310-100 is refused with 400 PBP-0001. examples: - '01310100' pattern: ^[0-9]{8}$ patternDescription: a CEP of 8 digits, without hyphen type: string required: - street - city - state - zipCode 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.