> ## 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. # Issue installment boletos > Creates a series of 2 to 36 independent boletos, one per installment, with totalAmount split evenly, the remainder going to the last installment, or with the amounts given in installmentAmounts. Installment k falls due on firstDueDate plus (k-1) times intervalDays days, with intervalDays from 1 to 365 and no business-day adjustment. The answer is immediate and nothing is issued in it: the series and its installments are recorded PENDING, and each installment is registered with the banking provider afterwards, one at a time. This answer always carries status CREATED and closed false; follow the series at GET /v1/boletos/installments/{series_id} and each installment at GET /v1/boletos/{id}. The organization comes from the X-Organization-Id header and the ledger from ledgerId, with the same refusals as POST /v1/boletos, and every installment is written with that pair. The account in midazAccountId must belong to that organization and ledger, and it is checked once per series. Nothing is recorded when a request is refused, and the refusals come in this order: 401 PBP-0003 and 403 PBP-0004 for authentication and authorization; the Idempotency-Key, 400 PBP-0012 when it is missing or malformed, 409 PBP-0007 while the original request is still running, and 422 PBP-0013 when the same key arrives with another body or under another organization; 400 PBP-0001 for a body that fails schema validation, including one that sends guarantor, which this operation does not accept, for installments or intervalDays of zero or less, and for an ourNumbers item that is not a number, named as ourNumbers[] counted from 0; 400 PBP-0025 for the organization, then 400 PBP-0026 for the ledger; 400 PBP-0001 for a date or an amount that cannot be read; 422 PBP-0006 for a type a series does not carry, QR_CODE or HYBRID; 422 PBP-0102 for a payer document whose check digit fails or a first due date before today; 422 PBP-0006 for a refused fine, interest or discount; 422 PBP-0102 for intervalDays above 365, installments outside 2 to 36, an installmentAmounts list of another length, or an amount below 0.01 or with more than two decimal places; the numbers, when ourNumbers is present and not null: 422 PBP-0102 for an ourNumbers list that does not hold one number per installment, an empty one included, 422 PBP-0006 when the connected provider does not accept a number chosen by the payee, or 422 PBP-0017 when this instance has no provider to judge them by, 400 PBP-0001 for an ourNumbers item wider than the provider accepts, named as ourNumbers[], and 422 PBP-0102 when two installments carry the same number, with the installments, counted from 1, in duplicateInstallmentNumbers; the account, 404 PBP-0005 when it does not exist or belongs to another organization or ledger, 422 PBP-0106 when account validation is not configured on this instance, and 503 PBP-0301 when the ledger credential is unavailable; the final beneficiary, established once per series, 503 PBP-0118 when the account holder's registration data cannot be read or reading it is not configured, 400 PBP-0116 when it is incomplete, 422 PBP-0117 when the holder cannot be a final beneficiary and 422 PBP-0119 when the payer is the holder; 422 PBP-0102 when installmentAmounts does not add up to totalAmount; only for a series with numbers, the provider account the numbers are reserved in, 422 PBP-0017 when this instance has no account discovery, 422 PBP-0014 when the provider refuses the lookup and 503 PBP-0015 when it does not answer; last, 422 PBP-0108 when a number is already held by an active boleto of this tenant on the same provider account, before the provider is called and with nothing of the series recorded, the problem carrying the installment as installmentNumber and, when the holder can be read, its id as ourNumberHolderBoletoId. A series without numbers never depends on the account discovery. A refusal releases the Idempotency-Key, and so do 503 PBP-0301, 503 PBP-0118 and 503 PBP-0015: a retry under the same key runs the request again. ## OpenAPI ````yaml /pt/openapi/v3-current/payments.yaml post /v1/boletos/installments 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/boletos/installments: post: tags: - Boletos summary: Issue installment boletos description: >- Creates a series of 2 to 36 independent boletos, one per installment, with totalAmount split evenly, the remainder going to the last installment, or with the amounts given in installmentAmounts. Installment k falls due on firstDueDate plus (k-1) times intervalDays days, with intervalDays from 1 to 365 and no business-day adjustment. The answer is immediate and nothing is issued in it: the series and its installments are recorded PENDING, and each installment is registered with the banking provider afterwards, one at a time. This answer always carries status CREATED and closed false; follow the series at GET /v1/boletos/installments/{series_id} and each installment at GET /v1/boletos/{id}. The organization comes from the X-Organization-Id header and the ledger from ledgerId, with the same refusals as POST /v1/boletos, and every installment is written with that pair. The account in midazAccountId must belong to that organization and ledger, and it is checked once per series. Nothing is recorded when a request is refused, and the refusals come in this order: 401 PBP-0003 and 403 PBP-0004 for authentication and authorization; the Idempotency-Key, 400 PBP-0012 when it is missing or malformed, 409 PBP-0007 while the original request is still running, and 422 PBP-0013 when the same key arrives with another body or under another organization; 400 PBP-0001 for a body that fails schema validation, including one that sends guarantor, which this operation does not accept, for installments or intervalDays of zero or less, and for an ourNumbers item that is not a number, named as ourNumbers[] counted from 0; 400 PBP-0025 for the organization, then 400 PBP-0026 for the ledger; 400 PBP-0001 for a date or an amount that cannot be read; 422 PBP-0006 for a type a series does not carry, QR_CODE or HYBRID; 422 PBP-0102 for a payer document whose check digit fails or a first due date before today; 422 PBP-0006 for a refused fine, interest or discount; 422 PBP-0102 for intervalDays above 365, installments outside 2 to 36, an installmentAmounts list of another length, or an amount below 0.01 or with more than two decimal places; the numbers, when ourNumbers is present and not null: 422 PBP-0102 for an ourNumbers list that does not hold one number per installment, an empty one included, 422 PBP-0006 when the connected provider does not accept a number chosen by the payee, or 422 PBP-0017 when this instance has no provider to judge them by, 400 PBP-0001 for an ourNumbers item wider than the provider accepts, named as ourNumbers[], and 422 PBP-0102 when two installments carry the same number, with the installments, counted from 1, in duplicateInstallmentNumbers; the account, 404 PBP-0005 when it does not exist or belongs to another organization or ledger, 422 PBP-0106 when account validation is not configured on this instance, and 503 PBP-0301 when the ledger credential is unavailable; the final beneficiary, established once per series, 503 PBP-0118 when the account holder's registration data cannot be read or reading it is not configured, 400 PBP-0116 when it is incomplete, 422 PBP-0117 when the holder cannot be a final beneficiary and 422 PBP-0119 when the payer is the holder; 422 PBP-0102 when installmentAmounts does not add up to totalAmount; only for a series with numbers, the provider account the numbers are reserved in, 422 PBP-0017 when this instance has no account discovery, 422 PBP-0014 when the provider refuses the lookup and 503 PBP-0015 when it does not answer; last, 422 PBP-0108 when a number is already held by an active boleto of this tenant on the same provider account, before the provider is called and with nothing of the series recorded, the problem carrying the installment as installmentNumber and, when the holder can be read, its id as ourNumberHolderBoletoId. A series without numbers never depends on the account discovery. A refusal releases the Idempotency-Key, and so do 503 PBP-0301, 503 PBP-0118 and 503 PBP-0015: a retry under the same key runs the request again. operationId: createBoletoInstallments parameters: - description: >- Midaz organization the account and every installment live under. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. in: header name: X-Organization-Id schema: description: >- Midaz organization the account and every installment live under. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. 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/CreateInstallmentsRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/CreateInstallmentsResponse' description: Created '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. '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Not Found '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-0301 means the ledger credential needed to check the account could not be resolved, or the ledger refused it. PBP-0118 means the account holder's registration data, which establishes the final beneficiary, could not be read, or reading it is not configured on this instance. PBP-0015 means the provider did not answer the discovery of the account a series' ourNumbers are reserved in; a series without numbers never receives it. Nothing was recorded, and all three release the Idempotency-Key: wait and send the same request again with the same key. 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: CreateInstallmentsRequest: additionalProperties: false properties: discount: $ref: '#/components/schemas/DiscountRequest' fine: $ref: '#/components/schemas/FineRequest' firstDueDate: description: Due date of the first installment, YYYY-MM-DD. examples: - '2030-01-15' format: date type: string installmentAmounts: description: >- Per-installment amounts, at most 36. When supplied, its length must match installments. items: maxLength: 32 type: string maxItems: 36 type: - array - 'null' installments: description: Number of installments. examples: - 2 format: int64 type: integer interest: $ref: '#/components/schemas/InterestRequest' intervalDays: description: Days between consecutive installments. examples: - 30 format: int64 type: integer ledgerId: description: >- Midaz ledger the account lives in and every installment is written with. Required: absent, blank or not a canonical UUID is refused with 400 PBP-0026. type: string midazAccountId: description: Midaz account the series settles into. type: string ourNumbers: description: >- Bank-side identification (nosso numero) chosen by the payee for each installment: one number per installment, in installment order, at most 36. All or none: when absent or null, the provider assigns every number, and an empty list is refused with 422 PBP-0102, as is a list of another length. Each item follows the rule of ourNumber on POST /v1/boletos: surrounding spaces are removed, a hyphen is accepted only when followed by exactly one digit, which is discarded, and any other character that is not a digit is refused; the accepted width is set by the connected provider (11 significant digits for the current one). A format or width refusal answers 400 PBP-0001 naming the item as ourNumbers[], counted from 0. Two installments with the same number, leading zeros ignored, are refused with 422 PBP-0102, and the problem carries the installments, counted from 1, as duplicateInstallmentNumbers. A number already held by an active boleto of this tenant on the same provider account refuses the whole series with 422 PBP-0108 before the provider is called, and the problem carries the installment as installmentNumber and, when the holder can be read, its id as ourNumberHolderBoletoId. Only a series with numbers depends on the provider account discovery: 422 PBP-0017 when this instance has none, 422 PBP-0014 when the provider refuses it and 503 PBP-0015 when the provider does not answer. items: type: string maxItems: 36 type: - array - 'null' payer: $ref: '#/components/schemas/PayerRequest' totalAmount: description: >- Series total as a decimal string. Optional: either this or installmentAmounts must be supplied. examples: - '100.00' maxLength: 32 type: string type: description: Boleto type applied to every installment. examples: - TRADITIONAL type: string required: - type - payer - installments - firstDueDate - intervalDays - midazAccountId type: object CreateInstallmentsResponse: additionalProperties: false properties: boletos: items: $ref: '#/components/schemas/InstallmentBoletoResponse' type: - array - 'null' closed: description: >- Whether no installment of the series can still be paid: true when every installment is SETTLED, CANCELED, INACTIVATED or FAILED. Always present. It can return to false when the provider reverts the cancellation of an installment. type: boolean installmentsCount: format: int64 type: integer ledgerId: description: Midaz ledger the installments were written with. Always present. type: string organizationId: description: >- Midaz organization the installments were written with. Always present, and always the organization of the X-Organization-Id header. type: string seriesId: type: string status: description: >- Emission outcome of the series, derived from its installments on every read. CREATED: some installment has no emission outcome yet. COMPLETED: every installment has an outcome and none is FAILED. PARTIAL_FAILURE: every installment has an outcome and some, not all, are FAILED; those carry errorMessage. FAILED: every installment is FAILED. It does not depend on payment, cancellation or write-off, and it can move from COMPLETED to PARTIAL_FAILURE or FAILED when the provider later refuses an accepted installment: a client waiting for the final outcome reads closed. enum: - CREATED - COMPLETED - PARTIAL_FAILURE - FAILED type: string totalAmount: type: string required: - seriesId - organizationId - ledgerId - status - closed - totalAmount - installmentsCount - boletos 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 DiscountRequest: additionalProperties: false properties: amount: description: >- Discount amount as a decimal string, greater than zero. For FIXED it is in BRL with at most 2 decimal places; for PERCENTAGE it is in percent (2.5 means 2.5%) with at most 6 decimal places. On a HYBRID boleto a PERCENTAGE amount accepts at most 2 decimal places, counted as written (2.500 carries three); more is refused with 422 PBP-0006 naming discount.amount. maxLength: 32 type: string limitDate: description: >- Last date the discount applies, YYYY-MM-DD. It must be on or after the day of issuance (Brazilian calendar) and before the due date: before dueDate on a single boleto, before firstDueDate on installments. A date outside that window is refused with 422 PBP-0006. examples: - '2029-12-31' format: date type: string type: description: >- Discount type, granted when the boleto is paid on or before limitDate. One of FIXED (amount in BRL, at most 2 decimal places) or PERCENTAGE (percent of the boleto's face value, at most 6 decimal places, 2 on a HYBRID boleto). Required when a discount is sent: an absent, empty or unlisted value is refused with 422 PBP-0006. A discount also requires amount and limitDate. type: string required: - amount - limitDate type: object FineRequest: additionalProperties: false properties: amount: description: >- Fine amount as a decimal string, greater than zero. For FIXED it is in BRL with at most 2 decimal places; for PERCENTAGE it is in percent (2.5 means 2.5%) with at most 6 decimal places. On a HYBRID boleto a PERCENTAGE amount accepts at most 2 decimal places, counted as written (2.500 carries three); more is refused with 422 PBP-0006 naming fine.amount. maxLength: 32 type: string type: description: >- Fine type, charged once when the boleto is paid after its due date. One of FIXED (amount in BRL, at most 2 decimal places) or PERCENTAGE (percent of the boleto's face value, at most 6 decimal places, 2 on a HYBRID boleto). Required when a fine is sent: an absent, empty or unlisted value is refused with 422 PBP-0006. type: string required: - amount type: object InterestRequest: additionalProperties: false properties: amount: description: >- Interest amount as a decimal string, greater than zero. For DAILY_FIXED it is in BRL per calendar day with at most 2 decimal places; for DAILY_PERCENTAGE and MONTHLY_PERCENTAGE it is in percent (1 means 1%) with at most 6 decimal places. On a HYBRID boleto a DAILY_PERCENTAGE or MONTHLY_PERCENTAGE amount accepts at most 2 decimal places, counted as written (1.500 carries three); more is refused with 422 PBP-0006 naming interest.amount. maxLength: 32 type: string type: description: >- Interest type, accrued for each calendar day the boleto is paid late. One of DAILY_FIXED (amount in BRL per calendar day late, at most 2 decimal places), DAILY_PERCENTAGE (percent of the boleto's face value per calendar day late, at most 6 decimal places, 2 on a HYBRID boleto) or MONTHLY_PERCENTAGE (percent of the boleto's face value per month, accrued per calendar day over a 30-day month, at most 6 decimal places, 2 on a HYBRID boleto). Required when interest is sent: an absent, empty or unlisted value is refused with 422 PBP-0006. type: string required: - amount type: object PayerRequest: additionalProperties: false properties: address: $ref: '#/components/schemas/AddressRequest' document: description: Payer CPF or CNPJ, digits only. type: string name: description: Payer full name. type: string required: - document - name type: object InstallmentBoletoResponse: additionalProperties: false properties: amount: type: string dueDate: type: string errorMessage: type: string id: type: string installmentLabel: type: string installmentNumber: format: int64 type: integer 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 status: enum: - PENDING - CREATED - SETTLED - CANCELED - INACTIVATED - FAILED type: string required: - id - installmentNumber - installmentLabel - amount - dueDate - status 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 AddressRequest: 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.