> ## 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. # Adopt the provider title of an installment > Operational action for an installment the emission conference did not adopt: PENDING, without a provider id, and already attempted. That covers an installment whose title the provider proved to exist, one withheld by a lapsed discount before its resend, and one attempted without either, for instance one whose resends the provider keeps refusing. - The service reads the title at the provider by the `providerId` given and compares its `clientRequestId`, derived from the installment, its amount and its due date with the installment's. - All three match: the provider id is recorded on the installment and the acceptance sweep takes it to `CREATED`. The answer is `200` with the boleto, the body of `GET /v1/boletos/{id}`. - Any of them differs, the provider has no title with that id, or the installment is not in that state: `422 PBP-0121`, and nothing is written. The `detail` says which. - Repeating the call with the same `providerId` on the installment it already adopted answers `200`. ## OpenAPI ````yaml /en/openapi/v3-current/payments.yaml post /v1/admin/boletos/{id}/adopt 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/boletos/{id}/adopt: post: tags: - Boletos summary: Adopt the provider title of an installment description: >- Operational action for an installment the emission conference did not adopt: PENDING, without a provider id, and already attempted. That covers an installment whose title the provider proved to exist, one withheld by a lapsed discount before its resend, and one attempted without either, for instance one whose resends the provider keeps refusing. - The service reads the title at the provider by the `providerId` given and compares its `clientRequestId`, derived from the installment, its amount and its due date with the installment's. - All three match: the provider id is recorded on the installment and the acceptance sweep takes it to `CREATED`. The answer is `200` with the boleto, the body of `GET /v1/boletos/{id}`. - Any of them differs, the provider has no title with that id, or the installment is not in that state: `422 PBP-0121`, and nothing is written. The `detail` says which. - Repeating the call with the same `providerId` on the installment it already adopted answers `200`. operationId: adoptBoletoEmission parameters: - 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 - description: Identifier of the installment's boleto (UUID). in: path name: id required: true schema: description: Identifier of the installment's boleto (UUID). examples: - 01928f6e-7a1b-7c3d-9e4f-5a6b7c8d9e0f format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/AdoptBoletoEmissionRequestBody' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/GetBoletoResponse' description: OK '400': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Bad Request. PBP-0001: the `id` is not a UUID, or `providerId` is absent or blank. '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. '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: 'Not Found. PBP-0005: the boleto does not exist in the tenant.' '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. PBP-0121 (EMISSION_ADOPTION_REFUSED): the installment is not PENDING, without a provider id and already attempted, or the title read does not match (clientRequestId, amount or due date), or the provider has no title with that id. The `detail` says which. Nothing was written. '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-0015: the provider did not answer the title read. Nothing was written. 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: AdoptBoletoEmissionRequestBody: additionalProperties: false properties: providerId: description: The provider's id of the title. examples: - 8c2f0b5e-1d3a-4c7e-9f6b-2a4d5e6f7a8b maxLength: 64 type: string required: - providerId type: object GetBoletoResponse: additionalProperties: false properties: amount: type: string barcode: type: string batchId: description: >- Batch the boleto was created in, as one of its items. Present only on a boleto of kind BATCH, absent on every other kind. examples: - 0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b format: uuid type: string batchPosition: description: >- Position of the boleto in its batch, zero-based: the position of its item in the batch request. Present only on a boleto of kind BATCH, absent on every other kind. examples: - 3 format: int64 maximum: 24 minimum: 0 type: integer cancelable: description: >- Whether cancelling this boleto would effect a cancellation at the provider. Always present. Derived from the boleto's state, not from any request field: true only for a CREATED boleto that carries a providerId. An already-canceled boleto reads false even though POST /v1/boletos/{id}/cancel answers it 200 as an idempotent replay. type: boolean canceledAt: type: string cancellationReason: type: string createdAt: type: string digitableLine: type: string discount: $ref: '#/components/schemas/DiscountResponse' dueDate: type: string errorMessage: type: string excessPayments: description: >- Payments a SETTLED hybrid boleto received after it was settled, by the leg that did not settle it, when the provider attaches them to the boleto. A payment by that leg that the provider does not attach to the boleto reaches the collection account without being listed here. They are never credited: the boleto stays settled by the leg in paidVia. At most one is recorded per leg: a later payment by a leg already listed is not added. Only a hybrid boleto carries them, and the member is absent when there is none. items: $ref: '#/components/schemas/ExcessPaymentResponse' maxItems: 10 type: array failedAt: type: string fine: $ref: '#/components/schemas/FineResponse' guarantor: $ref: '#/components/schemas/GuarantorResponse' description: >- Final beneficiary (sacador avalista) of the boleto: the holder of the issuing account, read from that account's registration data at issuance. It is a snapshot: a later change to the registration does not change it. Absent on boletos issued before the final beneficiary was derived. id: type: string inactivatedAt: type: string installmentLabel: type: string instructions: type: string interest: $ref: '#/components/schemas/InterestResponse' kind: description: >- Issuance form of the boleto: SINGLE for a standalone boleto, INSTALLMENT for an installment of a series, BATCH for an item of a batch, which carries batchId and batchPosition. type: string ledgerId: description: Midaz ledger the boleto was written with. Always present. type: string midazAccountId: description: >- Midaz account the boleto was issued for: the midazAccountId it was created with. The settlement credit of a settled boleto is posted to this account. Always present. type: string midazOperationId: type: string organizationId: description: >- Midaz organization the boleto was written with. Always present, and always the organization of the X-Organization-Id header. type: string ourNumber: description: >- Bank-side identification of the boleto (nosso numero), as assigned by the provider and printed on the instrument. Read from the barcode and returned in the instrument's form, with leading zeros: the width is set by the connected provider (11 digits for the current one). When the payee supplied ourNumber on issuance, this field still reports the instrument and not the value supplied: if the two differ, the value here is the one printed on the boleto, and the divergence is recorded by the service. Optional: absent for boletos issued before this field existed, and absent while the provider has not produced a valid barcode. Absence means not yet known; the periodic reconciliation fills it in once the provider produces the instrument, with no action needed from the client; it is never sent as an empty string. examples: - '00000000029' type: string ourNumberDigit: description: >- Check digit of ourNumber, computed by the bank and never accepted in a request. Optional: absent whenever the provider did not return it, in which case ourNumber is presented alone, with no trailing hyphen. It is absent in particular when the payee supplied ourNumber: the current provider returns the digit only for numbers it assigned itself. When present, the canonical presentation is {ourNumber}-{ourNumberDigit}. examples: - '3' type: string paidVia: description: >- Leg by which the boleto was paid: BOLETO for a payment of its barcode or digitable line, PIX for a payment of a hybrid boleto's Pix QR code. Present only on a SETTLED boleto, absent on every other status. A traditional boleto is always paid by BOLETO. Set once, when the boleto settles: a later payment by the other leg does not change it and, when the provider attaches it to the boleto, is listed in excessPayments. enum: - BOLETO - PIX type: string payer: $ref: '#/components/schemas/PayerResponse' pixLocation: description: >- Location of the hybrid boleto's dynamic Pix QR code, as issued. For support and diagnostics: to pay, the payer uses qrCode. Only a HYBRID boleto carries it, and it is served together with qrCode, under the same rule: absent while the boleto is PENDING or FAILED, present once it is CREATED and on every later status; absent on every other type. examples: - pix.example.com/qr/v2/cobv/5d9a8e91c88c43db942d01a0ad92ffc3 type: string pixTxId: description: >- Identifier of the due-date Pix charge attached to a hybrid boleto. Only a HYBRID boleto carries it, and only once its issuance is confirmed; absent on every other type. examples: - 35dabf21d3b941e8a937409b8749f281 type: string providerId: description: >- Identifier the payment provider assigned to this boleto. Quote it when you contact the provider about this boleto. type: string qrCode: description: >- Pix copy-and-paste code of a HYBRID boleto's Pix charge: the payload behind its QR code, which the payer scans or pastes to pay by Pix. Served only after the provider has registered the boleto, so it is never paid into a boleto whose registration fails: absent while the boleto is PENDING or FAILED, and so from the 201 and the 202 of its creation, which answer it PENDING; present on the read once the boleto is CREATED, and on every later status. Absent on a type without a Pix charge. type: string seriesId: type: string settledAmount: type: string settledAt: type: string status: type: string type: type: string updatedAt: type: string required: - id - organizationId - ledgerId - midazAccountId - type - kind - status - cancelable - amount - dueDate - payer - createdAt - updatedAt 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 DiscountResponse: additionalProperties: false properties: amount: type: string limitDate: type: string type: type: string required: - type - amount - limitDate type: object ExcessPaymentResponse: additionalProperties: false properties: amount: description: Amount received, as a decimal string with two decimal places. examples: - '10.00' type: string detectedAt: description: When the service recorded this payment as an excess payment. format: date-time type: string paidAt: description: >- When the payer made this payment, as the payment provider reports it. When the provider reports no instant, it is the moment the service observed the payment. format: date-time type: string paidVia: description: >- Leg this payment arrived by: always the leg that did not settle the boleto. enum: - BOLETO - PIX type: string providerReference: description: >- Reference of this payment at the payment provider: the end-to-end identifier of a Pix payment, or the authorization identifier of a boleto payment. Absent when the provider sent none. type: string required: - paidVia - amount - paidAt - detectedAt type: object FineResponse: additionalProperties: false properties: amount: type: string type: type: string required: - type - amount type: object GuarantorResponse: additionalProperties: false properties: address: $ref: '#/components/schemas/AddressResponse' description: >- Never filled for the final beneficiary: the issuing account's registration data carries no address for it. Kept so the shape of this component does not change. document: description: >- CPF or CNPJ of the final beneficiary, the issuing account's holder, as registered. Answered whole, never masked, wherever this component appears. type: string name: description: >- Name of the final beneficiary, the issuing account's holder, as registered and in full. The printed boleto may abbreviate it; this member never does. type: string required: - name - document type: object InterestResponse: additionalProperties: false properties: amount: type: string type: type: string required: - type - amount type: object PayerResponse: additionalProperties: false properties: address: $ref: '#/components/schemas/AddressResponse' document: type: string name: type: string required: - name - document 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 AddressResponse: additionalProperties: false properties: city: type: string complement: type: string neighborhood: type: string number: type: string state: type: string street: type: string zipCode: 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.