components: schemas: 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 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 BoletoDashboardResponse: additionalProperties: false properties: byStatus: additionalProperties: $ref: "#/components/schemas/BoletoTypeCountAmount" type: object byType: additionalProperties: $ref: "#/components/schemas/BoletoTypeCountAmount" type: object settlementRate: format: double type: number totalAmount: type: string totalCanceled: format: int64 type: integer totalFailed: format: int64 type: integer totalInactivated: format: int64 type: integer totalIssued: format: int64 type: integer totalOverdue: description: "Boletos past their due date and still unpaid: due before today in the Brazilian civil calendar (UTC-3), with status CREATED, or PENDING with a provider identifier (accepted by the provider and awaiting payment). A boleto due today is not overdue. No business-day calendar is applied: a boleto due on a weekend or holiday counts as overdue from the next calendar day, although it stays payable on the next business day. Every filter of the request applies." format: int64 type: integer totalOverdueAmount: description: Sum of the amount of the boletos counted in totalOverdue, as a decimal string with two decimal places. type: string totalPending: format: int64 type: integer totalSettled: format: int64 type: integer totalSettledAmount: type: string required: - totalIssued - totalPending - totalSettled - totalCanceled - totalInactivated - totalFailed - totalOverdue - totalAmount - totalSettledAmount - totalOverdueAmount - settlementRate - byType - byStatus type: object BoletoTypeCountAmount: additionalProperties: false properties: amount: type: string count: format: int64 type: integer required: - count - amount type: object CancelBoletoRequest: additionalProperties: false properties: reason: type: string required: - reason type: object CancelBoletoResponse: additionalProperties: false properties: canceledAt: type: string cancellationReason: type: string id: type: string ledgerId: description: Midaz ledger the boleto was written with. Always present. type: string organizationId: description: Midaz organization the boleto was written with. Always present. type: string providerId: type: string status: type: string required: - id - providerId - organizationId - ledgerId - status - canceledAt - cancellationReason type: object CancelPaymentRequest: additionalProperties: false properties: reason: type: string required: - reason type: object ConfigureWebhookRequest: additionalProperties: false properties: active: type: boolean callbackUrl: type: string enabledEvents: items: type: string type: - array - "null" secret: type: string required: - callbackUrl - secret - enabledEvents type: object ConsultBillBeneficiaryResponse: additionalProperties: false properties: document: description: Beneficiary document, masked. type: string name: description: Beneficiary name. type: string personType: description: PF for a person, PJ for a company, null for anything else the source reported, including nothing. enum: - PF - PJ - null type: - string - "null" required: - name - document - personType type: - object - "null" ConsultBillPaymentWindowResponse: additionalProperties: false properties: end: description: Closing time of the window. type: string start: description: Opening time of the window. type: string required: - start - end type: - object - "null" ConsultBillReceiverBankResponse: additionalProperties: false properties: code: description: Bank code, three digits. type: string ispb: description: Bank ISPB. type: string name: description: Bank name. type: string required: - name - ispb - code type: - object - "null" ConsultBillRequest: additionalProperties: false properties: digitableLine: description: "Digitable line, digits only: 47 for a bank slip, or 48 starting with 8 for a utilities bill." maxLength: 48 minLength: 47 pattern: ^(?:[0-79][0-9]{46}|8[0-9]{47})$ type: string required: - digitableLine type: object ConsultBillResponse: additionalProperties: false properties: amount: description: Consulted amount, two decimal places. type: string assignor: description: Utility company. Utilities only. type: - string - "null" beneficiary: $ref: "#/components/schemas/ConsultBillBeneficiaryResponse" description: Who receives the money, with the document masked. discount: description: Discount granted. Bank slip only. type: - string - "null" dueDate: description: Due date. Bank slip only. format: date type: - string - "null" fine: description: Fine charged. Bank slip only. type: - string - "null" interest: description: Interest charged. Bank slip only. type: - string - "null" limitDate: description: Last date the slip is payable. Bank slip only. format: date type: - string - "null" maxAmount: description: Highest payable amount, when the source reports a band. type: - string - "null" minAmount: description: Lowest payable amount, when the source reports a band. type: - string - "null" originalAmount: description: Face value of the slip. Bank slip only. type: - string - "null" payable: description: Whether the source accepts the bill for payment, as it reported. Bank slip only. type: - boolean - "null" paymentWindow: $ref: "#/components/schemas/ConsultBillPaymentWindowResponse" description: Time of day the bill can be paid. Utilities only. receiverBank: $ref: "#/components/schemas/ConsultBillReceiverBankResponse" description: Bank that receives the payment. Bank slip only. segment: description: FEBRABAN segment the line was consulted on. type: string settlementDate: description: Settlement date the source reported. Utilities only; it is not a due date. format: date type: - string - "null" state: description: Federative unit of the utility. Utilities only. type: - string - "null" utilitySegment: description: The source's own segment text. Utilities only. type: - string - "null" required: - segment - payable - amount - originalAmount - minAmount - maxAmount - fine - interest - discount - dueDate - limitDate - beneficiary - receiverBank - assignor - utilitySegment - state - paymentWindow - settlementDate type: object CreateBoletoRequest: additionalProperties: false properties: amount: description: Amount as a decimal string, at most two decimal places. examples: - "100.00" maxLength: 32 type: string discount: $ref: "#/components/schemas/DiscountRequest" dueDate: description: Due date, YYYY-MM-DD. examples: - "2030-01-15" format: date type: string fine: $ref: "#/components/schemas/FineRequest" instructions: type: string interest: $ref: "#/components/schemas/InterestRequest" ledgerId: description: "Midaz ledger the account lives in and the entry is posted to. Required: absent, blank or not a canonical UUID is refused with 400 PBP-0026." type: string midazAccountId: description: Midaz account the boleto settles into. type: string ourNumber: description: "Bank-side identification of the boleto (nosso numero), chosen by the payee. Optional: when absent, the provider assigns the number. Surrounding spaces are removed. A hyphen is accepted only when followed by exactly one digit, which is discarded because the check digit is always computed by the bank: 152-3 is sent as 152, while 152- and 152-abc are refused. Any other character that is not a digit is refused. Leading zeros do not make a different number: 152 and 00000000152 are the same number for the current provider, and two active boletos of the same provider account cannot hold it at the same time, whatever their amount or due date. The accepted width is set by the connected provider (11 significant digits for the current one). Format and width refusals answer 400 PBP-0001; a provider that does not accept a number chosen by the payee refuses the field with 422 PBP-0006. A number already held by an active boleto of the same provider account is refused with 422 PBP-0108 before the provider is called. When the holder can be read, the PBP-0108 detail names the boleto that holds the number, and the problem carries its id as ourNumberHolderBoletoId; when it is an earlier emission that has no answer from the provider yet, the detail says so instead of asking for another number; otherwise it asks for that boleto to be consulted before another number is informed, because it may be an earlier emission of the same charge. After a 422 PBP-0014, or a 5xx, answered to an emission with ourNumber, the number can stay held until the periodic reconciliation resolves that emission, which it does not do before a grace period set by the deployment (30 minutes by default); meanwhile that emission can still become a live boleto, and issuing the same charge again with another number can leave two boletos for it." examples: - "00000000152" type: string payer: $ref: "#/components/schemas/PayerRequest" type: description: Boleto type. The supported value is TRADITIONAL. HYBRID and QR_CODE are refused with 422 PBP-0006. examples: - TRADITIONAL type: string required: - type - payer - amount - dueDate - midazAccountId type: object CreateBoletoResponse: additionalProperties: false properties: amount: type: string barcode: type: string createdAt: type: string digitableLine: type: string discount: $ref: "#/components/schemas/DiscountResponse" dueDate: type: string fine: $ref: "#/components/schemas/FineResponse" id: type: string instructions: type: string interest: $ref: "#/components/schemas/InterestResponse" ledgerId: description: Midaz ledger the boleto was written with. Always present. type: string organizationId: description: Midaz organization the boleto was written with. Always present. 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 providerId: type: string qrCode: type: string status: type: string type: type: string required: - id - providerId - organizationId - ledgerId - status - type - amount - dueDate - createdAt type: object 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 midazAccountId: description: Midaz account the series settles into. type: string 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" installmentsCount: format: int64 type: integer seriesId: type: string status: type: string totalAmount: type: string required: - seriesId - status - totalAmount - installmentsCount - boletos type: object DARFResponse: additionalProperties: false properties: fineAmount: type: string interestAmount: type: string mainAmount: type: string name: type: string personType: type: string referenceDate: type: string taxId: type: string treasuryRevenueCode: type: string type: type: string required: - personType - taxId - name - referenceDate - treasuryRevenueCode - type - mainAmount - interestAmount - fineAmount 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. maxLength: 32 type: string limitDate: description: Last date the discount applies, YYYY-MM-DD. examples: - "2029-12-31" format: date type: string type: description: "Discount type. Optional: may be omitted, and an empty value is accepted. When a discount is sent, amount and limitDate are required." type: string required: - amount - limitDate type: object DiscountResponse: additionalProperties: false properties: amount: type: string limitDate: type: string type: type: string required: - type - amount - limitDate 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 ErrorResponse: additionalProperties: false properties: code: type: string details: additionalProperties: {} type: object message: type: string title: type: string required: - code - title - message type: object FineRequest: additionalProperties: false properties: amount: description: Fine amount as a decimal string. maxLength: 32 type: string type: description: "Fine type. Optional: may be omitted, and an empty value is accepted. When a fine is sent, amount is required." type: string required: - amount type: object FineResponse: additionalProperties: false properties: amount: type: string type: type: string required: - type - amount type: object GetBoletoResponse: additionalProperties: false properties: amount: type: string barcode: type: string 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 failedAt: type: string fine: $ref: "#/components/schemas/FineResponse" guarantor: $ref: "#/components/schemas/GuarantorResponse" id: type: string inactivatedAt: type: string installmentLabel: type: string instructions: type: string interest: $ref: "#/components/schemas/InterestResponse" kind: 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 payer: $ref: "#/components/schemas/PayerResponse" providerId: description: Identifier the payment provider assigned to this boleto. Quote it when you contact the provider about this boleto. type: string qrCode: 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 GetInstallmentsResponse: additionalProperties: false properties: boletos: items: $ref: "#/components/schemas/InstallmentBoletoResponse" type: - array - "null" installmentsCount: format: int64 type: integer seriesId: type: string status: type: string totalAmount: type: string required: - seriesId - status - totalAmount - installmentsCount - boletos type: object GetPaymentResponse: additionalProperties: false properties: amount: type: string canceledAt: type: string cancellationReason: type: string createdAt: type: string darf: $ref: "#/components/schemas/DARFResponse" description: type: string digitableLine: type: string dueDate: description: "Due date, YYYY-MM-DD. A DARF payment carries the one its creation request named, if any. A BANKSLIP payment carries the slip's due date as the payment provider's pre-payment consult reported it: absent when the consult reported none, and on bank-slip payments created before the due date was recorded. UTILITIES payments do not carry it." type: string errorMessage: type: string failedAt: type: string failureCode: description: "The product error code a FAILED payment was recorded with, when its failure has one. PBP-0211: the payment provider provably never received the payment, nothing was paid, and its reservation is cancelled. PBP-0014: the payment provider refused what it was sent. Absent on every other status, and on a failure recorded without a code. Treat the list as open." examples: - PBP-0211 type: string id: type: string ledgerId: description: Midaz ledger the payment was written with. Always present. type: string midazAccountId: description: "Midaz account the payment is debited from: the midazAccountId the payment was created with. Always present." type: string midazOperationId: type: string organizationId: description: Midaz organization the payment was written with. Always present, and always the organization of the X-Organization-Id header. type: string payee: $ref: "#/components/schemas/PayeeResponse" providerId: description: Identifier the payment provider assigned to this payment. Quote it, together with providerRequestId, when you contact the provider about this payment. Absent while the payment is UNCONFIRMED, and on a payment that failed before the provider acknowledged it. type: string providerRequestId: description: "Reference this API sends to the payment provider when it instructs this payment, exactly as sent. Which of providerId and providerRequestId the provider accepts for a lookup depends on the provider and on the payment type, so quote both when you contact the provider. It is recorded when the payment is created, before the instruction, so it is present on a payment the provider never received too: one FAILED with failureCode PBP-0211, or FAILED without a code after the ledger refused its funds. The provider holds no payment under it then, and a payment retried under the same Idempotency-Key after a refusal for funds carries the same reference as the refused attempt. Absent when the payment carries no such reference." type: string rejectedAt: type: string rejectionReason: type: string settledAmount: type: string settledAt: type: string status: description: "The payment's current status: UNCONFIRMED, CREATED, SCHEDULED, PENDING_APPROVAL, APPROVED, EXECUTED, SETTLED, REJECTED, FAILED or CANCELED. UNCONFIRMED means the outcome at the payment provider is not known yet: every payment starts there, and one whose initiation was answered 202 stays there until it resolves. Treat the list as open: a value added later must not break a client." type: string type: type: string updatedAt: type: string required: - id - organizationId - ledgerId - midazAccountId - type - status - amount - createdAt - updatedAt type: object GuarantorResponse: additionalProperties: false properties: address: $ref: "#/components/schemas/AddressResponse" document: type: string name: type: string required: - name - document type: object InitiateDARFPaymentRequest: additionalProperties: false properties: description: description: Optional free-text description carried on the payment. type: string dueDate: description: Optional due date, YYYY-MM-DD. examples: - "2026-05-10" format: date type: string fineAmount: description: Fine amount as a decimal string, up to two decimal places. Must be non-negative. examples: - "5.00" maxLength: 32 type: string history: description: Optional free-text history carried on the payment. type: string interestAmount: description: Interest amount as a decimal string, up to two decimal places. Must be non-negative. examples: - "10.00" maxLength: 32 type: string ledgerId: description: "Midaz ledger the account lives in and the entry is posted to. Required: absent, blank or not a canonical UUID is refused with 400 PBP-0026." type: string mainAmount: description: Principal amount as a decimal string, up to two decimal places. Must be positive. examples: - "100.00" maxLength: 32 type: string midazAccountId: description: "Midaz account the payment settles from. The TAXPAYER of the DARF is the registered owner of this account, read from the Midaz CRM — the request does not state one. A holder whose registered name exceeds 80 bytes cannot be paid on this rail: the name is never shortened to fit, and the refusal is 422 PBP-0207." type: string referenceDate: description: Tax period reference date, YYYY-MM-DD. examples: - "2026-04-01" format: date type: string referenceNumber: description: Optional reference number carried to the tax authority. format: int64 type: integer totalIncomeAmount: description: Optional total income amount as a decimal string. maxLength: 32 type: string totalIncomePercent: description: Optional total income percentage as a decimal string. maxLength: 32 type: string treasuryRevenueCode: description: "Federal revenue code (código da receita) of the DARF: the four digits of the code, zero-padded, for example 0086. A value in the provider's prefixed form, such as TRC_0086, is also accepted. At most 20 characters. The code is not checked against the revenue code catalogue by this API; the payment provider refuses an unknown code." examples: - "0086" type: string type: description: "DARF type: S for Simples, N for Normal." examples: - S type: string required: - referenceDate - treasuryRevenueCode - type - mainAmount - interestAmount - fineAmount - midazAccountId type: object InitiateDARFPaymentResponse: additionalProperties: false properties: createdAt: type: string id: type: string ledgerId: description: Midaz ledger the payment was written with. Always present. type: string organizationId: description: Midaz organization the payment was written with. Always present. type: string providerId: description: "Identifier the payment provider assigned to this payment. Quote it, together with providerRequestId, when you contact the provider about this payment. Absent while the payment is UNCONFIRMED (the 202 answer): the provider has acknowledged nothing yet. Read the payment by id later to obtain it." type: string providerRequestId: description: Reference this API sent to the payment provider when it instructed the payment, exactly as sent. Which of providerId and providerRequestId the provider accepts for a lookup depends on the provider and on the payment type, so quote both when you contact the provider. Absent when the payment carries no such reference. type: string status: description: "The payment's status when this answer was produced. CREATED on a 201 for a new payment; UNCONFIRMED on a 202, while the outcome at the payment provider is unknown. A request already on record is answered with the payment's status at that moment, which may be any status a payment takes. A replay of the same Idempotency-Key serves the stored answer, whose status may since have changed: read the payment by id for its current state." type: string totalAmount: type: string type: type: string required: - id - type - status - totalAmount - createdAt - organizationId - ledgerId type: object InitiatePaymentRequest: additionalProperties: false properties: description: description: Free-text description carried on the payment. type: string digitableLine: description: Bankslip or utilities digitable line, digits only. examples: - "00190500954014481606906809350314337370000000100" type: string ledgerId: description: "Midaz ledger the account lives in and the entry is posted to. Required: absent, blank or not a canonical UUID is refused with 400 PBP-0026." type: string midazAccountId: description: Midaz account the payment settles from. Who PAYS is the registered owner of this account, read from the Midaz CRM — the request does not state a payer. type: string required: - digitableLine - midazAccountId type: object InitiatePaymentResponse: additionalProperties: false properties: amount: type: string createdAt: type: string digitableLine: type: string dueDate: type: string id: type: string ledgerId: description: Midaz ledger the payment was written with. Always present. type: string organizationId: description: Midaz organization the payment was written with. Always present. type: string providerId: description: "Identifier the payment provider assigned to this payment. Quote it, together with providerRequestId, when you contact the provider about this payment. Absent while the payment is UNCONFIRMED (the 202 answer): the provider has acknowledged nothing yet. Read the payment by id later to obtain it." type: string providerRequestId: description: Reference this API sent to the payment provider when it instructed the payment, exactly as sent. Which of providerId and providerRequestId the provider accepts for a lookup depends on the provider and on the payment type, so quote both when you contact the provider. Absent when the payment carries no such reference. type: string status: description: "The payment's status when this answer was produced. CREATED on a 201 for a new payment; UNCONFIRMED on a 202, while the outcome at the payment provider is unknown. A request already on record is answered with the payment's status at that moment, which may be any status a payment takes. A replay of the same Idempotency-Key serves the stored answer, whose status may since have changed: read the payment by id for its current state." type: string type: type: string required: - id - type - status - digitableLine - amount - createdAt - organizationId - ledgerId type: object InstallmentBoletoResponse: additionalProperties: false properties: amount: type: string dueDate: type: string id: type: string installmentLabel: type: string installmentNumber: format: int64 type: integer status: type: string required: - id - installmentNumber - installmentLabel - amount - dueDate - status type: object InterestRequest: additionalProperties: false properties: amount: description: Interest amount as a decimal string. maxLength: 32 type: string type: description: "Interest type. Optional: may be omitted, and an empty value is accepted. When interest is sent, amount is required." type: string required: - amount type: object InterestResponse: additionalProperties: false properties: amount: type: string type: type: string required: - type - amount type: object ListBoletosResponse: additionalProperties: false properties: items: items: $ref: "#/components/schemas/GetBoletoResponse" type: - array - "null" limit: format: int64 type: integer page: format: int64 type: integer total: format: int64 type: integer required: - items - page - limit - total type: object ListPaymentsResponse: additionalProperties: false properties: items: items: $ref: "#/components/schemas/GetPaymentResponse" type: - array - "null" limit: format: int64 type: integer page: format: int64 type: integer total: format: int64 type: integer required: - items - page - limit - total type: object PayeeResponse: additionalProperties: false properties: name: type: string taxId: type: string 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 PayerResponse: additionalProperties: false properties: address: $ref: "#/components/schemas/AddressResponse" document: type: string name: type: string required: - name - document type: object PaymentDashboardResponse: additionalProperties: false properties: byStatus: additionalProperties: $ref: "#/components/schemas/PaymentTypeCountAmount" type: object byType: additionalProperties: $ref: "#/components/schemas/PaymentTypeCountAmount" type: object totalAmount: type: string totalApproved: format: int64 type: integer totalCanceled: format: int64 type: integer totalCreated: format: int64 type: integer totalExecuted: format: int64 type: integer totalFailed: format: int64 type: integer totalPendingApproval: format: int64 type: integer totalRejected: format: int64 type: integer totalScheduled: description: Number of payments in the SCHEDULED state. Payments initiated through this API execute immediately and are not created in this state, so a non-zero value reflects a SCHEDULED state reported by the payment provider. These payments are also counted under byStatus.SCHEDULED. format: int64 type: integer totalSettled: format: int64 type: integer totalSettledAmount: type: string totalUnconfirmed: description: "Payments in the UNCONFIRMED state: the outcome at the payment provider is not known yet. A payment whose initiation was answered 202 is counted here until it resolves. The same rows are also counted under byStatus.UNCONFIRMED." format: int64 type: integer required: - totalUnconfirmed - totalCreated - totalScheduled - totalSettled - totalFailed - totalRejected - totalCanceled - totalPendingApproval - totalApproved - totalExecuted - totalAmount - totalSettledAmount - byType - byStatus type: object PaymentTypeCountAmount: additionalProperties: false properties: amount: type: string count: format: int64 type: integer required: - count - amount type: object PreflightAccountingFlowResponse: additionalProperties: false properties: ambiguousRoutes: description: Route codes of the flow carried by more than one ledger route, when the flow is ambiguous. items: type: string type: array flow: description: Canonical flow code. examples: - BOLETO_IN type: string malformedReason: description: Which part of that route diverges, when the flow is malformed. type: string malformedRoute: description: First route code of the flow that diverges from the contract, when the flow is malformed. type: string missingActions: description: Actions the malformed route does not declare, when the reason is action_coverage. items: type: string type: array missingRoutes: description: Route codes of the flow absent from the ledger, when the flow is incomplete. items: type: string type: array status: description: complete, absent, incomplete, ambiguous or malformed. examples: - complete type: string required: - flow - status - missingRoutes - ambiguousRoutes - missingActions type: object PreflightAccountingRoutesResponse: additionalProperties: false properties: accountingRoutesEnabled: description: "Whether ACCOUNTING_ROUTES_ENABLED is on in this deployment. Reported, not obeyed: the verdict is judged as if it were on." type: boolean flows: description: One entry per canonical flow, in the order BOLETO_IN, PAYMENT_OUT, DARF_OUT. Empty when the route inventory could not be read. items: $ref: "#/components/schemas/PreflightAccountingFlowResponse" type: array ledgerId: description: Ledger the preflight read, in canonical form. type: string organizationId: description: Organization the preflight read, in canonical form. type: string ready: description: "Whether the plugin can post against this ledger as far as accounting routes are concerned. It is the verdict on the whole ledger: a complete flow in a ledger that is not ready does not post." type: boolean reason: description: Class of the verdict, from a closed vocabulary of accounting_routes_* reasons. Absent for a ledger that holds every canonical route. type: string unrecognisedMarkers: description: Ledger routes carrying a plugin marker the contract does not know. format: int64 type: integer validateRoutes: description: The ledger's validateRoutes setting, or null when the settings could not be read. type: - boolean - "null" required: - organizationId - ledgerId - accountingRoutesEnabled - ready - validateRoutes - unrecognisedMarkers - flows type: object 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 ProviderWebhookPayload: additionalProperties: true properties: clientRequestId: description: Identifier this service sent when it created the entity, echoed back for correlation. Optional here even though the provider envelope declares it required. type: string createTimestamp: description: "Instant the provider recorded for this state, RFC 3339. Optional here: a delivery without one means no reference instant, not a malformed request." format: date-time type: string entity: description: Provider entity name the event belongs to, for example PaymentSlipPay or TaxDarfPayment. Cross-checked against x-webhook-baas-entity; the body wins. type: string pactualId: description: "Provider-assigned primary key of the entity this event is about. A string representation of a GUID in every delivery seen so far, but not validated as one: the field is the provider's to shape." type: string status: description: Provider state the entity moved to, for example PAID. This IS the provider's event name — the x-webhook-baas-event header carries the same value — and it is stored as sent. type: string required: - pactualId - entity - status type: object RepresentQuarantinedWebhookResponse: additionalProperties: false properties: dedupKey: type: string priorVerdict: type: string providerEventType: type: string providerType: type: string receivedAt: type: string representedAt: type: string retryCountBefore: format: int64 type: integer status: type: string webhookId: type: string required: - webhookId - dedupKey - providerType - providerEventType - status - retryCountBefore - receivedAt - representedAt type: object ResubscribeWebhookSubscriptionRequest: additionalProperties: false properties: acknowledge_revoking: description: "OPTIONAL, and it forces a write that would otherwise be refused. Name EXACTLY the resources the 409 reported, each one spelled as the refusal printed it — a bare entity name, or an entity/EVENT pair where only an event under a declared entity is at risk — and the re-registration proceeds and REMOVES them from the provider's subscription. The set is re-measured at the provider on this call and compared against what you sent: a name you left out, or a name the provider is not holding outside the declared set, is refused with another 409 that says which. Comparison is exact per name — no case folding, no trimming — and insensitive to order; repeats are collapsed. Omit the field, or send an empty list, to get the ordinary refusal. It is NOT a conditional write: the provider offers none, so it cannot close the window between this service's read and its write. What it closes is the window between the refusal you read and the call you sent." examples: - - PaymentSlip - PaymentSlipPay/SOME_EVENT items: type: string type: - array - "null" type: object ResubscribeWebhookSubscriptionResource: additionalProperties: false properties: entity: type: string event_names: items: type: string type: - array - "null" required: - entity - event_names type: object ResubscribeWebhookSubscriptionResponse: additionalProperties: false properties: provider_type: type: string resources: items: $ref: "#/components/schemas/ResubscribeWebhookSubscriptionResource" type: - array - "null" status: type: string webhook_url: type: string required: - status - provider_type - webhook_url - resources 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 WebhookConfigResponse: additionalProperties: false properties: active: type: boolean callbackUrl: type: string createdAt: type: string enabledEvents: items: type: string type: - array - "null" id: type: string secret: description: Always the literal "[REDACTED]" — the signing secret is never returned by this API. examples: - "[REDACTED]" type: string updatedAt: type: string required: - id - callbackUrl - secret - enabledEvents - active - createdAt - updatedAt type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http 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.\n\nERROR 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 openapi: 3.1.0 paths: /v1/admin/accounting-routes/preflight: get: description: |- Reports whether the plugin can post against one (organization, ledger) of the caller's tenant, and the state of each canonical flow there: BOLETO_IN, PAYMENT_OUT and DARF_OUT, each complete, absent, incomplete (with the missing route codes), ambiguous (with the repeated codes) or malformed (with the code and the reason). The routes reported are the ORGANIZATION's: from Midaz v4.1.0 on, a listing through any ledger of the organization returns every route of it, so two ledgers of one organization report the same flows. `validateRoutes` and `ready` are the requested ledger's. READ-ONLY. It reads the ledger live, with GET requests only, and bypasses the accounting routes cache: nothing is posted, cached or stored, so it is safe to run right after provisioning and as often as needed. `ready` is the verdict on the WHOLE ledger: a flow reported complete in a ledger that is not ready still does not post. `reason` names the class of the verdict: accounting_routes_not_provisioned (ready: no canonical route, and the ledger does not validate routes), accounting_routes_required_but_absent, accounting_routes_incomplete, accounting_routes_ambiguous, accounting_routes_malformed, accounting_routes_dependency_unavailable, accounting_routes_access_denied or accounting_routes_unreadable. It is absent for a ledger that holds every canonical route. The ACCOUNTING_ROUTES_ENABLED knob is REPORTED, NOT OBEYED: the verdict is judged as if it were on, because this is what runs before it is turned on, and its current value is in `accountingRoutesEnabled`. The organization comes from the X-Organization-Id header (400 PBP-0025) and the ledger from the ledgerId query parameter (400 PBP-0026). An organization or ledger the ledger does not know, for this tenant, is answered 404 without saying which. operationId: preflightAccountingRoutes parameters: - description: "Midaz organization of the ledger to inspect. 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 of the ledger to inspect. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025." type: string - description: "Midaz ledger to inspect. Required: absent, blank or not a canonical UUID is refused with 400 PBP-0026." explode: false in: query name: ledgerId schema: description: "Midaz ledger to inspect. Required: absent, blank or not a canonical UUID is refused with 400 PBP-0026." type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/PreflightAccountingRoutesResponse" 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/problem+json: schema: $ref: "#/components/schemas/Detail" application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error '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: [] summary: Preflight the accounting routes of a ledger tags: - Admin x-mint: href: /pt/reference/interfaces/payments-btg/preflight-accounting-routes /v1/admin/providers/connect: post: 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/problem+json: schema: $ref: "#/components/schemas/Detail" application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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: [] summary: Connect provider with the tenant's client credentials tags: - Admin x-mint: href: /pt/reference/interfaces/payments-btg/connect-provider /v1/admin/providers/webhooks/{provider_type}/resubscribe: post: description: |- Re-registers this tenant's EXISTING webhook subscription at the provider, without rotating the connection. WHAT IT DOES, EXACTLY: it reads the connection this tenant currently serves deliveries on, recomposes that connection's delivery URL, and sends the provider a subscription write carrying the declared resource set pointed at that URL. The connection record is untouched — same connection token, same signing key, same delivery URL — so a URL or a key you are already holding stays valid, and nothing you have configured elsewhere needs to change. ⚠️ WHAT IT DOES NOT DO, AND THE LIMIT IS THE POINT. When the provider reports a subscription as BLOCKED after repeated delivery failures, the procedure that returns it to service is NOT MEASURED by this service. This operation re-registers; whether the provider's consecutive-error counter resets, and whether deliveries resume, is something you OBSERVE afterwards — in the provider's own subscription state and in this service's webhook.subscription.blocked gauge — rather than something this call promises. Confirm the procedure with the provider before treating a blocked channel as repaired. ⛔ THE WRITE REPLACES THE PROVIDER'S RESOURCE ARRAY WHOLE, WHICH IS WHY IT READS BEFORE IT WRITES. The resources field of the answer is the entire set that is registered afterwards; any resource the provider held that is not in that list would no longer be subscribed, and the provider reports nothing about a removal. On a deployment where several consumers share one provider credential, that array is shared too, so the resource at risk may not even be yours. This operation therefore reads the subscription the provider currently holds under your credential BEFORE writing, and refuses with 409 if that subscription carries anything outside the set below — the answer then names resources that would have been removed, and nothing is written. The read exists only to refuse: the write's resource array is always the declared set and is never assembled from what the provider reports. If that read cannot be completed the call is refused with 502, because a read that failed says nothing about what the provider is holding. ⚠️ THERE IS ONE WAY PAST THAT 409, AND IT IS EXPLICIT: send the optional acknowledge_revoking naming exactly the resources the refusal reported. The call then proceeds and THOSE RESOURCES ARE REMOVED from the provider's subscription. The set is measured again on that call and compared against what you sent, so a name you left out — or a name the provider is not holding outside the declared set — is refused with another 409 saying which, and still writes nothing. It is NOT a conditional write: the provider offers none, so the window between this service reading the subscription and writing it is as open as it ever was. What the acknowledgement rules out is acting on a stale picture — a resource that appeared between the refusal you read and the call you sent makes your call FAIL instead of destroying something you never saw. IT IS A LIVE TENANT'S SELF-SERVICE ACTION, AND THAT BOUNDS WHO YOU ACT AS, NOT WHAT YOU AFFECT. The tenant comes from the credentials you authenticate with and there is no tenant parameter anywhere in this request, so you cannot name somebody else. The provider, however, files ONE subscription per provider credential, not one per tenant: where several tenants share a credential, that single subscription is what this write re-points at YOUR tenant's delivery URL, and the others keep receiving deliveries only because their own health poller notices the registered address is not the one it composed and re-registers on its next tick. Which tenants share a credential is not something this service can see. THE ANSWER CARRIES THE DELIVERY URL, WHICH IS A CREDENTIAL — the connection's routing token is a segment of it. Treat the response body as secret. It carries NO signing key. A tenant with no connection to re-present, and a provider_type this deployment does not serve, are both refused with 404. The operation declares no Idempotency-Key: a retry re-executes, and re-executing sends the identical write. ⚠️ A RETRY OF A CALL THAT CARRIED acknowledge_revoking IS THE ONE EXCEPTION TO THAT, AND THE 409 IT ANSWERS PROVES LESS THAN IT LOOKS LIKE. Once a forced write has landed, the resources you acknowledged are gone from the provider's subscription — so on the retry they are no longer outside the declared set, your acknowledgement names something that is not there, and the call is refused with 409. That refusal reports one thing only: the set measured on this call is no longer the set you named. It is consistent with your first call having landed, and equally consistent with it never having reached the provider while some OTHER actor removed those resources in the meantime — on a shared provider credential, another consumer's own health poller is exactly such an actor. So it is not evidence of either on its own: do not read it as proof the write happened, and do not read it as "nothing was written" either. Check whether the removal already happened before re-sending, and re-send WITHOUT the field to see the current state. This is why a retry on a timeout should be a plain call, not a repeated force. operationId: resubscribeProviderWebhook 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: Provider whose subscription is being re-registered, for example BTG. Matched case-insensitively; a provider this deployment does not serve is refused with 404. in: path name: provider_type required: true schema: description: Provider whose subscription is being re-registered, for example BTG. Matched case-insensitively; a provider this deployment does not serve is refused with 404. examples: - BTG type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ResubscribeWebhookSubscriptionRequest" responses: "200": content: application/json: schema: $ref: "#/components/schemas/ResubscribeWebhookSubscriptionResponse" 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 "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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: [] summary: Re-register the tenant's existing webhook subscription at a provider tags: - Admin x-mint: href: /pt/reference/interfaces/payments-btg/resubscribe-provider-webhook /v1/admin/quarantine/webhooks/{id}/represent: post: description: "Returns ONE inbound provider webhook out of quarantine and back into the reconciliation sweep's claim set, with a full retry budget. Quarantine is the terminal PERMANENTLY_FAILED state: the service modelled the event, could not apply it within its retry budget, and stopped claiming the row. NOTHING IS APPLIED BY THIS CALL. It does not contact the ledger, does not contact the provider and does not change any boleto or payment. It changes one row of the webhook journal so that the ordinary drain picks the delivery up again on its next cycle, through exactly the same processing path every other delivery takes. Watch the drain, not this response, to learn whether the delivery finally applied. A request under a new Idempotency-Key for a row that is no longer in quarantine — because a previous call already released it, or because it never was — is refused with 409 PBP-0007 rather than released a second time. Fix the cause before re-presenting; a row released into the same failing condition simply returns to quarantine." operationId: representQuarantinedWebhook 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, or with a value that is not a UUID, 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, or with a value that is not a UUID, is refused with 400 PBP-0012." type: string - description: Identifier of the quarantined webhook journal row (UUID), as reported by the PERMANENTLY_FAILED log line and metric. in: path name: id required: true schema: description: Identifier of the quarantined webhook journal row (UUID), as reported by the PERMANENTLY_FAILED log line and metric. examples: - 123e4567-e89b-12d3-a456-426614174000 format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RepresentQuarantinedWebhookResponse" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" 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 "409": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Conflict. PBP-0007 means the webhook exists and is not in quarantine: a previous call already re-presented it, or it was never quarantined. Nothing was changed. 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." "422": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" 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 "503": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable security: - BearerAuth: [] summary: Re-present a quarantined provider webhook tags: - Admin x-mint: href: /pt/reference/interfaces/payments-btg/represent-quarantined-webhook /v1/admin/webhooks: get: description: Retrieves the current outbound webhook configuration for the tenant. operationId: getAdminWebhookConfig 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 responses: "200": content: application/json: schema: $ref: "#/components/schemas/WebhookConfigResponse" 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/problem+json: schema: $ref: "#/components/schemas/Detail" application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error '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: [] summary: Get webhook configuration tags: - Admin x-mint: href: /pt/reference/interfaces/payments-btg/get-webhook-configuration post: description: Registers or updates the callback URL for receiving status change notifications. One configuration per tenant. operationId: configureAdminWebhook 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, or with a value that is not a UUID, 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, or with a value that is not a UUID, is refused with 400 PBP-0012." type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ConfigureWebhookRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/WebhookConfigResponse" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" 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." "409": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" 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." "422": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" 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 "503": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" description: Service Unavailable. PBP-0008 means the tenant's storage could not be resolved. The request was not processed; wait and send the same request again with the same Idempotency-Key. security: - BearerAuth: [] summary: Configure outbound webhook tags: - Admin x-mint: href: /pt/reference/interfaces/payments-btg/configure-webhook /v1/boletos: get: description: Lists boletos with optional status, kind, type and date filters, paginated. operationId: listBoletos parameters: - description: "Midaz organization whose boletos are listed. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. Only boletos of this organization are listed and counted." in: header name: X-Organization-Id schema: description: "Midaz organization whose boletos are listed. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. Only boletos of this organization are listed and counted." type: string - description: Status filter. explode: false in: query name: status schema: description: Status filter. enum: - PENDING - CREATED - SETTLED - CANCELED - INACTIVATED - FAILED examples: - CREATED type: string - description: Boleto kind filter. explode: false in: query name: kind schema: description: Boleto kind filter. enum: - SINGLE - INSTALLMENT examples: - SINGLE type: string - description: Boleto type filter. explode: false in: query name: type schema: description: Boleto type filter. enum: - TRADITIONAL - QR_CODE - HYBRID examples: - TRADITIONAL type: string - description: Created-from bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and starts at its first instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T00:00:00-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B). explode: false in: query name: from schema: description: Created-from bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and starts at its first instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T00:00:00-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B). examples: - "2026-01-01" pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}(T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2}))?$ patternDescription: a YYYY-MM-DD date or an RFC 3339 date-time with offset type: string - description: Created-to bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and covers it to its last instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T23:59:59.999999-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B). explode: false in: query name: to schema: description: Created-to bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and covers it to its last instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T23:59:59.999999-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B). examples: - "2026-12-31" pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}(T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2}))?$ patternDescription: a YYYY-MM-DD date or an RFC 3339 date-time with offset type: string - description: Due-date lower bound, inclusive. explode: false in: query name: dueDateFrom schema: description: Due-date lower bound, inclusive. examples: - "2026-02-01" format: date type: string - description: Due-date upper bound, inclusive. explode: false in: query name: dueDateTo schema: description: Due-date upper bound, inclusive. examples: - "2026-11-30" format: date type: string - description: Page number, one-based. explode: false in: query name: page schema: default: 1 description: Page number, one-based. examples: - 1 format: int64 minimum: 1 type: integer - description: Items per page. explode: false in: query name: limit schema: default: 20 description: Items per page. examples: - 20 format: int64 maximum: 100 minimum: 1 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/ListBoletosResponse" 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." "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error '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: [] summary: List boletos tags: - Boletos x-mint: href: /pt/reference/interfaces/payments-btg/list-boletos post: description: "Issues a traditional boleto through the banking provider. The supported boleto type is TRADITIONAL; a request with type HYBRID or QR_CODE is refused with 422 PBP-0006. The boleto is issued without a guarantor (sacador avalista), and this operation does not accept one: a request that sends guarantor is refused with 400 PBP-0001, naming body.guarantor as an unexpected property. A nosso numero already held by an active boleto of the same provider account is refused with 422 PBP-0108 before the provider is called. When that holder can be read, the PBP-0108 detail names the boleto that holds the number, and the problem carries its id as ourNumberHolderBoletoId. When it is an earlier emission still without the provider's answer, the detail says so and does not ask for another number, because that emission can still become a live boleto; when it is a boleto the provider already answered, the detail asks for it to be consulted before another number is informed, because it may be an earlier emission of the same charge whose answer was lost. When a title the local index cannot see holds the number — for example, one issued through another deployment or another tenant sharing the provider account — the provider accepts the emission and refuses it later, and the boleto moves to FAILED, unless the title holding the number belongs to this same emission, in which case the boleto is bound to that title. The boleto stays PENDING instead when the provider's search cannot tell whose title holds the number — it lists a live title with that number that it attributes to no emission, more than one title of this same emission, or one of this emission without the provider's identifier or that disagrees with the boleto — or when the search could not be made or read whole; it also stays PENDING, transiently, while the search does not answer or is postponed to a later reconciliation pass." operationId: createBoleto parameters: - description: "Midaz organization the account and the ledger entry 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 the ledger entry 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, or with a value that is not a UUID, 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, or with a value that is not a UUID, is refused with 400 PBP-0012." type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateBoletoRequest" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CreateBoletoResponse" description: Created "400": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" 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 "409": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" 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." "422": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" 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 "503": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable security: - BearerAuth: [] summary: Issue a single boleto tags: - Boletos x-mint: href: /pt/reference/interfaces/payments-btg/issue-boleto /v1/boletos/installments: post: description: "Installment boleto issuance is not available on this service. A request that passes authentication, authorization and request validation is answered with 501 Not Implemented, and no boleto or installment series is created. A request refused earlier keeps its own status: 401 or 403 for authentication and authorization, 400 PBP-0012 for a missing or malformed Idempotency-Key, and 400 PBP-0001 for a body that fails schema validation, including one that sends guarantor, which this operation does not accept." operationId: createBoletoInstallments 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, or with a value that is not a UUID, 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, or with a value that is not a UUID, 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: "Not returned: this operation is unavailable and answers 501 Not Implemented." "400": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" 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 "409": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" 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." "422": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" 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 "501": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not Implemented. Installment boletos are not available on this service: every request that passes authentication, authorization and request validation is answered this way. The response body carries `code` PBP-0109 and a `detail` saying that installment boletos are not available. No installment series is created or read. Do not retry." "503": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" description: Service Unavailable. PBP-0008 means the tenant's storage could not be resolved. The request was not processed; wait and send the same request again with the same Idempotency-Key. security: - BearerAuth: [] summary: Issue installment boletos tags: - Boletos x-mint: href: /pt/reference/interfaces/payments-btg/issue-installment-boletos /v1/boletos/installments/{series_id}: get: description: "Installment series lookup is not available on this service. A request that passes authentication, authorization and parameter validation is answered with 501 Not Implemented. A request refused earlier keeps its own status: 401 or 403 for authentication and authorization, and 400 PBP-0001 when series_id is not a UUID." operationId: getInstallmentSeries 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: Installment series identifier (UUID). in: path name: series_id required: true schema: description: Installment series identifier (UUID). examples: - 123e4567-e89b-12d3-a456-426614174000 format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/GetInstallmentsResponse" description: "Not returned: this operation is unavailable and answers 501 Not Implemented." "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/problem+json: schema: $ref: "#/components/schemas/Detail" application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error "501": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not Implemented. Installment boletos are not available on this service: every request that passes authentication, authorization and request validation is answered this way. The response body carries `code` PBP-0109 and a `detail` saying that installment boletos are not available. No installment series is created or read. Do not retry." '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: [] summary: Get installment series tags: - Boletos x-mint: href: /pt/reference/interfaces/payments-btg/get-installment-series /v1/boletos/{id}: get: description: Retrieves a single boleto by its ID with full detail. operationId: getBoleto parameters: - description: "Midaz organization the boleto belongs to. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. A boleto of another organization is answered 404, exactly as one that does not exist." in: header name: X-Organization-Id schema: description: "Midaz organization the boleto belongs to. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. A boleto of another organization is answered 404, exactly as one that does not exist." type: string - description: Boleto identifier (UUID). in: path name: id required: true schema: description: Boleto identifier (UUID). examples: - 123e4567-e89b-12d3-a456-426614174000 format: uuid type: string 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 "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/problem+json: schema: $ref: "#/components/schemas/Detail" application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error '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: [] summary: Get boleto by ID tags: - Boletos x-mint: href: /pt/reference/interfaces/payments-btg/get-boleto /v1/boletos/{id}/cancel: post: description: "Cancels a boleto in CREATED status. No ledger entry is recorded: issuance takes no balance reservation, so cancellation has nothing to reverse." operationId: cancelBoleto parameters: - description: "Midaz organization the boleto to cancel belongs to. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. A boleto of another organization is answered 404, exactly as one that does not exist." in: header name: X-Organization-Id schema: description: "Midaz organization the boleto to cancel belongs to. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. A boleto of another organization is answered 404, exactly as one that does not exist." type: string - description: "Client-supplied idempotency key, a UUID. Required: a request without it, or with a value that is not a UUID, 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, or with a value that is not a UUID, is refused with 400 PBP-0012." type: string - description: Boleto identifier (UUID). in: path name: id required: true schema: description: Boleto identifier (UUID). examples: - 123e4567-e89b-12d3-a456-426614174000 format: uuid type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CancelBoletoRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/CancelBoletoResponse" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" 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 "409": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" 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." "422": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" 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 "503": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable security: - BearerAuth: [] summary: Cancel an issued boleto tags: - Boletos x-mint: href: /pt/reference/interfaces/payments-btg/cancel-boleto /v1/boletos/{id}/pdf: get: description: Streams the FEBRABAN-rendered PDF for a previously emitted boleto. The PDF is fetched on demand from the provider; if the provider has not finished registering the boleto, the response is 503 with a Retry-After header. operationId: getBoletoPDF parameters: - description: "Midaz organization the boleto belongs to. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. A boleto of another organization is answered 404, exactly as one that does not exist." in: header name: X-Organization-Id schema: description: "Midaz organization the boleto belongs to. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. A boleto of another organization is answered 404, exactly as one that does not exist." type: string - description: Boleto identifier (UUID). in: path name: id required: true schema: description: Boleto identifier (UUID). examples: - 123e4567-e89b-12d3-a456-426614174000 format: uuid type: string responses: "200": content: application/pdf: schema: contentMediaType: application/octet-stream format: binary type: string description: The rendered FEBRABAN boleto PDF, streamed as raw bytes. headers: Content-Disposition: schema: description: attachment; filename="boleto-.pdf" type: string Content-Type: schema: description: Always application/pdf. type: string "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 "408": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Request Timeout "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Service Unavailable security: - BearerAuth: [] summary: Download boleto PDF tags: - Boletos x-mint: href: /pt/reference/interfaces/payments-btg/download-boleto-pdf /v1/dashboards/boletos: get: description: Returns aggregated counts, amounts, and breakdowns of boletos for the specified period. operationId: getBoletoDashboard parameters: - description: "Midaz organization whose boletos are aggregated. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. Only boletos of this organization are counted and summed." in: header name: X-Organization-Id schema: description: "Midaz organization whose boletos are aggregated. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. Only boletos of this organization are counted and summed." type: string - description: Created-from bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and starts at its first instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T00:00:00-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B). explode: false in: query name: from schema: description: Created-from bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and starts at its first instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T00:00:00-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B). examples: - "2026-01-01" pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}(T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2}))?$ patternDescription: a YYYY-MM-DD date or an RFC 3339 date-time with offset type: string - description: Created-to bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and covers it to its last instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T23:59:59.999999-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B). explode: false in: query name: to schema: description: Created-to bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and covers it to its last instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T23:59:59.999999-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B). examples: - "2026-12-31" pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}(T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2}))?$ patternDescription: a YYYY-MM-DD date or an RFC 3339 date-time with offset type: string - description: Due-date lower bound, inclusive. explode: false in: query name: dueDateFrom schema: description: Due-date lower bound, inclusive. examples: - "2026-02-01" format: date type: string - description: Due-date upper bound, inclusive. explode: false in: query name: dueDateTo schema: description: Due-date upper bound, inclusive. examples: - "2026-11-30" format: date type: string - description: Boleto type filter. explode: false in: query name: type schema: description: Boleto type filter. enum: - TRADITIONAL - HYBRID - QR_CODE examples: - TRADITIONAL type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/BoletoDashboardResponse" 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." "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error '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: [] summary: Get boleto dashboard tags: - Dashboards x-mint: href: /pt/reference/interfaces/payments-btg/get-boleto-dashboard /v1/dashboards/payments: get: description: Returns aggregated counts, amounts, and breakdowns of payments for the specified period. operationId: getPaymentDashboard parameters: - description: "Midaz organization whose payments are aggregated. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. Only payments of this organization are counted and summed." in: header name: X-Organization-Id schema: description: "Midaz organization whose payments are aggregated. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. Only payments of this organization are counted and summed." type: string - description: Created-from bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and starts at its first instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T00:00:00-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B). explode: false in: query name: from schema: description: Created-from bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and starts at its first instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T00:00:00-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B). examples: - "2026-01-01" pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}(T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2}))?$ patternDescription: a YYYY-MM-DD date or an RFC 3339 date-time with offset type: string - description: Created-to bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and covers it to its last instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T23:59:59.999999-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B). explode: false in: query name: to schema: description: Created-to bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and covers it to its last instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T23:59:59.999999-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B). examples: - "2026-12-31" pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}(T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2}))?$ patternDescription: a YYYY-MM-DD date or an RFC 3339 date-time with offset type: string - description: Payment type filter. explode: false in: query name: type schema: description: Payment type filter. enum: - BANKSLIP - UTILITIES - DARF examples: - BANKSLIP type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/PaymentDashboardResponse" 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." "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error '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: [] summary: Get payment dashboard tags: - Dashboards x-mint: href: /pt/reference/interfaces/payments-btg/get-payment-dashboard /v1/payments: get: description: Lists payments with optional status, type, creation-date and due-date filters, paginated. operationId: listPayments parameters: - description: "Midaz organization whose payments are listed. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. Only payments of this organization are listed and counted." in: header name: X-Organization-Id schema: description: "Midaz organization whose payments are listed. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. Only payments of this organization are listed and counted." type: string - description: "Status filter. UNCONFIRMED selects the payments whose outcome at the payment provider is not known yet: an initiation answered 202 leaves its payment there until it resolves." explode: false in: query name: status schema: description: "Status filter. UNCONFIRMED selects the payments whose outcome at the payment provider is not known yet: an initiation answered 202 leaves its payment there until it resolves." enum: - UNCONFIRMED - CREATED - SCHEDULED - PENDING_APPROVAL - APPROVED - EXECUTED - SETTLED - REJECTED - FAILED - CANCELED examples: - CREATED type: string - description: Payment type filter. explode: false in: query name: type schema: description: Payment type filter. enum: - BANKSLIP - UTILITIES - DARF examples: - BANKSLIP type: string - description: Created-from bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and starts at its first instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T00:00:00-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B). explode: false in: query name: from schema: description: Created-from bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and starts at its first instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T00:00:00-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B). examples: - "2026-01-01" pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}(T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2}))?$ patternDescription: a YYYY-MM-DD date or an RFC 3339 date-time with offset type: string - description: Created-to bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and covers it to its last instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T23:59:59.999999-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B). explode: false in: query name: to schema: description: Created-to bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and covers it to its last instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T23:59:59.999999-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B). examples: - "2026-12-31" pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}(T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2}))?$ patternDescription: a YYYY-MM-DD date or an RFC 3339 date-time with offset type: string - description: Due-date lower bound, inclusive. It matches the DARF and BANKSLIP payments that carry a due date (see dueDate on the payment). UTILITIES payments carry none, so this bound matches none of them. explode: false in: query name: dueDateFrom schema: description: Due-date lower bound, inclusive. It matches the DARF and BANKSLIP payments that carry a due date (see dueDate on the payment). UTILITIES payments carry none, so this bound matches none of them. examples: - "2026-02-01" format: date type: string - description: Due-date upper bound, inclusive. It matches the DARF and BANKSLIP payments that carry a due date (see dueDate on the payment). UTILITIES payments carry none, so this bound matches none of them. explode: false in: query name: dueDateTo schema: description: Due-date upper bound, inclusive. It matches the DARF and BANKSLIP payments that carry a due date (see dueDate on the payment). UTILITIES payments carry none, so this bound matches none of them. examples: - "2026-11-30" format: date type: string - description: Page number, one-based. explode: false in: query name: page schema: default: 1 description: Page number, one-based. examples: - 1 format: int64 minimum: 1 type: integer - description: Items per page. explode: false in: query name: limit schema: default: 20 description: Items per page. examples: - 20 format: int64 maximum: 100 minimum: 1 type: integer - description: "The Idempotency-Key a payment was created under, on POST /v1/payments or POST /v1/payments/darf. Lists the payment that key created in this organization, if any: the way to find what a creation answered without a payment id left behind, a 5xx above all. A key whose creation was refused before anything was created lists nothing. A payment retried under the same key after a refusal for funds is listed with the refused attempt. Combines with the other filters. A value that is not a UUID is refused with 400 PBP-0001; an empty value is ignored, as on the other filters. Meant for recovering one request, not for polling." explode: false in: query name: idempotencyKey schema: description: "The Idempotency-Key a payment was created under, on POST /v1/payments or POST /v1/payments/darf. Lists the payment that key created in this organization, if any: the way to find what a creation answered without a payment id left behind, a 5xx above all. A key whose creation was refused before anything was created lists nothing. A payment retried under the same key after a refusal for funds is listed with the refused attempt. Combines with the other filters. A value that is not a UUID is refused with 400 PBP-0001; an empty value is ignored, as on the other filters. Meant for recovering one request, not for polling." examples: - 6f9619ff-8b86-d011-b42d-00c04fc964ff type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ListPaymentsResponse" 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." "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error '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: [] summary: List payments tags: - Payments x-mint: href: /pt/reference/interfaces/payments-btg/list-payments post: description: Initiates a bankslip or utilities bill payment. The type is classified automatically from the digitable line. The payment is executed immediately; this operation does not accept a scheduling date. A request that sends scheduledDate is refused with 400 PBP-0001, naming body.scheduledDate as an unexpected property. operationId: initiatePayment parameters: - description: "Midaz organization the account and the ledger entry 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 the ledger entry 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, or with a value that is not a UUID, 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, or with a value that is not a UUID, is refused with 400 PBP-0012." type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/InitiatePaymentRequest" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/InitiatePaymentResponse" description: "Created. The payment provider acknowledged the payment: it is in status CREATED and carries the provider's `providerId`. Its outcome arrives later; follow it with GET /v1/payments/{id}. A request under an `Idempotency-Key` that already names a payment the provider acknowledged is answered 201 too, with that payment as it stands, in whatever status it has reached. Compare the 202, where the outcome at the provider is not known." "202": content: application/json: schema: $ref: "#/components/schemas/InitiatePaymentResponse" description: "Accepted. The payment was created, its funds are reserved, and the instruction was sent to the payment provider, but its outcome is NOT known: the provider did not answer in time, failed on its side, dropped the connection or answered in a way that could not be read, or this service could not record the provider's acknowledgement. The payment is in status UNCONFIRMED and carries no `providerId`. ⚠️ Do NOT send it again under a new `Idempotency-Key`: the provider may have it, and a second request can pay the slip twice. It resolves without you: the reconciliation reads it from the provider and moves it to the status the provider reports, or to FAILED, with its funds released, when the provider still has no record of it. Read its current state with GET /v1/payments/{id}. A resend under the SAME `Idempotency-Key` is safe: for up to 48 hours it answers this same 202, even after the payment has resolved, so read the payment by id for its current status. A request under a key that already names a payment still UNCONFIRMED is answered 202 too." "400": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Bad Request. Branch on `code`. PBP-0001 means the request is malformed: the body is missing, is not JSON, fails schema validation, or contains a member this operation does not accept. Each unexpected member is named in errors[] by its `location`; `payer`, `payeeName`, `payeeTaxId` and `scheduledDate` are not accepted. PBP-0025 means the `X-Organization-Id` header is missing or is not a canonical UUID. PBP-0026 means the `ledgerId` member is missing, blank or not a canonical UUID. PBP-0012 means the `Idempotency-Key` header is missing or is not a UUID. PBP-0204 means the account named in `midazAccountId` has no registered owner, so the payer cannot be established. The payer is always taken from the account's registration, so no request field resolves this: register the account's owner, or use an account that has one, and send the request again. In every case no payment was created and nothing was sent to the payment provider." "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. Two branches, told apart by `code`. PBP-0005 means the funding account named in the request was not found or is not accessible to the caller. PBP-0110 means the source of the payment slip has no bill under this digitable line: the provider's pre-payment consult answered that it does not exist. Check the line. For both, nothing was created and the payment provider was not instructed, so the `Idempotency-Key` is released and a resend is the first instruction." "409": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" 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." "422": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Unprocessable Entity. The request was valid but could not be carried out; branch on `code`. PBP-0300 means the funding account does not have enough available balance, and PBP-0302 means the funds reservation would take the funding account past its overdraft limit. Both are answered BEFORE the payment provider is instructed: the payment is recorded as failed, and nothing was sent to the payment provider or paid. The Idempotency-Key is released, so the request can be sent again, under the same or a new key, once the balance allows. A refusal for the ledger's accounting configuration is not answered with this status: it is PBP-0301 on the 503. PBP-0014 means the payment provider refused the payment instruction on the only attempt made. Nothing was paid: the payment is recorded as failed and its funds reservation is cancelled. The Idempotency-Key is consumed: a resend under the same key answers this same 422 again and runs nothing. Correct the cause and send the request under a new Idempotency-Key. PBP-0013 means this Idempotency-Key was already used for a different request: another body, or a payment with another digitable line, funding account, `X-Organization-Id` or `ledgerId`. Nothing was done. Send this payment under a key of its own. PBP-0210 means the payment provider's pre-payment check found that this slip cannot be paid: it is not valid for payment (already paid, cancelled or expired; the provider does not say which), or its amount is zero or less. No payment was created and the payment provider was not instructed, so the request can be sent again under the same or a new Idempotency-Key, but it keeps answering this code until the slip's state changes. PBP-0202 means account validation is not available on this deployment; no payment was created. Contact support. PBP-0017 means the payment provider account this payment would be paid from could not be established. No payment was created and nothing was sent to the payment provider. Sending the request again does not resolve it. Contact support. PBP-0205 means the registration of the funding account's owner is inconsistent — a tax id that is not a valid CPF or CNPJ, one that contradicts the registered person type, or more than one registered owner — so the payer cannot be established. No payment was created. The payer is always taken from the account's registration, not from the request, so correct the owner's registration before sending the request again. PBP-0208 means the tax document of the funding account's registered owner is not numeric, for example an alphanumeric CNPJ. The registration is valid, but the payment provider accepts only a numeric CPF or CNPJ. No payment was created; use a funding account whose registered owner has a numeric document. PBP-0111 means the source of the payment slip refused it in the payment provider's pre-payment check, for the reason whose provider code the `detail` names — for example an amount that differs from the registered one. No payment was created and the payment provider was not instructed, so the request can be sent again under the same or a new Idempotency-Key; it only succeeds once the cause the code names is resolved." "500": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Internal Server Error. PBP-0002 is an unexpected failure with no classified answer, and it answers at two moments. BEFORE CREATION, a failure this service could not classify before it recorded the payment (for example while it checked whether the request already created a payment, prepared the call to the payment provider or built the payment) leaves nothing behind: the Idempotency-Key is released, and the SAME request under the SAME key runs again. AFTER CREATION, every failure to record the payment before the payment provider is instructed is answered 503 PBP-0301, and every outcome after the instruction is 201, 202, 422 or 503 PBP-0211, so a 500 there is a defect, not a branch to code against: the payment may or may not exist, and in the rare case the failure followed the instruction it may have been sent. The response does not say which moment it was. Before sending the request under a NEW Idempotency-Key, look for it: GET /v1/payments with `idempotencyKey` set to the key this request was sent under. A resend under the SAME key answers 409 PBP-0007 while the first request still holds the key; after that it either replays this 500, with a message that the original may have taken effect, or, when nothing was stored, runs the request again and answers from the payment it recorded, if any. Once the request has been sent under a new Idempotency-Key, never resend it under the old one: if this service could not store this answer, the old key runs the request again after five minutes, and could pay alongside the new one." "502": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Bad Gateway. Branch on `code`: the `detail` of a 5xx response is a fixed generic text. PBP-0113 means the payment provider's pre-payment check for this slip returned an answer that cannot be used: no amount, an amount outside the minimum and maximum the same answer declares, the provider's internal error (PIE002) reported inside the `errors[]` of an answer, a refusal reason this API does not recognize, or a body that cannot be read. A provider that fails without answering, PIE002 included, is 503 PBP-0015, not this. No payment was created and the payment provider was not instructed. The Idempotency-Key is released, so the same request can be sent again under the same key; a later check may return a usable answer." "503": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Service Unavailable. Branch on `code`: the `detail` of a 5xx response is a fixed generic text. PBP-0211 means the payment provider did not receive the payment instruction: it was closed for the day (outside the hours it accepts), unreachable on every attempt, or calls to it were suspended after repeated failures; it refused the call itself on the only attempt made — not authorized, forbidden, or not received in full in time; or this API could not authenticate with the provider or set up the call to it at all. Nothing was paid. The payment was created, is recorded as failed, and its funds reservation is cancelled shortly after this answer. The Idempotency-Key is consumed: a resend under the same key answers this same 503 again and runs nothing. To try again, send the request under a new Idempotency-Key, which is safe because nothing was paid; until the first reservation is released it may be answered PBP-0300. While the provider is closed, every attempt answers this code until it reopens, and while it refuses these calls, or they cannot be authenticated, every attempt answers it until an operator restores access. PBP-0015 means the payment provider's pre-payment consult of the slip, which runs before any payment is created, gave no usable answer: it could not be reached, did not answer in time, refused the call, failed on its side, or calls to it were suspended after repeated failures. No payment was created and the payment provider was not instructed. The Idempotency-Key is released, so send the same request again under the same key. PBP-0015 is never answered after the payment instruction is sent: an instruction whose outcome is not known is answered 202 with the payment in status UNCONFIRMED, and one the payment provider did not receive is answered PBP-0211. PBP-0008 means the tenant's storage could not be resolved. The request was not processed and no payment was created; wait and send the same request again with the same Idempotency-Key. PBP-0206 means the registered owner of the funding account, who is the payer, could not be established because the records that identify it could not be reached or are not available on this deployment. No payment was created and the payment provider was not called. Wait and send the request again; if a resend under the same Idempotency-Key is answered 500 PBP-0002, send it under a new key. If the request under a new key answers this code again, contact support. PBP-0301 means the funds could not be reserved in the ledger, or the payment could not be recorded before the payment provider was instructed. On this operation it is always answered BEFORE the payment provider is instructed: nothing was sent to the payment provider and nothing was paid. It is answered at two moments. Before the payment is created, nothing exists: where accounting routes are enabled, the tenant's accounting routes could not be read or are incomplete or inconsistent; and on an instance that resolves a credential per tenant, that credential could not be resolved, or was rejected, while the funding account was being checked. The Idempotency-Key was released, so the same request under the same key runs again, and succeeds once the cause is repaired. After the payment is created, it may exist in status UNCONFIRMED and was not sent. That payment is never sent to the payment provider: the reconciliation marks it FAILED and releases any funds reserved for it. Rarely, that needs an operator; contact support in those cases. This answer is stored, so a resend under the same key answers this same 503 again and runs nothing. The response does not say which of the two moments it was: both carry the same code and status, and no payment id. The remedy is the same: once the cause is repaired, send the request under a NEW Idempotency-Key, which cannot pay twice because a payment answered with this code is never instructed. Once the request has been sent under a new Idempotency-Key, never resend it under the old one: if this service could not store this answer, the old key runs the request again after five minutes, and could pay alongside the new one. Until the first payment's reservation is released, the new request may be answered PBP-0300. To account for a payment the first request may have created, call GET /v1/payments with `idempotencyKey` set to the Idempotency-Key the request was sent under. A payment found there reads UNCONFIRMED until it ends FAILED (follow it with GET /v1/payments/{id}), and it is never paid." security: - BearerAuth: [] summary: Initiate a payment tags: - Payments x-mint: href: /pt/reference/interfaces/payments-btg/initiate-payment /v1/payments/consult: post: description: |- Consults a bill by its digitable line without paying it: the source's own view of the amount, the dates and who receives the money. **Why POST for a read.** The digitable line identifies a payable bill and is sensitive, so it travels in the body instead of the URL, where proxies, logs and browser history would keep it. Nothing is created or changed: the request carries no Idempotency-Key and repeating it is safe. **Local validation first.** The line must be 47 digits for a bank slip or 48 digits starting with 8 for a utilities bill, digits only and never normalized: any other form is refused with 400 PBP-0001 before any check digit is computed. A line in the right form whose check digits do not match is refused with 422 PBP-0100. Neither reaches the source. **Segments differ.** Every member of the answer is always present; a member the segment does not report is null. A bank slip reports payability, the face value, fine, interest, discount, the due and limit dates, the beneficiary and the receiving bank. A utilities bill reports the assignor, its segment, the state, the payment window and a settlement date, which is not a due date. A bank slip the source does not know is 404 PBP-0110; a utilities line the source does not know is refused with 422 PBP-0111. **Permission.** The operation requires `payments/create`, the same permission as initiating a payment: consulting is the first step of paying. **Isolation.** The tenant and the provider credential come from the token, never from the request. The `X-Organization-Id` header is required and validated in form (a canonical UUID); it does not scope the consult, which reads no stored data of any organization. operationId: consultBill parameters: - description: "Midaz organization of the caller. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. The organization is validated and does not scope the consult: the tenant and the provider credential come from the token." in: header name: X-Organization-Id schema: description: "Midaz organization of the caller. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. The organization is validated and does not scope the consult: the tenant and the provider credential come from the token." type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ConsultBillRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ConsultBillResponse" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The request is structurally invalid. PBP-0001 covers every schema refusal: the line not 47 digits, nor 48 digits starting with 8 (a 44-digit barcode, a 47-digit line starting with 8, a letter, a space or a hyphen), an absent body, a body that is not JSON, and a member the operation does not accept. The refusal never echoes the line. PBP-0025 means the `X-Organization-Id` header was absent or not a canonical UUID." "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" application/problem+json: schema: $ref: "#/components/schemas/Detail" 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: "PBP-0110: the source has no bank slip for this line. Bank slips only: a utilities line the source does not know is 422 PBP-0111." "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: "The line is well formed and cannot be consulted. PBP-0100: its check digits do not match. PBP-0111: the source refused the line with a reason of its own, whose code travels in the `providerCode` extension member when the source named one; for a utilities bill this includes a line the source does not know. PBP-0017: the tenant has no connection to the payment provider." "429": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: |- PBP-0112: the consult rate limit for this caller was exceeded. The count is keyed by `(tenantId, sub)` of the validated token: one client never consumes another client's budget, and one operator never consumes another operator's budget within the same client. A token without `sub` is refused with 401 PBP-0003 and counts nothing; the count never falls back to the IP address. Every consult that passes authentication counts, including one the schema then refuses. Initial limit: 100 consults per 60 s per key. ⚠️ The counter lives in process, so the ceiling is per replica: with N replicas the effective ceiling is N × the limit. It is a barrier against enumeration, not a guaranteed global quota. Payments by the same client are not affected by this limit. headers: Retry-After: description: "Seconds to wait before retrying: the time left in the limiter's window for this key, a whole number of at least 1." schema: minimum: 1 type: integer X-RateLimit-Limit: description: The limit of the current window for the `(tenantId, sub)` key. schema: minimum: 0 type: integer X-RateLimit-Remaining: description: Consults left in the current window. schema: minimum: 0 type: integer X-RateLimit-Reset: description: Seconds until the current window resets, a whole number of at least 1. schema: minimum: 1 type: integer "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error "502": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "PBP-0113: the source answered the consult in a way that cannot be acted on. Retrying the same line is unlikely to help." "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "PBP-0114: the bill source is temporarily unavailable — it did not answer, the consult's protection against a failing source is open, payments to the provider are suspended, the provider is limiting requests, or the tenant's provider credential cannot be used. The request may be retried; when the answer carries `Retry-After`, wait that long first." headers: Retry-After: description: Seconds to wait before retrying, a whole number of at least 1. Present when the provider limited the request or payments to it are suspended; absent when the source named no wait. schema: minimum: 1 type: integer security: - BearerAuth: [] summary: Consult a bill by digitable line tags: - Payments x-mint: href: /pt/reference/interfaces/payments-btg/consult-a-bill-by-digitable-line /v1/payments/darf: post: description: Initiates a DARF (federal tax) payment with specific tax fields. operationId: initiateDARFPayment parameters: - description: "Midaz organization the account and the ledger entry 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 the ledger entry 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, or with a value that is not a UUID, 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, or with a value that is not a UUID, is refused with 400 PBP-0012." type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/InitiateDARFPaymentRequest" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/InitiateDARFPaymentResponse" description: "Created. The payment provider acknowledged the DARF payment: it is in status CREATED and carries the provider's `providerId`. Its outcome arrives later; follow it with GET /v1/payments/{id}. A request under an `Idempotency-Key` that already names a DARF payment the provider acknowledged is answered 201 too, with that payment as it stands, in whatever status it has reached. Compare the 202, where the outcome at the provider is not known." "202": content: application/json: schema: $ref: "#/components/schemas/InitiateDARFPaymentResponse" description: "Accepted. The DARF payment was created, its funds are reserved, and the instruction was sent to the payment provider, but its outcome is NOT known: the provider did not answer in time, failed on its side, dropped the connection or answered in a way that could not be read, or this service could not record the provider's acknowledgement. The payment is in status UNCONFIRMED and carries no `providerId`. ⚠️ Do NOT send it again under a new `Idempotency-Key`: the provider may have it, and a second request can pay the tax twice. Its funds stay reserved until the payment provider's outcome arrives. Read its current state with GET /v1/payments/{id}. A resend under the SAME `Idempotency-Key` is safe: for up to 48 hours it answers this same 202, even after the payment has resolved, so read the payment by id for its current status. A request under a key that already names a DARF payment still UNCONFIRMED is answered 202 too." "400": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Bad Request. Branch on `code`. PBP-0001 means the request is malformed: the body is missing, is not JSON, fails schema validation, contains a member this operation does not accept, has a date or amount that cannot be parsed, or has markup in a text field. Each unexpected member is named in errors[] by its `location`; `personType`, `taxId` and `name` are not accepted. PBP-0200 means a DARF rule was not met: `type` other than S or N, an amount out of range or with more than two decimal places, or `treasuryRevenueCode` or `history` longer than allowed. PBP-0025 means the `X-Organization-Id` header is missing or is not a canonical UUID. PBP-0026 means the `ledgerId` member is missing, blank or not a canonical UUID. PBP-0012 means the `Idempotency-Key` header is missing or is not a UUID. PBP-0204 means the account named in `midazAccountId` has no registered owner, so the taxpayer of the DARF cannot be established. The taxpayer is always taken from the account's registration, so no request field resolves this: register the account's owner, or use an account that has one, and send the request again. In every case no payment was created and nothing was sent to the payment provider." "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 "409": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" 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." "422": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Unprocessable Entity. The request was valid but could not be carried out; branch on `code`. PBP-0300 means the funding account does not have enough available balance, and PBP-0302 means the funds reservation would take the funding account past its overdraft limit. Both are answered BEFORE the payment provider is instructed: the payment is recorded as failed, and nothing was sent to the payment provider or paid. The Idempotency-Key is released, so the request can be sent again, under the same or a new key, once the balance allows. A refusal for the ledger's accounting configuration is not answered with this status: it is PBP-0301 on the 503. PBP-0014 means the payment provider refused the DARF instruction on the only attempt made. Nothing was paid: the payment is recorded as failed and its funds reservation is cancelled. The Idempotency-Key is consumed: a resend under the same key answers this same 422 again and runs nothing. Correct the cause and send the request under a new Idempotency-Key. PBP-0013 means this Idempotency-Key was already used for a different request: another body, or a DARF with another revenue code, reference date, type or amounts, funding account, `X-Organization-Id` or `ledgerId`. Nothing was done. Send this payment under a key of its own. PBP-0202 means account validation is not available on this deployment; no payment was created. Contact support. PBP-0017 means the payment provider account this payment would be paid from could not be established. No payment was created and nothing was sent to the payment provider. Sending the request again does not resolve it. Contact support. PBP-0205 means the registration of the funding account's owner is inconsistent — a tax id that is not a valid CPF or CNPJ, one that contradicts the registered person type, or more than one registered owner — so the taxpayer of the DARF cannot be established. No payment was created. The taxpayer is always taken from the account's registration, not from the request, so correct the owner's registration before sending the request again. PBP-0207 means the registered owner's name is longer than the 80 bytes a DARF accepts (accented characters use more than one byte). The name is never shortened. No payment was created; shorten the registered owner's name, or use a funding account whose owner's name fits, and send the request again. This limit applies only to DARF payments. PBP-0208 means the tax document of the funding account's registered owner is not numeric, for example an alphanumeric CNPJ. The registration is valid, but the payment provider accepts only a numeric CPF or CNPJ. No payment was created; use a funding account whose registered owner has a numeric document. POST /v1/payments answers the same code for the same account." "500": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Internal Server Error. PBP-0002 is an unexpected failure with no classified answer, and it answers at two moments. BEFORE CREATION, a failure this service could not classify before it recorded the payment (for example while it checked whether the request already created a payment, prepared the call to the payment provider or built the payment) leaves nothing behind: the Idempotency-Key is released, and the SAME request under the SAME key runs again. AFTER CREATION, every failure to record the payment before the payment provider is instructed is answered 503 PBP-0301, and every outcome after the instruction is 201, 202, 422 or 503 PBP-0211, so a 500 there is a defect, not a branch to code against: the payment may or may not exist, and in the rare case the failure followed the instruction it may have been sent. The response does not say which moment it was. Before sending the request under a NEW Idempotency-Key, look for it: GET /v1/payments with `idempotencyKey` set to the key this request was sent under. A resend under the SAME key answers 409 PBP-0007 while the first request still holds the key; after that it either replays this 500, with a message that the original may have taken effect, or, when nothing was stored, runs the request again and answers from the payment it recorded, if any. Once the request has been sent under a new Idempotency-Key, never resend it under the old one: if this service could not store this answer, the old key runs the request again after five minutes, and could pay alongside the new one." "503": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Service Unavailable. Branch on `code`: the `detail` of a 5xx response is a fixed generic text. PBP-0008 means the tenant's storage could not be resolved. The request was not processed and no payment was created; wait and send the same request again with the same Idempotency-Key. PBP-0211 means the payment provider did not receive the payment instruction: it was closed for the day (outside the hours it accepts), unreachable on every attempt, or calls to it were suspended after repeated failures; it refused the call itself on the only attempt made — not authorized, forbidden, or not received in full in time; or this API could not authenticate with the provider or set up the call to it at all. Nothing was paid. The payment was created, is recorded as failed, and its funds reservation is cancelled shortly after this answer. The Idempotency-Key is consumed: a resend under the same key answers this same 503 again and runs nothing. To try again, send the request under a new Idempotency-Key, which is safe because nothing was paid; until the first reservation is released it may be answered PBP-0300. While the provider is closed, every attempt answers this code until it reopens, and while it refuses these calls, or they cannot be authenticated, every attempt answers it until an operator restores access. PBP-0015 means calls to the payment provider were suspended after repeated failures while the DARF was being prepared, before any payment is created: nothing was created or sent, the Idempotency-Key is released, and the same request can be sent again under the same key once the provider recovers. PBP-0015 is never answered after the payment instruction is sent: an instruction whose outcome is not known is answered 202 with the payment in status UNCONFIRMED, and one the payment provider did not receive is answered PBP-0211. PBP-0206 means the registered owner of the funding account, who is the taxpayer of the DARF, could not be established because the records that identify it could not be reached or are not available on this deployment. No payment was created and the payment provider was not called. Wait and send the request again; if a resend under the same Idempotency-Key is answered 500 PBP-0002, send it under a new key. If the request under a new key answers this code again, contact support. PBP-0301 means the funds could not be reserved in the ledger, or the payment could not be recorded before the payment provider was instructed. On this operation it is always answered BEFORE the payment provider is instructed: nothing was sent to the payment provider and nothing was paid. It is answered at two moments. Before the payment is created, nothing exists: where accounting routes are enabled, the tenant's accounting routes could not be read or are incomplete or inconsistent; and on an instance that resolves a credential per tenant, that credential could not be resolved, or was rejected, while the funding account was being checked. The Idempotency-Key was released, so the same request under the same key runs again, and succeeds once the cause is repaired. After the payment is created, it may exist in status UNCONFIRMED and was not sent. That payment is never sent to the payment provider: the reconciliation marks it FAILED and releases any funds reserved for it. Rarely, that needs an operator; contact support in those cases. This answer is stored, so a resend under the same key answers this same 503 again and runs nothing. The response does not say which of the two moments it was: both carry the same code and status, and no payment id. The remedy is the same: once the cause is repaired, send the request under a NEW Idempotency-Key, which cannot pay twice because a payment answered with this code is never instructed. Once the request has been sent under a new Idempotency-Key, never resend it under the old one: if this service could not store this answer, the old key runs the request again after five minutes, and could pay alongside the new one. Until the first payment's reservation is released, the new request may be answered PBP-0300. To account for a payment the first request may have created, call GET /v1/payments with `idempotencyKey` set to the Idempotency-Key the request was sent under. A payment found there reads UNCONFIRMED until it ends FAILED (follow it with GET /v1/payments/{id}), and it is never paid." security: - BearerAuth: [] summary: Initiate a DARF payment tags: - Payments x-mint: href: /pt/reference/interfaces/payments-btg/initiate-darf-payment /v1/payments/{id}: get: description: Retrieves a single payment by its ID with full detail, including the DARF fields when applicable. operationId: getPayment parameters: - description: "Midaz organization the payment belongs to. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. A payment of another organization is answered 404, exactly as one that does not exist." in: header name: X-Organization-Id schema: description: "Midaz organization the payment belongs to. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. A payment of another organization is answered 404, exactly as one that does not exist." type: string - description: Payment identifier (UUID). in: path name: id required: true schema: description: Payment identifier (UUID). examples: - 123e4567-e89b-12d3-a456-426614174000 format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/GetPaymentResponse" 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/problem+json: schema: $ref: "#/components/schemas/Detail" application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error '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: [] summary: Get payment by ID tags: - Payments x-mint: href: /pt/reference/interfaces/payments-btg/get-payment /v1/payments/{id}/cancel: post: description: Payment cancellation is not available. Every request that passes authentication and request validation is answered with 501 Not Implemented and error code PBP-0203, including a request for a payment that is already canceled. No cancellation is performed and no payment is changed. A request refused before that keeps its own 4xx status and error code. operationId: cancelPayment 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, or with a value that is not a UUID, 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, or with a value that is not a UUID, is refused with 400 PBP-0012." type: string - description: Payment identifier (UUID). in: path name: id required: true schema: description: Payment identifier (UUID). examples: - 123e4567-e89b-12d3-a456-426614174000 format: uuid type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CancelPaymentRequest" required: true responses: "400": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" 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." "409": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" 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." "422": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" 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 "501": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Implemented. Payment cancellation is not available. The response body carries `code` PBP-0203 and a `detail` naming the unavailable capability. No cancellation is performed and the payment is not changed. Retrying does not resolve it. "503": content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable security: - BearerAuth: [] summary: Cancel a payment tags: - Payments x-mint: href: /pt/reference/interfaces/payments-btg/cancel-payment /v1/webhooks/btg: post: description: "Accepts a settlement event pushed by the payment provider, persists it verbatim and returns 202 only after that persistence succeeds. This route is served only by a single-tenant deployment; a multi-tenant deployment serves the per-connection route at this path plus a connection token instead, and this document advertises both because it is generated without a deployment mode. If the deployment's storage is unavailable the event is not persisted and the response is 503 (retryable) instead of 202. Authentication is an HMAC-SHA256 signature over the raw request body, sent as lowercase hex in x-webhook-baas-signature and computed with a secret agreed with the provider, not the platform identity used by the rest of this API. The body is the provider envelope: pactualId, entity and status are required, clientRequestId and createTimestamp are optional, and any further member is accepted and stored as sent. Member names are matched without regard to case. The x-webhook-baas-entity and x-webhook-baas-event headers are optional copies of entity and status; where a header disagrees with the body the body is authoritative, because only the body is signed. The x-webhook-baas-notifyid header identifies the logical notification and, when sent, is what this endpoint deduplicates on; a delivery without it is still accepted and deduplicated on a key derived from pactualId, entity, status and createTimestamp. The x-webhook-baas-deliveryid header names one attempt to deliver that notification rather than the notification itself; it is optional, it decides nothing, and it is recorded only in this endpoint's logs, so that a delivery can be matched against the provider's own list of failed attempts. A delivery whose status names a provider TRANSPORT event rather than a business one — PING, which the provider's own webhook test emits and which belongs to no entity's event catalogue — is the single exception to all of the above: it is answered 202 without being deduplicated and without being persisted." operationId: receiveProviderWebhook parameters: - description: "HMAC-SHA256 of the raw request body, lowercase hex. WHICH key signs it depends on the route: the unparameterised route verifies against the deployment-wide provider secret, while the per-connection route verifies against the signing key issued for that connection_token and nothing else — a delivery signed with the deployment-wide secret is refused there. It is verified by a per-operation middleware that runs before any schema check, so a request that omits it, or carries a value that does not match the body, is refused with 401 PBP-0500 and never with a schema error." in: header name: x-webhook-baas-signature required: true schema: description: "HMAC-SHA256 of the raw request body, lowercase hex. WHICH key signs it depends on the route: the unparameterised route verifies against the deployment-wide provider secret, while the per-connection route verifies against the signing key issued for that connection_token and nothing else — a delivery signed with the deployment-wide secret is refused there. It is verified by a per-operation middleware that runs before any schema check, so a request that omits it, or carries a value that does not match the body, is refused with 401 PBP-0500 and never with a schema error." type: string - description: Provider entity name, repeating the body's entity member. Cross-checked against it; the body decides, because only the body is under the signature. in: header name: x-webhook-baas-entity schema: description: Provider entity name, repeating the body's entity member. Cross-checked against it; the body decides, because only the body is under the signature. type: string - description: Provider event name, which is the same value as the body's status member. Cross-checked against it; the body decides. in: header name: x-webhook-baas-event schema: description: Provider event name, which is the same value as the body's status member. Cross-checked against it; the body decides. type: string - description: Provider identifier of the LOGICAL notification, as opposed to one delivery attempt of it. When present it becomes this delivery's deduplication key; when absent the key is derived from the envelope instead, and the delivery is still accepted. in: header name: x-webhook-baas-notifyid schema: description: Provider identifier of the LOGICAL notification, as opposed to one delivery attempt of it. When present it becomes this delivery's deduplication key; when absent the key is derived from the envelope instead, and the delivery is still accepted. type: string - description: "Provider identifier of ONE ATTEMPT to deliver a notification, as opposed to the notification itself. It decides nothing: it is never deduplicated on and no column holds it, because an attempt identifier is fresh on every retry. It is recorded in this endpoint's logs so a delivery can be matched against the provider's own list of failed attempts. A delivery without it is still accepted." in: header name: x-webhook-baas-deliveryid schema: description: "Provider identifier of ONE ATTEMPT to deliver a notification, as opposed to the notification itself. It decides nothing: it is never deduplicated on and no column holds it, because an attempt identifier is fresh on every retry. It is recorded in this endpoint's logs so a delivery can be matched against the provider's own list of failed attempts. A delivery without it is still accepted." type: string - description: Optional provider correlation identifier. Persisted with the event when present. in: header name: X-Correlation-Id schema: description: Optional provider correlation identifier. Persisted with the event when present. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ProviderWebhookPayload" required: true responses: "202": description: Accepted "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "413": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Request Entity Too Large "415": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unsupported Media Type "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 summary: Receive a provider webhook tags: - Settlement x-internal: true x-mint: href: /pt/reference/interfaces/payments-btg/receive-provider-webhook /v1/webhooks/btg/{connection_token}: post: description: "Accepts a settlement event pushed by the payment provider on a per-tenant webhook connection, persists it verbatim and returns 202 only after that persistence succeeds. This route is served only by a multi-tenant deployment; a single-tenant deployment serves the unparameterised provider webhook route instead, and this document advertises both because it is generated without a deployment mode. The connection_token path segment names a webhook connection this service issued when a tenant connected the provider: it selects the tenant the delivery belongs to, the storage it is written to, and the key its signature is verified under. Authentication is an HMAC-SHA256 signature over the raw request body, sent as lowercase hex in x-webhook-baas-signature and computed with the secret agreed for that one connection, not a platform identity and not a key shared between tenants. A connection_token that names no connection, a connection that has been revoked, and a signature that does not match the body are refused with the same 401 and cannot be told apart. If the tenant's storage is unavailable the event is not persisted and the response is 503 (retryable) instead of 202. The body is the provider envelope: pactualId, entity and status are required, clientRequestId and createTimestamp are optional, and any further member is accepted and stored as sent. Member names are matched without regard to case. The x-webhook-baas-entity and x-webhook-baas-event headers are optional copies of entity and status; where a header disagrees with the body the body is authoritative, because only the body is signed. The x-webhook-baas-notifyid header identifies the logical notification and, when sent, is what this endpoint deduplicates on; a delivery without it is still accepted and deduplicated on a key derived from pactualId, entity, status and createTimestamp. The x-webhook-baas-deliveryid header names one attempt to deliver that notification rather than the notification itself; it is optional, it decides nothing, and it is recorded only in this endpoint's logs, so that a delivery can be matched against the provider's own list of failed attempts. A delivery whose status names a provider TRANSPORT event rather than a business one — PING, which the provider's own webhook test emits and which belongs to no entity's event catalogue — is the single exception to all of the above: it is answered 202 without being deduplicated and without being persisted." operationId: receiveProviderWebhookByConnection parameters: - description: "HMAC-SHA256 of the raw request body, lowercase hex. WHICH key signs it depends on the route: the unparameterised route verifies against the deployment-wide provider secret, while the per-connection route verifies against the signing key issued for that connection_token and nothing else — a delivery signed with the deployment-wide secret is refused there. It is verified by a per-operation middleware that runs before any schema check, so a request that omits it, or carries a value that does not match the body, is refused with 401 PBP-0500 and never with a schema error." in: header name: x-webhook-baas-signature required: true schema: description: "HMAC-SHA256 of the raw request body, lowercase hex. WHICH key signs it depends on the route: the unparameterised route verifies against the deployment-wide provider secret, while the per-connection route verifies against the signing key issued for that connection_token and nothing else — a delivery signed with the deployment-wide secret is refused there. It is verified by a per-operation middleware that runs before any schema check, so a request that omits it, or carries a value that does not match the body, is refused with 401 PBP-0500 and never with a schema error." type: string - description: Provider entity name, repeating the body's entity member. Cross-checked against it; the body decides, because only the body is under the signature. in: header name: x-webhook-baas-entity schema: description: Provider entity name, repeating the body's entity member. Cross-checked against it; the body decides, because only the body is under the signature. type: string - description: Provider event name, which is the same value as the body's status member. Cross-checked against it; the body decides. in: header name: x-webhook-baas-event schema: description: Provider event name, which is the same value as the body's status member. Cross-checked against it; the body decides. type: string - description: Provider identifier of the LOGICAL notification, as opposed to one delivery attempt of it. When present it becomes this delivery's deduplication key; when absent the key is derived from the envelope instead, and the delivery is still accepted. in: header name: x-webhook-baas-notifyid schema: description: Provider identifier of the LOGICAL notification, as opposed to one delivery attempt of it. When present it becomes this delivery's deduplication key; when absent the key is derived from the envelope instead, and the delivery is still accepted. type: string - description: "Provider identifier of ONE ATTEMPT to deliver a notification, as opposed to the notification itself. It decides nothing: it is never deduplicated on and no column holds it, because an attempt identifier is fresh on every retry. It is recorded in this endpoint's logs so a delivery can be matched against the provider's own list of failed attempts. A delivery without it is still accepted." in: header name: x-webhook-baas-deliveryid schema: description: "Provider identifier of ONE ATTEMPT to deliver a notification, as opposed to the notification itself. It decides nothing: it is never deduplicated on and no column holds it, because an attempt identifier is fresh on every retry. It is recorded in this endpoint's logs so a delivery can be matched against the provider's own list of failed attempts. A delivery without it is still accepted." type: string - description: Optional provider correlation identifier. Persisted with the event when present. in: header name: X-Correlation-Id schema: description: Optional provider correlation identifier. Persisted with the event when present. type: string - description: Opaque token identifying the webhook connection this service issued for one tenant and one provider. It selects the tenant the delivery belongs to, the storage it is written to, and the secret its body signature is verified under. A token that names no connection and a token whose connection has been revoked are refused identically, and neither is echoed back. in: path name: connection_token required: true schema: description: Opaque token identifying the webhook connection this service issued for one tenant and one provider. It selects the tenant the delivery belongs to, the storage it is written to, and the secret its body signature is verified under. A token that names no connection and a token whose connection has been revoked are refused identically, and neither is echoed back. type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ProviderWebhookPayload" required: true responses: "202": description: Accepted "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unauthorized "413": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Request Entity Too Large "415": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unsupported Media Type "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 summary: Receive a provider webhook on a tenant connection tags: - Settlement x-internal: true x-mint: href: /pt/reference/interfaces/payments-btg/receive-provider-webhook-by-connection servers: - url: https://api.example.com description: Replace the example host with the URL provided during environment onboarding. 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