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 AdoptBoletoEmissionRequestBody: additionalProperties: false properties: providerId: description: The provider's id of the title. examples: - 8c2f0b5e-1d3a-4c7e-9f6b-2a4d5e6f7a8b maxLength: 64 type: string required: - providerId type: object BatchInvalidItemsProblem: allOf: - $ref: "#/components/schemas/Detail" - properties: code: enum: - PBP-0123 type: string itemErrors: description: The problems of the items, by ascending position and, within an item, in the order of its members. items: $ref: "#/components/schemas/BatchItemError" minItems: 1 type: array required: - code - itemErrors type: object description: "422 PBP-0123: one or more items are invalid. The whole batch is refused, and nothing is recorded or sent for issuance. Every problem of every item comes at once, in two forms: errors[], the service's form for generic clients, with location body.items[]. and message; and itemErrors[], an extension member with the same problems, each with position, field and the item's code, to mark the member and translate the problem without reading the message. A refusal that holds for the whole batch (account, ledger, holder registration) prevails and comes under its own code, without the list." BatchItemError: additionalProperties: false properties: code: description: "Code of the item's problem. An open list; today: PBP-0001 (form, size, presence, document, amount, due date, address), PBP-0006 (type not supported, HYBRID included, with the reason in message; charges), PBP-0119 (payer is the final beneficiary) and PBP-0125 (ourNumber repeated in the batch). It is the code the single boleto or the installment series gives the same condition, except the last, which is the batch's own." examples: - PBP-0125 pattern: ^PBP-[0-9]{4}$ type: string field: description: Path of the member inside the item, in dot notation (payer.address.zipCode, ourNumber, discount.limitDate). examples: - payer.address.zipCode type: string message: description: Human-readable message, in English like every message of the service. A client translates by code, never by this text. examples: - type HYBRID is not supported for batch issuance type: string position: description: Position of the item in the request, from 0. examples: - 1 format: int64 maximum: 24 minimum: 0 type: integer required: - position - field - code - message type: object BatchSizeProblem: allOf: - $ref: "#/components/schemas/Detail" - properties: code: enum: - PBP-0122 type: string maxItems: description: The most items a batch holds. enum: - 25 format: int64 type: integer receivedItems: description: The number of items sent. examples: - 26 format: int64 minimum: 0 type: integer required: - code - maxItems - receivedItems type: object description: "422 PBP-0122: the number of items is outside 1 to 25." BoletoBatchCounts: additionalProperties: false properties: canceled: description: Items CANCELED. examples: - 1 format: int64 minimum: 0 type: integer failed: description: Items FAILED. examples: - 1 format: int64 minimum: 0 type: integer inactivated: description: "Items INACTIVATED: written off." examples: - 0 format: int64 minimum: 0 type: integer overdue: description: "Items still processing past the service's deadline (overdue: true). Never more than processing." examples: - 0 format: int64 minimum: 0 type: integer processing: description: Items PENDING, still being issued. examples: - 1 format: int64 minimum: 0 type: integer registered: description: "Items CREATED: registered and available for payment." examples: - 2 format: int64 minimum: 0 type: integer requested: description: "Number of items requested: the size of the batch." examples: - 5 format: int64 maximum: 25 minimum: 1 type: integer settled: description: "Items SETTLED: paid." examples: - 0 format: int64 minimum: 0 type: integer required: - requested - processing - registered - settled - canceled - inactivated - failed - overdue type: object BoletoBatchItemResponse: additionalProperties: false properties: amount: description: Requested amount, as a decimal string with two decimal places. examples: - "150.00" type: string boletoId: description: "Identifier of the boleto this item produced: the id GET /v1/boletos/{id}, the PDF and the boleto cancellation take." format: uuid type: string cancelable: description: "Same meaning as cancelable on GET /v1/boletos/{id}: true only for a CREATED item that carries a providerId. Always present." type: boolean discount: $ref: "#/components/schemas/DiscountResponse" dueDate: description: Requested due date. examples: - "2030-01-15" format: date type: string errorCode: description: Product code of the failure. Present only with status FAILED. The list is open; today PBP-0108 when the requested ourNumber is already in use, and PBP-0014 when the item was refused. examples: - PBP-0108 pattern: ^PBP-[0-9]{4}$ type: string errorMessage: description: Readable reason of the failure, present only with status FAILED. Written by this service; after provider reported ERROR it may carry, in parentheses, the error code the issuing bank sent. Translate it by errorCode. examples: - no title was issued for this emission maxLength: 500 type: string fine: $ref: "#/components/schemas/FineResponse" instructions: description: Instructions requested for the item. Absent when the item carried none. type: string interest: $ref: "#/components/schemas/InterestResponse" ourNumber: description: Bank-side identification of the item's boleto (nosso numero), read from the barcode with leading zeros, as GET /v1/boletos/{id} answers it. Absent while the provider has not produced the boleto. examples: - "00000000152" type: string ourNumberDigit: description: Check digit of ourNumber, computed by the bank, as GET /v1/boletos/{id} answers it. Absent whenever the provider did not return it. examples: - "3" type: string ourNumberHolderBoletoId: description: Boleto that held the requested ourNumber when the item collided with it on creation (errorCode PBP-0108). It may be an earlier issuance of the same charge, so read that boleto before requesting another number. Absent in every other case. type: string overdue: description: "Whether the item is PENDING past the service's deadline. Derived on every read. It is not a failure: the item is still being processed. Always false outside PENDING." type: boolean payer: $ref: "#/components/schemas/PayerResponse" position: description: "Position of the item in the request, from 0: its index in the request's items and in body.items[] of a refusal. Add 1 to show it as item n." examples: - 0 format: int64 maximum: 24 minimum: 0 type: integer providerId: description: Identifier the payment provider assigned to the item's boleto. Present only once the item is bound to a live boleto at the provider; absent while it is queued or being sent, and on FAILED. type: string requestedOurNumber: description: "ourNumber requested for the item, in canonical form: no hyphen and no check digit. Absent when the item requested none, and on an item that failed with PBP-0108 on creation. Distinct from ourNumber, which reports the boleto." examples: - "00000000152" type: string status: description: Status of the item's boleto, the same GET /v1/boletos/{id} answers. PENDING covers an item queued, sent or still being processed; CREATED is a registered item with barcode and digitable line. An item becomes FAILED only once it is certain that no boleto was registered for it. enum: - PENDING - CREATED - SETTLED - CANCELED - INACTIVATED - FAILED examples: - CREATED type: string required: - position - boletoId - status - overdue - cancelable - amount - dueDate - payer type: object BoletoBatchOutcome: description: "Issuance outcome of the batch, derived from its items on every read. CREATED: some item is still PENDING. COMPLETED: no item is PENDING and none is FAILED. PARTIAL_FAILURE: no item is PENDING and some, not all, are FAILED; those carry errorCode and errorMessage. FAILED: every item is FAILED. Only issuance moves it: payment, cancellation and write-off do not, and it never moves back to CREATED." enum: - CREATED - COMPLETED - PARTIAL_FAILURE - FAILED type: string BoletoBatchResponse: additionalProperties: false properties: batchId: description: Batch identifier. examples: - 0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b format: uuid type: string closed: description: "Whether every item is SETTLED, CANCELED, INACTIVATED or FAILED: nothing else will happen to the batch, payment included. Always present. It moves back to false when a cancellation is refused and the item returns to CREATED. True implies finished." type: boolean counts: $ref: "#/components/schemas/BoletoBatchCounts" createdAt: description: When the batch was created, RFC 3339 in UTC. examples: - "2026-10-14T19:34:00Z" format: date-time type: string finished: description: "Whether no item is PENDING: the issuance of the batch is over. Always present. It never moves back to false; an overdue item keeps it false." type: boolean items: description: "Every item, in ascending position. Never paginated: a batch holds at most 25 items." items: $ref: "#/components/schemas/BoletoBatchItemResponse" type: - array - "null" ledgerId: description: Ledger of the batch and of each item. examples: - 7c1e5b9a-3d2f-4a6b-8e0c-1f2a3b4c5d6e format: uuid type: string midazAccountId: description: Collection account of the batch and of each item. examples: - 3f9a2c1e-5b7d-4e8f-9a0b-1c2d3e4f5a6b type: string organizationId: description: "Organization the batch was recorded with: always the organization of the X-Organization-Id header." examples: - 0f9d6c2a-1b3e-4f5a-8c7d-6e5f4a3b2c1d format: uuid type: string status: $ref: "#/components/schemas/BoletoBatchOutcome" required: - items - batchId - organizationId - ledgerId - midazAccountId - status - closed - finished - counts - createdAt type: object BoletoBatchSummary: additionalProperties: false properties: batchId: description: Batch identifier. examples: - 0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b format: uuid type: string closed: description: "Whether every item is SETTLED, CANCELED, INACTIVATED or FAILED: nothing else will happen to the batch, payment included. Always present. It moves back to false when a cancellation is refused and the item returns to CREATED. True implies finished." type: boolean counts: $ref: "#/components/schemas/BoletoBatchCounts" createdAt: description: When the batch was created, RFC 3339 in UTC. examples: - "2026-10-14T19:34:00Z" format: date-time type: string finished: description: "Whether no item is PENDING: the issuance of the batch is over. Always present. It never moves back to false; an overdue item keeps it false." type: boolean ledgerId: description: Ledger of the batch and of each item. examples: - 7c1e5b9a-3d2f-4a6b-8e0c-1f2a3b4c5d6e format: uuid type: string midazAccountId: description: Collection account of the batch and of each item. examples: - 3f9a2c1e-5b7d-4e8f-9a0b-1c2d3e4f5a6b type: string organizationId: description: "Organization the batch was recorded with: always the organization of the X-Organization-Id header." examples: - 0f9d6c2a-1b3e-4f5a-8c7d-6e5f4a3b2c1d format: uuid type: string status: $ref: "#/components/schemas/BoletoBatchOutcome" required: - batchId - organizationId - ledgerId - midazAccountId - status - closed - finished - counts - createdAt 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 CancelBoletoBatchItemResult: additionalProperties: false properties: boletoId: description: Identifier of the item's boleto. format: uuid type: string errorCode: description: Product code of the outcome. Present with NOT_CANCELABLE (PBP-0103) and with CANCEL_FAILED. examples: - PBP-0103 pattern: ^PBP-[0-9]{4}$ type: string errorMessage: description: Readable reason, present with errorCode. Translate it by errorCode. examples: - boleto is SETTLED and cannot be canceled type: string position: description: Position of the item in the request, from 0. examples: - 0 format: int64 maximum: 24 minimum: 0 type: integer result: description: "Outcome of the request for the item. CANCELED: this request canceled it. NOT_CANCELABLE: the item could not be canceled, and status says why (SETTLED paid, CANCELED already canceled, INACTIVATED written off, FAILED failed, PENDING not cancelable yet); errorCode is PBP-0103, and it is not an error. CANCEL_FAILED: the cancellation was attempted and refused, with the code and message the single boleto cancellation gives; asking again retries only these and the items that became cancelable." enum: - CANCELED - NOT_CANCELABLE - CANCEL_FAILED examples: - CANCELED type: string status: description: Status of the item's boleto after the attempt. enum: - PENDING - CREATED - SETTLED - CANCELED - INACTIVATED - FAILED examples: - CANCELED type: string required: - position - boletoId - result - status type: object CancelBoletoBatchRequest: additionalProperties: false properties: reason: description: "Reason for the cancellation, recorded on every item canceled as its cancellationReason. Required: absent, blank once trimmed or longer than 500 characters is refused with 400 PBP-0001, with the same messages as POST /v1/boletos/{id}/cancel." examples: - Cobrança emitida em duplicidade type: string required: - reason type: object CancelBoletoBatchResponse: additionalProperties: false properties: batchId: description: Batch identifier. examples: - 0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b format: uuid type: string items: description: One result per item of the batch, in ascending position. items: $ref: "#/components/schemas/CancelBoletoBatchItemResult" type: - array - "null" required: - batchId - items 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 ConfigurePixConfigRequest: additionalProperties: false properties: pixKey: description: "Pix key of the tenant's collection account, the receiver of the Pix payment of the tenant's boletos that carry a Pix QR code. Accepted formats: random key (lowercase UUID), CPF (11 digits), CNPJ (14 digits), e-mail (lowercase, at most 77 characters) and phone (+, country code and number). A CPF or CNPJ key with invalid check digits is refused with 400 PBP-0001, and so is a CNPJ key in the alphanumeric format. A CPF or CNPJ key must be the document of the holder of the collection account, who is the Pix receiver: another document is refused with 422 PBP-0120, and nothing is written. When the holder's document cannot be read, the key is written and the check is left to the issuance of a boleto that carries a Pix QR code. A random, e-mail or phone key is not verified." examples: - f34f8ec2-a4b7-41b4-8200-b53a07e00bac maxLength: 77 pattern: ^([0-9]{11}|[0-9]{14}|[+][1-9][0-9][0-9]{1,14}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|[a-z0-9.!#$&'*+/=?^_`{|}~-]+@[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:[.][a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*)$ patternDescription: "a Pix key: a random key (lowercase UUID), a CPF (11 digits), a CNPJ (14 digits), a lowercase e-mail or a phone (+, country code and number)" type: string receiverAddress: $ref: "#/components/schemas/PixReceiverAddressRequest" description: Address of the holder of the account the key belongs to, the receiver of the Pix payment. A boleto that carries a Pix QR code requires it, and the account record does not provide it. required: - pixKey - receiverAddress type: object ConfigureWebhookRequest: additionalProperties: false properties: active: type: boolean callbackUrl: type: string enabledEvents: description: "Event types the configuration receives, any of: BOLETO_CREATED, BOLETO_SETTLED, BOLETO_CANCELED, BOLETO_CANCEL_FAILED, BOLETO_INACTIVATED, BOLETO_FAILED, BOLETO_EXCESS_PAYMENT, BOLETO_BATCH_FINISHED, PAYMENT_SETTLED, PAYMENT_REJECTED, PAYMENT_FAILED, PAYMENT_CANCELED, PAYMENT_SCHEDULED, PIX_KEY_CHANGED (the notice that the tenant's Pix key changed). A type outside this list is refused. The list holds at most 64 entries." items: type: string maxItems: 64 type: - array - "null" secret: type: string required: - callbackUrl - secret - enabledEvents type: object ConfiguredPixConfigResponse: additionalProperties: false properties: complete: description: Whether the configuration has every member a boleto that carries a Pix QR code needs from it; always true after a write, which requires them all. As on the read, it does not guarantee that an issuance is accepted. type: boolean pixKey: description: The configured Pix key. examples: - f34f8ec2-a4b7-41b4-8200-b53a07e00bac type: string updatedAt: description: When this write was recorded, in UTC. examples: - "2026-10-13T15:04:05Z" format: date-time type: string updatedBy: description: "Identifier of the authenticated principal that made this write: the subject of its access token." type: string required: - pixKey - complete - updatedAt - updatedBy type: object 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 CreateBoletoBatchItemRequest: additionalProperties: false properties: amount: description: Amount as a decimal string, at most two decimal places, greater than zero. examples: - "150.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: description: Instructions printed on the boleto, free text. Optional; the same member and rule as on POST /v1/boletos. examples: - Mensalidade de janeiro type: string interest: $ref: "#/components/schemas/InterestRequest" ourNumber: description: "Bank-side identification of the boleto (nosso numero), chosen by the payee. Optional item by item: when absent, the number is assigned at issuance. Same form as on POST /v1/boletos: surrounding spaces are removed, a hyphen is accepted only when followed by exactly one digit, which is discarded, and leading zeros do not make a different number. Two items of the batch with the same number are an item problem PBP-0125 on both, and the batch is refused. A number already held by an active boleto of the same collection account does not refuse the batch: that item alone ends FAILED with errorCode PBP-0108, and the other items go on." examples: - "00000000152" type: string payer: $ref: "#/components/schemas/PayerRequest" type: description: "Boleto type. Only TRADITIONAL is issued in a batch: HYBRID, QR_CODE or any other value is an item problem PBP-0006, reported in 422 PBP-0123 with every other problem of the batch." examples: - TRADITIONAL type: string required: - type - payer - amount - dueDate type: object CreateBoletoBatchRequest: additionalProperties: false properties: items: description: "Boletos of the batch, from 1 to 25, in the order the client wants to see them. The position of each item is its index in this list, from 0: the position of the response and the index of body.items[] in a refusal. A list outside 1 to 25 items, the empty list included, refuses the whole batch with 422 PBP-0122, which carries the limit and the number of items received; the batch is never split." items: $ref: "#/components/schemas/CreateBoletoBatchItemRequest" type: array 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 every item of the batch settles into. Its holder is the final beneficiary of every item. It must belong to the organization and the ledger, or the request is answered 404. Checked once per batch. type: string required: - midazAccountId - items 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. A HYBRID boleto takes it as a TRADITIONAL one does, from the same numbering: a number held by an active boleto of either type is in use for both. 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 values are TRADITIONAL and HYBRID; QR_CODE is refused with 422 PBP-0006. A HYBRID boleto can also be paid by Pix, and needs the tenant's Pix receiver configured at POST /v1/admin/pix-config: without it, or when its Pix key is a CPF or a CNPJ other than the issuing account holder's own document, the request is refused with 422 PBP-0120." 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" guarantor: $ref: "#/components/schemas/GuarantorResponse" description: "Final beneficiary (sacador avalista) of the boleto: the holder of the issuing account, read from that account's registration data at issuance. The request never chooses it, and every boleto this operation issues carries it." 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 pixLocation: description: "Location of the hybrid boleto's dynamic Pix QR code, as issued. For support and diagnostics: to pay, the payer uses qrCode. Only a HYBRID boleto carries it, and it is served together with qrCode, under the same rule: absent while the boleto is PENDING or FAILED, present once it is CREATED and on every later status; absent on every other type." examples: - pix.example.com/qr/v2/cobv/5d9a8e91c88c43db942d01a0ad92ffc3 type: string pixTxId: description: Identifier of the due-date Pix charge attached to a hybrid boleto. Only a HYBRID boleto carries it, and only once its issuance is confirmed; absent on every other type. examples: - 35dabf21d3b941e8a937409b8749f281 type: string providerId: description: Identifier the banking provider assigned to this boleto. Absent from the 202 response, while the provider's answer is not confirmed; read the boleto with GET /v1/boletos/{id} for its current state. type: string qrCode: description: "Pix copy-and-paste code of a HYBRID boleto's Pix charge: the payload behind its QR code, which the payer scans or pastes to pay by Pix. Served only after the provider has registered the boleto, so it is never paid into a boleto whose registration fails: absent while the boleto is PENDING or FAILED, and so from the 201 and the 202 of its creation, which answer it PENDING; present on the read once the boleto is CREATED, and on every later status. Absent on a type without a Pix charge." type: string status: type: string type: type: string required: - id - 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 ledgerId: description: "Midaz ledger the account lives in and every installment is written with. Required: absent, blank or not a canonical UUID is refused with 400 PBP-0026." type: string midazAccountId: description: Midaz account the series settles into. type: string ourNumbers: description: "Bank-side identification (nosso numero) chosen by the payee for each installment: one number per installment, in installment order, at most 36. All or none: when absent or null, the provider assigns every number, and an empty list is refused with 422 PBP-0102, as is a list of another length. Each item follows the rule of ourNumber on POST /v1/boletos: surrounding spaces are removed, a hyphen is accepted only when followed by exactly one digit, which is discarded, and any other character that is not a digit is refused; the accepted width is set by the connected provider (11 significant digits for the current one). A format or width refusal answers 400 PBP-0001 naming the item as ourNumbers[], counted from 0. Two installments with the same number, leading zeros ignored, are refused with 422 PBP-0102, and the problem carries the installments, counted from 1, as duplicateInstallmentNumbers. A number already held by an active boleto of this tenant on the same provider account refuses the whole series with 422 PBP-0108 before the provider is called, and the problem carries the installment as installmentNumber and, when the holder can be read, its id as ourNumberHolderBoletoId. Only a series with numbers depends on the provider account discovery: 422 PBP-0017 when this instance has none, 422 PBP-0014 when the provider refuses it and 503 PBP-0015 when the provider does not answer." items: type: string maxItems: 36 type: - array - "null" payer: $ref: "#/components/schemas/PayerRequest" totalAmount: description: "Series total as a decimal string. Optional: either this or installmentAmounts must be supplied." examples: - "100.00" maxLength: 32 type: string type: description: Boleto type applied to every installment. examples: - TRADITIONAL type: string required: - type - payer - installments - firstDueDate - intervalDays - midazAccountId type: object CreateInstallmentsResponse: additionalProperties: false properties: boletos: items: $ref: "#/components/schemas/InstallmentBoletoResponse" type: - array - "null" closed: description: "Whether no installment of the series can still be paid: true when every installment is SETTLED, CANCELED, INACTIVATED or FAILED. Always present. It can return to false when the provider reverts the cancellation of an installment." type: boolean installmentsCount: format: int64 type: integer ledgerId: description: Midaz ledger the installments were written with. Always present. type: string organizationId: description: Midaz organization the installments were written with. Always present, and always the organization of the X-Organization-Id header. type: string seriesId: type: string status: description: "Emission outcome of the series, derived from its installments on every read. CREATED: some installment has no emission outcome yet. COMPLETED: every installment has an outcome and none is FAILED. PARTIAL_FAILURE: every installment has an outcome and some, not all, are FAILED; those carry errorMessage. FAILED: every installment is FAILED. It does not depend on payment, cancellation or write-off, and it can move from COMPLETED to PARTIAL_FAILURE or FAILED when the provider later refuses an accepted installment: a client waiting for the final outcome reads closed." enum: - CREATED - COMPLETED - PARTIAL_FAILURE - FAILED type: string totalAmount: type: string required: - seriesId - organizationId - ledgerId - status - closed - totalAmount - installmentsCount - boletos type: object 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, greater than zero. For FIXED it is in BRL with at most 2 decimal places; for PERCENTAGE it is in percent (2.5 means 2.5%) with at most 6 decimal places. On a HYBRID boleto a PERCENTAGE amount accepts at most 2 decimal places, counted as written (2.500 carries three); more is refused with 422 PBP-0006 naming discount.amount. maxLength: 32 type: string limitDate: description: "Last date the discount applies, YYYY-MM-DD. It must be on or after the day of issuance (Brazilian calendar) and before the due date: before dueDate on a single boleto, before firstDueDate on installments. A date outside that window is refused with 422 PBP-0006." examples: - "2029-12-31" format: date type: string type: description: "Discount type, granted when the boleto is paid on or before limitDate. One of FIXED (amount in BRL, at most 2 decimal places) or PERCENTAGE (percent of the boleto's face value, at most 6 decimal places, 2 on a HYBRID boleto). Required when a discount is sent: an absent, empty or unlisted value is refused with 422 PBP-0006. A discount also requires amount and limitDate." type: string required: - amount - limitDate type: object 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 ExcessPaymentResponse: additionalProperties: false properties: amount: description: Amount received, as a decimal string with two decimal places. examples: - "10.00" type: string detectedAt: description: When the service recorded this payment as an excess payment. format: date-time type: string paidAt: description: When the payer made this payment, as the payment provider reports it. When the provider reports no instant, it is the moment the service observed the payment. format: date-time type: string paidVia: description: "Leg this payment arrived by: always the leg that did not settle the boleto." enum: - BOLETO - PIX type: string providerReference: description: "Reference of this payment at the payment provider: the end-to-end identifier of a Pix payment, or the authorization identifier of a boleto payment. Absent when the provider sent none." type: string required: - paidVia - amount - paidAt - detectedAt type: object FineRequest: additionalProperties: false properties: amount: description: Fine amount as a decimal string, greater than zero. For FIXED it is in BRL with at most 2 decimal places; for PERCENTAGE it is in percent (2.5 means 2.5%) with at most 6 decimal places. On a HYBRID boleto a PERCENTAGE amount accepts at most 2 decimal places, counted as written (2.500 carries three); more is refused with 422 PBP-0006 naming fine.amount. maxLength: 32 type: string type: description: "Fine type, charged once when the boleto is paid after its due date. One of FIXED (amount in BRL, at most 2 decimal places) or PERCENTAGE (percent of the boleto's face value, at most 6 decimal places, 2 on a HYBRID boleto). Required when a fine is sent: an absent, empty or unlisted value is refused with 422 PBP-0006." type: string required: - amount type: object 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 batchId: description: Batch the boleto was created in, as one of its items. Present only on a boleto of kind BATCH, absent on every other kind. examples: - 0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b format: uuid type: string batchPosition: description: "Position of the boleto in its batch, zero-based: the position of its item in the batch request. Present only on a boleto of kind BATCH, absent on every other kind." examples: - 3 format: int64 maximum: 24 minimum: 0 type: integer cancelable: description: "Whether cancelling this boleto would effect a cancellation at the provider. Always present. Derived from the boleto's state, not from any request field: true only for a CREATED boleto that carries a providerId. An already-canceled boleto reads false even though POST /v1/boletos/{id}/cancel answers it 200 as an idempotent replay." type: boolean canceledAt: type: string cancellationReason: type: string createdAt: type: string digitableLine: type: string discount: $ref: "#/components/schemas/DiscountResponse" dueDate: type: string errorMessage: type: string excessPayments: description: "Payments a SETTLED hybrid boleto received after it was settled, by the leg that did not settle it, when the provider attaches them to the boleto. A payment by that leg that the provider does not attach to the boleto reaches the collection account without being listed here. They are never credited: the boleto stays settled by the leg in paidVia. At most one is recorded per leg: a later payment by a leg already listed is not added. Only a hybrid boleto carries them, and the member is absent when there is none." items: $ref: "#/components/schemas/ExcessPaymentResponse" maxItems: 10 type: array failedAt: type: string fine: $ref: "#/components/schemas/FineResponse" guarantor: $ref: "#/components/schemas/GuarantorResponse" description: "Final beneficiary (sacador avalista) of the boleto: the holder of the issuing account, read from that account's registration data at issuance. It is a snapshot: a later change to the registration does not change it. Absent on boletos issued before the final beneficiary was derived." id: type: string inactivatedAt: type: string installmentLabel: type: string instructions: type: string interest: $ref: "#/components/schemas/InterestResponse" kind: description: "Issuance form of the boleto: SINGLE for a standalone boleto, INSTALLMENT for an installment of a series, BATCH for an item of a batch, which carries batchId and batchPosition." type: string ledgerId: description: Midaz ledger the boleto was written with. Always present. type: string midazAccountId: description: "Midaz account the boleto was issued for: the midazAccountId it was created with. The settlement credit of a settled boleto is posted to this account. Always present." type: string midazOperationId: type: string organizationId: description: Midaz organization the boleto was written with. Always present, and always the organization of the X-Organization-Id header. type: string ourNumber: description: "Bank-side identification of the boleto (nosso numero), as assigned by the provider and printed on the instrument. Read from the barcode and returned in the instrument's form, with leading zeros: the width is set by the connected provider (11 digits for the current one). When the payee supplied ourNumber on issuance, this field still reports the instrument and not the value supplied: if the two differ, the value here is the one printed on the boleto, and the divergence is recorded by the service. Optional: absent for boletos issued before this field existed, and absent while the provider has not produced a valid barcode. Absence means not yet known; the periodic reconciliation fills it in once the provider produces the instrument, with no action needed from the client; it is never sent as an empty string." examples: - "00000000029" type: string ourNumberDigit: description: "Check digit of ourNumber, computed by the bank and never accepted in a request. Optional: absent whenever the provider did not return it, in which case ourNumber is presented alone, with no trailing hyphen. It is absent in particular when the payee supplied ourNumber: the current provider returns the digit only for numbers it assigned itself. When present, the canonical presentation is {ourNumber}-{ourNumberDigit}." examples: - "3" type: string paidVia: description: "Leg by which the boleto was paid: BOLETO for a payment of its barcode or digitable line, PIX for a payment of a hybrid boleto's Pix QR code. Present only on a SETTLED boleto, absent on every other status. A traditional boleto is always paid by BOLETO. Set once, when the boleto settles: a later payment by the other leg does not change it and, when the provider attaches it to the boleto, is listed in excessPayments." enum: - BOLETO - PIX type: string payer: $ref: "#/components/schemas/PayerResponse" pixLocation: description: "Location of the hybrid boleto's dynamic Pix QR code, as issued. For support and diagnostics: to pay, the payer uses qrCode. Only a HYBRID boleto carries it, and it is served together with qrCode, under the same rule: absent while the boleto is PENDING or FAILED, present once it is CREATED and on every later status; absent on every other type." examples: - pix.example.com/qr/v2/cobv/5d9a8e91c88c43db942d01a0ad92ffc3 type: string pixTxId: description: Identifier of the due-date Pix charge attached to a hybrid boleto. Only a HYBRID boleto carries it, and only once its issuance is confirmed; absent on every other type. examples: - 35dabf21d3b941e8a937409b8749f281 type: string providerId: description: Identifier the payment provider assigned to this boleto. Quote it when you contact the provider about this boleto. type: string qrCode: description: "Pix copy-and-paste code of a HYBRID boleto's Pix charge: the payload behind its QR code, which the payer scans or pastes to pay by Pix. Served only after the provider has registered the boleto, so it is never paid into a boleto whose registration fails: absent while the boleto is PENDING or FAILED, and so from the 201 and the 202 of its creation, which answer it PENDING; present on the read once the boleto is CREATED, and on every later status. Absent on a type without a Pix charge." type: string seriesId: type: string settledAmount: type: string settledAt: type: string status: type: string type: type: string updatedAt: type: string required: - id - organizationId - ledgerId - midazAccountId - type - kind - status - cancelable - amount - dueDate - payer - createdAt - updatedAt type: object GetInstallmentsResponse: additionalProperties: false properties: boletos: items: $ref: "#/components/schemas/InstallmentBoletoResponse" type: - array - "null" closed: description: "Whether no installment of the series can still be paid: true when every installment is SETTLED, CANCELED, INACTIVATED or FAILED. Always present. It can return to false when the provider reverts the cancellation of an installment." type: boolean installmentsCount: format: int64 type: integer ledgerId: description: Midaz ledger the installments were written with. Always present. type: string organizationId: description: Midaz organization the installments were written with. Always present, and always the organization of the X-Organization-Id header. type: string seriesId: type: string status: description: "Emission outcome of the series, derived from its installments on every read. CREATED: some installment has no emission outcome yet. COMPLETED: every installment has an outcome and none is FAILED. PARTIAL_FAILURE: every installment has an outcome and some, not all, are FAILED; those carry errorMessage. FAILED: every installment is FAILED. It does not depend on payment, cancellation or write-off, and it can move from COMPLETED to PARTIAL_FAILURE or FAILED when the provider later refuses an accepted installment: a client waiting for the final outcome reads closed." enum: - CREATED - COMPLETED - PARTIAL_FAILURE - FAILED type: string totalAmount: type: string required: - seriesId - organizationId - ledgerId - status - closed - totalAmount - installmentsCount - boletos type: object 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" description: "Never filled for the final beneficiary: the issuing account's registration data carries no address for it. Kept so the shape of this component does not change." document: description: CPF or CNPJ of the final beneficiary, the issuing account's holder, as registered. Answered whole, never masked, wherever this component appears. type: string name: description: Name of the final beneficiary, the issuing account's holder, as registered and in full. The printed boleto may abbreviate it; this member never does. type: string required: - name - document type: object 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 errorMessage: type: string id: type: string installmentLabel: type: string installmentNumber: format: int64 type: integer ourNumber: description: "Bank-side identification of the boleto (nosso numero), as assigned by the provider and printed on the instrument. Read from the barcode and returned in the instrument's form, with leading zeros: the width is set by the connected provider (11 digits for the current one). When the payee supplied ourNumber on issuance, this field still reports the instrument and not the value supplied: if the two differ, the value here is the one printed on the boleto, and the divergence is recorded by the service. Optional: absent for boletos issued before this field existed, and absent while the provider has not produced a valid barcode. Absence means not yet known; the periodic reconciliation fills it in once the provider produces the instrument, with no action needed from the client; it is never sent as an empty string." examples: - "00000000029" type: string ourNumberDigit: description: "Check digit of ourNumber, computed by the bank and never accepted in a request. Optional: absent whenever the provider did not return it, in which case ourNumber is presented alone, with no trailing hyphen. It is absent in particular when the payee supplied ourNumber: the current provider returns the digit only for numbers it assigned itself. When present, the canonical presentation is {ourNumber}-{ourNumberDigit}." examples: - "3" type: string status: enum: - PENDING - CREATED - SETTLED - CANCELED - INACTIVATED - FAILED type: string required: - id - installmentNumber - installmentLabel - amount - dueDate - status type: object InterestRequest: additionalProperties: false properties: amount: description: Interest amount as a decimal string, greater than zero. For DAILY_FIXED it is in BRL per calendar day with at most 2 decimal places; for DAILY_PERCENTAGE and MONTHLY_PERCENTAGE it is in percent (1 means 1%) with at most 6 decimal places. On a HYBRID boleto a DAILY_PERCENTAGE or MONTHLY_PERCENTAGE amount accepts at most 2 decimal places, counted as written (1.500 carries three); more is refused with 422 PBP-0006 naming interest.amount. maxLength: 32 type: string type: description: "Interest type, accrued for each calendar day the boleto is paid late. One of DAILY_FIXED (amount in BRL per calendar day late, at most 2 decimal places), DAILY_PERCENTAGE (percent of the boleto's face value per calendar day late, at most 6 decimal places, 2 on a HYBRID boleto) or MONTHLY_PERCENTAGE (percent of the boleto's face value per month, accrued per calendar day over a 30-day month, at most 6 decimal places, 2 on a HYBRID boleto). Required when interest is sent: an absent, empty or unlisted value is refused with 422 PBP-0006." type: string required: - amount type: object InterestResponse: additionalProperties: false properties: amount: type: string type: type: string required: - type - amount type: object ListBoletoBatchesResponse: additionalProperties: false properties: items: description: Batches of the page, most recent first. items: $ref: "#/components/schemas/BoletoBatchSummary" type: - array - "null" limit: description: Items per page. examples: - 20 format: int64 type: integer page: description: Page number, one-based. examples: - 1 format: int64 type: integer total: description: Number of batches of the organization that match the filter. examples: - 42 format: int64 type: integer required: - items - page - limit - total 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 ListPixKeyHistoryResponse: additionalProperties: false properties: items: description: Changes of the page, the most recent first. A tenant with no change answers an empty list. items: $ref: "#/components/schemas/PixKeyHistoryItem" type: - array - "null" limit: description: Changes per page. examples: - 20 format: int64 type: integer page: description: Page number, one-based. examples: - 1 format: int64 type: integer total: description: Number of changes of the tenant's Pix key. A page past the last change answers an empty items list and 0. examples: - 3 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 PixConfigResponse: additionalProperties: false properties: complete: description: "True when the key and the four members of the address are present, which is what a boleto that carries a Pix QR code needs from this configuration. It does not guarantee that an issuance is accepted: the receiver's name and document are not part of this configuration, they come from the record of the collection account when a boleto is issued. A CPF or CNPJ key is checked against the document of that account's holder; the other key types are not verified." type: boolean pixKey: description: "The configured Pix key. It is not masked: it is public data, carried in the Pix QR code of every boleto that pays it." examples: - f34f8ec2-a4b7-41b4-8200-b53a07e00bac type: string receiverAddress: $ref: "#/components/schemas/PixReceiverAddressResponse" description: The receiver's address. Omitted when none is configured; a member that is not configured is omitted too. updatedAt: description: When the configuration was last written with POST /v1/admin/pix-config, in UTC. Omitted for a configuration never written with it. examples: - "2026-10-13T15:04:05Z" format: date-time type: string updatedBy: description: "Identifier of the authenticated principal that made that write: the subject of its access token. Omitted like updatedAt." type: string required: - pixKey - complete type: object PixKeyHistoryItem: additionalProperties: false properties: changedAt: description: "When the change was made, in UTC: the updatedAt POST /v1/admin/pix-config recorded for it." examples: - "2026-10-31T14:05:09Z" format: date-time type: string changedBy: description: "Identifier of the authenticated principal that made the change: the subject of its access token." type: string firstConfiguration: description: "True when the change was the tenant's first key: there was no key before it." type: boolean holderCheck: description: "How the key the change set was held to the holder of the collection account. VERIFIED: a CPF or CNPJ key checked against the document of that account's holder. UNVERIFIED: a CPF or CNPJ key written without that check. NOT_VERIFIABLE: a random, e-mail or phone key, whose owner no record tells." enum: - VERIFIED - UNVERIFIED - NOT_VERIFIABLE examples: - VERIFIED type: string id: description: Identifier of the change. It is the changeId of the PIX_KEY_CHANGED notice that announced it. examples: - 019a3b8e-6f1c-7d2e-8a4b-5c6d7e8f9a01 format: uuid type: string key: description: "The key the change set, masked by its type: a CPF key shows its middle six digits (***.456.789-**), an e-mail key its first character and its domain (j***@example.com), and a phone key its country code and its last four digits (+55*******1234). A CNPJ key and a random key are shown whole. A key of type UNKNOWN is shown as ***." examples: - "***.456.789-**" type: string keyType: description: Type of the key the change set. EVP is a random key; UNKNOWN is a key in none of the Pix key formats. enum: - CPF - CNPJ - EMAIL - PHONE - EVP - UNKNOWN examples: - CPF type: string previousKey: description: The key the change replaced, masked as key is. Omitted on the tenant's first configuration, when there was no key. examples: - f34f8ec2-a4b7-41b4-8200-b53a07e00bac type: string previousKeyType: description: Type of the key the change replaced. Omitted on the tenant's first configuration, when there was no key. enum: - CPF - CNPJ - EMAIL - PHONE - EVP - UNKNOWN examples: - EVP type: string required: - id - changedAt - changedBy - keyType - key - firstConfiguration - holderCheck type: object PixReceiverAddressRequest: additionalProperties: false properties: city: description: City. examples: - SAO PAULO minLength: 1 type: string state: description: State code (UF), two upper-case letters. enum: - AC - AL - AM - AP - BA - CE - DF - ES - GO - MA - MG - MS - MT - PA - PB - PE - PI - PR - RJ - RN - RO - RR - RS - SC - SE - SP - TO examples: - SP type: string street: description: Street and number, on one line. examples: - Avenida Paulista 1000 minLength: 1 type: string zipCode: description: "CEP with 8 digits and no hyphen: 01310-100 is refused with 400 PBP-0001." examples: - "01310100" pattern: ^[0-9]{8}$ patternDescription: a CEP of 8 digits, without hyphen type: string required: - street - city - state - zipCode type: object PixReceiverAddressResponse: additionalProperties: false properties: city: description: City. examples: - SAO PAULO type: string state: description: State code (UF). examples: - SP type: string street: description: Street and number. examples: - Avenida Paulista 1000 type: string zipCode: description: CEP with 8 digits. examples: - "01310100" type: string 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_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 holds webhook_url and the signing key the service generated for this connection. FALSE means the connect succeeded and webhook_url is 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 connection again. 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 RevokeWebhookConnectionResponse: additionalProperties: false properties: provider_type: type: string revoked_connections: format: int64 type: integer status: type: string required: - status - provider_type - revoked_connections 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: description: "Event types the configuration receives, any of: BOLETO_CREATED, BOLETO_SETTLED, BOLETO_CANCELED, BOLETO_CANCEL_FAILED, BOLETO_INACTIVATED, BOLETO_FAILED, BOLETO_EXCESS_PAYMENT, BOLETO_BATCH_FINISHED, PAYMENT_SETTLED, PAYMENT_REJECTED, PAYMENT_FAILED, PAYMENT_CANCELED, PAYMENT_SCHEDULED, PIX_KEY_CHANGED (the notice that the tenant's Pix key changed). A type outside this list is refused." 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. ERROR BODIES. A failed request arrives as an RFC 9457 problem document on application/problem+json. Branch on the code member. A license refusal carries an LCS code, listed in the License Manager error list. title: Payments — via BTG API version: 1.0.0 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/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send it again. security: - BearerAuth: [] summary: Preflight the accounting routes of a ledger tags: - Admin x-mint: href: /en/reference/interfaces/payments-btg/preflight-accounting-routes /v1/admin/boletos/{id}/adopt: post: description: |- Operational action for an installment the emission conference did not adopt: PENDING, without a provider id, and already attempted. That covers an installment whose title the provider proved to exist, one withheld by a lapsed discount before its resend, and one attempted without either, for instance one whose resends the provider keeps refusing. - The service reads the title at the provider by the `providerId` given and compares its `clientRequestId`, derived from the installment, its amount and its due date with the installment's. - All three match: the provider id is recorded on the installment and the acceptance sweep takes it to `CREATED`. The answer is `200` with the boleto, the body of `GET /v1/boletos/{id}`. - Any of them differs, the provider has no title with that id, or the installment is not in that state: `422 PBP-0121`, and nothing is written. The `detail` says which. - Repeating the call with the same `providerId` on the installment it already adopted answers `200`. operationId: adoptBoletoEmission parameters: - description: "Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." in: header name: Idempotency-Key required: true schema: description: "Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." type: string - description: Identifier of the installment's boleto (UUID). in: path name: id required: true schema: description: Identifier of the installment's boleto (UUID). examples: - 01928f6e-7a1b-7c3d-9e4f-5a6b7c8d9e0f format: uuid type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/AdoptBoletoEmissionRequestBody" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/GetBoletoResponse" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Bad Request. PBP-0001: the `id` is not a UUID, or `providerId` is absent or blank." "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not Found. PBP-0005: the boleto does not exist in the tenant." "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Conflict. While an earlier request under the same `Idempotency-Key` is still being processed, a request under that key is answered PBP-0007 and is not run. Send it again under the SAME key after a short wait: the key answers this code for at most five minutes after the earlier request arrived. Afterwards the same key answers with the earlier request's stored answer, with 500 PBP-0002 when that answer cannot be replayed, or, when no answer was kept, by running the request. Do not send it under a new key to get past this answer: the earlier request may still take effect." "413": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Request Entity Too Large "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Unprocessable Entity. PBP-0121 (EMISSION_ADOPTION_REFUSED): the installment is not PENDING, without a provider id and already attempted, or the title read does not match (clientRequestId, amount or due date), or the provider has no title with that id. The `detail` says which. Nothing was written." "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Service Unavailable. PBP-0015: the provider did not answer the title read. Nothing was written. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send the same request again with the same Idempotency-Key." security: - BearerAuth: [] summary: Adopt the provider title of an installment tags: - Boletos x-mint: href: /en/reference/interfaces/payments-btg/adopt-the-provider-title-of-an-installment /v1/admin/pix-config: get: description: |- Returns the Pix key and the receiver address of the tenant of the credentials you authenticate with. They are the Pix receiver of the tenant's hybrid boletos (`type: HYBRID` on POST /v1/boletos), which carry a Pix QR code. A hybrid boleto issued while the key or a member of the address is missing is refused with 422 PBP-0120, naming what is missing. `complete` is true when the key and the four members of the address are present. A partial configuration, such as a key with no address, is answered 200 with `complete: false`, and the members it lacks are omitted. `complete` does not guarantee that an issuance is accepted: the receiver's name and document are not part of this configuration, they come from the record of the collection account when a boleto is issued. A CPF or CNPJ key is checked against the document of that account's holder; the other key types are not verified. Only a tenant with no Pix key configured, or with no provider credential, is answered 404 PBP-0005. operationId: getAdminPixConfig 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/PixConfigResponse" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "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" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send it again. security: - BearerAuth: [] summary: Get the tenant's Pix receiver configuration tags: - Admin x-mint: href: /en/reference/interfaces/payments-btg/get-the-tenants-pix-receiver-configuration post: description: |- Sets the Pix key of the tenant and the address of the receiver, the Pix receiver of the tenant's hybrid boletos (`type: HYBRID` on POST /v1/boletos), which carry a Pix QR code. The whole configuration is replaced: both members are required and there is no partial update. - The key must be a key of the tenant's collection account, in one of the Pix key formats. A key outside them, a CPF or CNPJ key with invalid check digits, a state outside the list or a zip code that is not 8 digits is refused with 400 PBP-0001, naming the member. - A CPF or CNPJ key must be the document of the holder of the collection account, who is the Pix receiver: another document is refused with 422 PBP-0120, naming `pixKey`, and nothing is written. When the holder's document cannot be read, the key is written and the check is left to the issuance of a boleto that carries a Pix QR code. - A random, e-mail or phone key is not looked up in the Pix directory and its ownership is not verified: confirm that it is a key of the tenant's collection account before configuring it. - The address is stored encrypted. It is returned by GET /v1/admin/pix-config and not by this operation. - A tenant with no provider credential is refused with 422 PBP-0017: connect the provider first with POST /v1/admin/providers/connect. - The write records who made it and when (`updatedBy`, `updatedAt`). - A write that changes the key, the tenant's first key included, records the change in the Pix key history, read with GET /v1/admin/pix-config/history, and announces it with the `PIX_KEY_CHANGED` notice to the webhook configurations that enable it. A write that keeps the key and changes only the address records and announces nothing. operationId: configureAdminPixConfig parameters: - description: Tenant organization ID. Optional. The organization context is determined by the credentials you authenticate with; this header does not select or change it. in: header name: X-Organization-Id schema: description: Tenant organization ID. Optional. The organization context is determined by the credentials you authenticate with; this header does not select or change it. type: string - description: "Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." in: header name: Idempotency-Key required: true schema: description: "Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ConfigurePixConfigRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ConfiguredPixConfigResponse" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Conflict. While an earlier request under the same `Idempotency-Key` is still being processed, a request under that key is answered PBP-0007 and is not run. Send it again under the SAME key after a short wait: the key answers this code for at most five minutes after the earlier request arrived. Afterwards the same key answers with the earlier request's stored answer, with 500 PBP-0002 when that answer cannot be replayed, or, when no answer was kept, by running the request. Do not send it under a new key to get past this answer: the earlier request may still take effect." "413": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Request Entity Too Large "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send the same request again with the same Idempotency-Key. security: - BearerAuth: [] summary: Configure the tenant's Pix receiver tags: - Admin x-mint: href: /en/reference/interfaces/payments-btg/configure-the-tenants-pix-receiver /v1/admin/pix-config/history: get: description: |- Lists the changes of the Pix key of the tenant of the credentials you authenticate with, the most recent first, paginated: for each change, the key it set and the key it replaced, who made it and when, and how the key was checked against the holder of the collection account. Every write with POST /v1/admin/pix-config that changes the key is recorded, the tenant's first key included (`firstConfiguration: true`, with no previous key); a write that keeps the key and changes only the address is not a change. Each change is announced by a `PIX_KEY_CHANGED` notice whose `changeId` is its `id`. A CPF, e-mail or phone key is shown masked, by its type; a CNPJ key and a random key are shown whole. The keys are kept with no automatic purge, so the history answers which key a boleto that carries a Pix QR code, issued at a given instant, paid into. A tenant with no change is answered 200 with an empty `items` list and `total: 0`, never 404. A `page` below 1 or a `limit` outside 1 to 100 is refused with 400 PBP-0001. WHO MAY CALL IT. The caller needs the `admin:read` permission, which the `editor`, `operator` and `viewer` roles carry. A caller without it is refused with 403 PBP-0004 before the operation runs. operationId: listAdminPixKeyHistory 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: 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: Changes per page. explode: false in: query name: limit schema: default: 20 description: Changes per page. examples: - 20 format: int64 maximum: 100 minimum: 1 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/ListPixKeyHistoryResponse" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send it again. security: - BearerAuth: [] summary: List the changes of the tenant's Pix key tags: - Admin x-mint: href: /en/reference/interfaces/payments-btg/list-the-changes-of-the-tenants-pix-key /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_subscription_registered. webhook_url is this tenant's inbound address for provider deliveries, and the token it contains identifies the tenant, so treat the response body as secret. The service generates a signing key for each connection, which the provider uses to compute the HMAC-SHA256 of each delivery body, and registers webhook_url and that key at the provider itself; webhook_subscription_registered reports whether this call registered them. Both fields are absent in single-tenant deployments. The signing key is never returned: no endpoint answers with it, so only the service can register it at the provider. Calling connect again ROTATES the connection: it issues a new webhook_url and a new signing key, registers the new pair at the provider, and reports the outcome in webhook_subscription_registered. The previous pair keeps authenticating deliveries for a grace window so that deliveries already in flight are not lost. When the deployment has no provider registration configured, webhook_subscription_registered is false and nothing can register the new pair; the previous pair stops authenticating when the grace window closes. 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/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "413": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Request Entity Too Large "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "502": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Gateway "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send it again. security: - BearerAuth: [] summary: Connect provider with the tenant's client credentials tags: - Admin x-mint: href: /en/reference/interfaces/payments-btg/connect-provider /v1/admin/providers/webhooks/{provider_type}/cancel: post: description: |- Cuts this tenant's inbound webhook channel for one provider, immediately. WHO MAY CALL IT. The caller needs the `admin:cancel` permission, which the `editor` role carries. A caller without it is refused with 403 PBP-0004 before the operation runs. This operation is served in multi-tenant deployments only. WHAT IS CUT: the tenant's current connection for the provider and any previous connection still inside its rotation grace window. THE EFFECT IS IMMEDIATE: the first delivery after this call answers 401. revoked_connections reports how many connections were still able to serve a delivery and are not any more. ZERO IS A SUCCESS: it means nothing was live, because the channel was already cut or the tenant never connected. A retry carrying the SAME Idempotency-Key returns the stored answer of the first call for 48 hours by default, without cutting anything. If a connect ran between the two calls, that replay still reports the first call's revoked_connections while the newly issued channel is live. Use a FRESH Idempotency-Key for every cut. THE ANSWER CARRIES NO CREDENTIAL: no connection token, no delivery URL and no signing key. Restoring the channel means calling provider connect again. operationId: revokeProviderWebhookConnection parameters: - description: Tenant organization ID. Optional. The organization context is determined by the credentials you authenticate with; this header does not select or change it. in: header name: X-Organization-Id schema: description: Tenant organization ID. Optional. The organization context is determined by the credentials you authenticate with; this header does not select or change it. type: string - description: "Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." in: header name: Idempotency-Key required: true schema: description: "Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." type: string - description: Provider whose inbound webhook channel is being cut, as the connect answer names it in provider_type. Matched case-insensitively; a provider this deployment does not serve is refused with 404 rather than answered with a count of zero. in: path name: provider_type required: true schema: description: Provider whose inbound webhook channel is being cut, as the connect answer names it in provider_type. Matched case-insensitively; a provider this deployment does not serve is refused with 404 rather than answered with a count of zero. type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RevokeWebhookConnectionResponse" description: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Conflict. While an earlier request under the same `Idempotency-Key` is still being processed, a request under that key is answered PBP-0007 and is not run. Send it again under the SAME key after a short wait: the key answers this code for at most five minutes after the earlier request arrived. Afterwards the same key answers with the earlier request's stored answer, with 500 PBP-0002 when that answer cannot be replayed, or, when no answer was kept, by running the request. Do not send it under a new key to get past this answer: the earlier request may still take effect." "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send the same request again with the same Idempotency-Key. security: - BearerAuth: [] summary: Revoke the tenant's inbound webhook connection for a provider tags: - Admin x-mint: href: /en/reference/interfaces/payments-btg/revoke-the-tenants-inbound-webhook-connection-for-a-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, as the connect answer names it in provider_type. 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, as the connect answer names it in provider_type. Matched case-insensitively; a provider this deployment does not serve is refused with 404. 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/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Conflict "413": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Request Entity Too Large "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "502": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Gateway "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send it again. security: - BearerAuth: [] summary: Re-register the tenant's existing webhook subscription at a provider tags: - Admin x-mint: href: /en/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, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." in: header name: Idempotency-Key required: true schema: description: "Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." type: string - description: Identifier of the 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/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Conflict. 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/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send the same request again with the same Idempotency-Key. security: - BearerAuth: [] summary: Re-present a quarantined provider webhook tags: - Admin x-mint: href: /en/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/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send it again. security: - BearerAuth: [] summary: Get webhook configuration tags: - Admin x-mint: href: /en/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, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." in: header name: Idempotency-Key required: true schema: description: "Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ConfigureWebhookRequest" required: true 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/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Conflict. While an earlier request under the same `Idempotency-Key` is still being processed, a request under that key is answered PBP-0007 and is not run. Send it again under the SAME key after a short wait: the key answers this code for at most five minutes after the earlier request arrived. Afterwards the same key answers with the earlier request's stored answer, with 500 PBP-0002 when that answer cannot be replayed, or, when no answer was kept, by running the request. Do not send it under a new key to get past this answer: the earlier request may still take effect." "413": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Request Entity Too Large "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send the same request again with the same Idempotency-Key. security: - BearerAuth: [] summary: Configure outbound webhook tags: - Admin x-mint: href: /en/reference/interfaces/payments-btg/configure-webhook /v1/boletos: get: description: Lists boletos with optional status, kind, type, batch and date filters, paginated. Kind BATCH lists the items of batches, and batchId the items of one batch. 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. BATCH lists the items of batches. explode: false in: query name: kind schema: description: Boleto kind filter. BATCH lists the items of batches. enum: - SINGLE - INSTALLMENT - BATCH 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: "Batch filter: only the boletos created as items of this batch. A value that is not a UUID is refused with 400 PBP-0001. A batch that does not exist, or that belongs to another organization, yields an empty list (total 0), not 404: this is a filter. Combined with a kind other than BATCH, the list is empty." explode: false in: query name: batchId schema: description: "Batch filter: only the boletos created as items of this batch. A value that is not a UUID is refused with 400 PBP-0001. A batch that does not exist, or that belongs to another organization, yields an empty list (total 0), not 404: this is a filter. Combined with a kind other than BATCH, the list is empty." examples: - 0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b format: uuid 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/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send it again. security: - BearerAuth: [] summary: List boletos tags: - Boletos x-mint: href: /en/reference/interfaces/payments-btg/list-boletos post: description: "Issues a boleto through the banking provider. The supported boleto types are TRADITIONAL and HYBRID; a request with type QR_CODE is refused with 422 PBP-0006. A HYBRID boleto can also be paid by Pix: it is issued together with a due-date Pix charge, and once its issuance is confirmed the answer carries that charge's identifier in pixTxId. The Pix code the payer scans, in qrCode, and its location, in pixLocation, are served only after the provider has registered the boleto, so that code is never paid into a boleto whose registration fails: both are absent while the boleto is PENDING, as this operation answers it, or FAILED, and GET /v1/boletos/{id} carries them once it is CREATED and on every later status. The charge is registered to the tenant's Pix receiver, configured at POST /v1/admin/pix-config: when that configuration is incomplete, when the holder of the issuing account cannot be the Pix receiver, or when the configured Pix key is a CPF or a CNPJ other than that holder's own document, a HYBRID is refused with 422 PBP-0120, whose detail names what to repair, after the final beneficiary is established and before anything is persisted or sent to the provider. A random, e-mail or phone key is not checked against the holder. On a HYBRID, a percentage charge (a fine of type PERCENTAGE, interest of type DAILY_PERCENTAGE or MONTHLY_PERCENTAGE, or a discount of type PERCENTAGE) accepts at most two decimal places, counted as written, so 2.500 carries three: an amount with more is refused with 422 PBP-0006 naming its field (fine.amount, interest.amount or discount.amount), before anything is persisted or sent to the provider. Every boleto is issued with a final beneficiary (sacador avalista): the holder of the issuing account, read from that account's registration data at issuance and returned in guarantor. This operation does not accept one: a request that sends guarantor is refused with 400 PBP-0001, naming body.guarantor as an unexpected property. The final beneficiary is established after the account checks and before anything is persisted or sent to the provider, and its refusals come in this order: 503 PBP-0118 when the registration data could not be read, or reading it is not configured; then what the registration holds, 400 PBP-0116 when the account has no registered holder, or the holder's registration is incomplete, and 422 PBP-0117 when the registered holder cannot be used as a final beneficiary; last, 422 PBP-0119 when the payer is the account holder, since a boleto cannot be issued to its own final beneficiary. None of them issues anything, and a retry under the same Idempotency-Key runs the request again. The provider account the boleto is issued on is established after the final beneficiary, on a HYBRID together with its Pix receiver, and before anything is persisted or sent to the provider. When the tenant's provider configuration cannot establish it, because the provider is not connected for the tenant, it refused the tenant's credential, or the account to issue on cannot be determined, the request is refused with 422 PBP-0017, the same on every boleto type and with or without a nosso numero; retrying it unchanged does not clear the condition. When the provider refuses that lookup, it is refused with 422 PBP-0014, and when the provider does not answer it, with 503 PBP-0015. None of them issues anything, and a retry under the same Idempotency-Key runs the request again. 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. An issuance without a nosso numero whose outcome at the provider is not confirmed yet is answered 202 Accepted: the emission was recorded and sent, but the provider's answer was lost, could not be read or could not be recorded, and looking the emission up at the provider did not settle it. The 202 carries the recorded boleto, in status PENDING and without providerId, barcode or digitableLine. A background reconciliation completes it: it binds the boleto to its title at the provider when it finds one, and moves it to FAILED when the provider provably holds none. Read its current state with GET /v1/boletos/{id}, using the id in the body. Do not send it again under a new Idempotency-Key, since the provider may have issued it; a resend under the same Idempotency-Key answers this same 202 while the stored answer is kept. Once the read shows the boleto FAILED, it was not issued: send it again under a new Idempotency-Key, since the same Idempotency-Key answers this same 202 until the stored answer expires. Without a nosso numero, 422 PBP-0014 answers only a provider refusal that proves no title was issued, and a retry under the same Idempotency-Key runs the request again. A request under an Idempotency-Key already used for a different boleto, or naming a boleto whose emission reached the provider and failed, is refused with 422 PBP-0013; send it under a new Idempotency-Key." 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, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." in: header name: Idempotency-Key required: true schema: description: "Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateBoletoRequest" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CreateBoletoResponse" description: "Created. The banking provider issued the boleto: the body carries its `providerId`. Compare the 202, where the provider's answer is not confirmed yet." "202": content: application/json: schema: $ref: "#/components/schemas/CreateBoletoResponse" description: "Accepted. The boleto was recorded and its emission was sent to the banking provider, but the provider's answer is not confirmed yet: it was lost, could not be read or could not be recorded, and looking the emission up at the provider did not settle it. The boleto is in status PENDING and carries no `providerId`, `barcode` or `digitableLine`. Do NOT send it again under a new `Idempotency-Key`: the provider may have issued it, and a second request can issue a second boleto. A background reconciliation completes it: it binds the boleto to its title at the provider when it finds one, and moves it to FAILED when the provider provably holds none. Read its current state with GET /v1/boletos/{id}, using the `id` in this body. A resend under the SAME `Idempotency-Key` is safe: it answers this same 202 while the stored answer is kept, even after the boleto is completed, so read the boleto by id for its current state. Once the read shows the boleto FAILED, it was not issued: send it again under a NEW `Idempotency-Key`, since the same `Idempotency-Key` answers this same 202 until the stored answer expires." "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Conflict. While an earlier request under the same `Idempotency-Key` is still being processed, a request under that key is answered PBP-0007 and is not run. Send it again under the SAME key after a short wait: the key answers this code for at most five minutes after the earlier request arrived. Afterwards the same key answers with the earlier request's stored answer, with 500 PBP-0002 when that answer cannot be replayed, or, when no answer was kept, by running the request. Do not send it under a new key to get past this answer: the earlier request may still take effect." "413": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Request Entity Too Large "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send the same request again with the same Idempotency-Key. security: - BearerAuth: [] summary: Issue a single boleto tags: - Boletos x-mint: href: /en/reference/interfaces/payments-btg/issue-boleto /v1/boletos/batches: get: description: "Lists the boleto batches of the X-Organization-Id organization, most recent first, each with its outcome and counts and without its items; read one batch by its batchId for the items. The outcome, the counts, `closed` and `finished` are derived from the items on every read. The parameters are validated as on GET /v1/boletos: 400 PBP-0001 when page, limit, from or to is malformed or out of range, or when from or to names a day that does not exist, and 422 PBP-0006 when from is after to. An organization with no batch in the window is answered an empty page: `items` is `[]` and `total` is 0. A request refused earlier keeps its own status: 401 or 403 for authentication and authorization, and 400 PBP-0025 when X-Organization-Id is missing or not a canonical UUID." operationId: listBoletoBatches parameters: - description: "Organization whose batches are listed. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. Only batches of this organization are listed and counted." in: header name: X-Organization-Id schema: description: "Organization whose batches are listed. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. Only batches of this organization are listed and counted." 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-10-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-10-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: 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/ListBoletoBatchesResponse" description: A page of the organization's batches, most recent first. A page with no batch carries an empty items list, never null. "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send it again. security: - BearerAuth: [] summary: List boleto batches tags: - Boletos x-mint: href: /en/reference/interfaces/payments-btg/list-boleto-batches post: description: "Issues from 1 to 25 TRADITIONAL boletos, one per item, on one collection account (midazAccountId) and one ledger (ledgerId) of the X-Organization-Id organization, in a single request. The answer is 202 Accepted with the batch and the status of each item: the batch is recorded and its items are sent for issuance, and no item carries a barcode in this answer. Issuance goes on asynchronously, each item on its own; follow it at GET /v1/boletos/batches/{batch_id} or through the status change notifications configured at /v1/admin/webhooks. A request refused before anything is recorded keeps its own status and code, in this order: 401 or 403 for authentication and authorization; 400 PBP-0012 for a missing or malformed Idempotency-Key; 413 PBP-0010 for a body above 256 KiB (262144 bytes); 400 PBP-0001 for a body that fails schema validation, including items absent or null, an item without type, and guarantor, ledgerId or midazAccountId sent inside an item; 400 PBP-0025 when X-Organization-Id is missing or not a canonical UUID; 400 PBP-0026 when ledgerId is missing or not a canonical UUID; 400 PBP-0001 when midazAccountId is blank; 422 PBP-0122 when the batch holds fewer than 1 or more than 25 items, with maxItems and receivedItems; 404 PBP-0005 when the account does not exist or is not under the organization and the ledger; 400 PBP-0116 when the account has no registered holder, or the holder's registration is incomplete, and 422 PBP-0117 when the registered holder cannot be used as a final beneficiary; 422 PBP-0123 when one or more items break a rule, the whole batch refused with every problem listed in itemErrors, each with its position and field; and 422 PBP-0017 when an item carries ourNumber and this instance has no account discovery to reserve it in. A retry carrying the same Idempotency-Key and the same body issues no boleto: it returns the stored answer of the first call while the service keeps the idempotency record of that call, and the batch's current state once the record has expired. The same key with a different body is refused with 422 PBP-0013." operationId: createBoletoBatch 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, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." in: header name: Idempotency-Key required: true schema: description: "Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateBoletoBatchRequest" required: true responses: "202": content: application/json: schema: $ref: "#/components/schemas/BoletoBatchResponse" description: "Accepted: the batch is recorded and its items are sent for issuance. Each item carries its position, its boleto and its status." "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Conflict. While an earlier request under the same `Idempotency-Key` is still being processed, a request under that key is answered PBP-0007 and is not run. Send it again under the SAME key after a short wait: the key answers this code for at most five minutes after the earlier request arrived. Afterwards the same key answers with the earlier request's stored answer, with 500 PBP-0002 when that answer cannot be replayed, or, when no answer was kept, by running the request. Do not send it under a new key to get past this answer: the earlier request may still take effect." "413": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Request Entity Too Large "422": content: application/problem+json: schema: anyOf: - $ref: "#/components/schemas/BatchSizeProblem" - $ref: "#/components/schemas/BatchInvalidItemsProblem" - $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send the same request again with the same Idempotency-Key. security: - BearerAuth: [] summary: Issue a batch of boletos tags: - Boletos x-mint: href: /en/reference/interfaces/payments-btg/issue-a-batch-of-boletos /v1/boletos/batches/{batch_id}: get: description: "Reads one boleto batch of the X-Organization-Id organization: its outcome, its counts and every item, in ascending position. The outcome, the counts, `closed`, `finished` and each item's `overdue` are derived from the items on every read, at the instant of the read. A batch that does not exist and a batch of another organization are both answered 404 PBP-0005, with the same body. A request refused earlier keeps its own status: 401 or 403 for authentication and authorization, 400 PBP-0001 when batch_id is not a UUID, and 400 PBP-0025 when X-Organization-Id is missing or not a canonical UUID." operationId: getBoletoBatch parameters: - description: "Organization the batch belongs to. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. A batch of another organization is answered 404, exactly as one that does not exist." in: header name: X-Organization-Id schema: description: "Organization the batch belongs to. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. A batch of another organization is answered 404, exactly as one that does not exist." type: string - description: Batch identifier (UUID), the batchId the creation answered. A value that is not a UUID is refused with 400 PBP-0001. in: path name: batch_id required: true schema: description: Batch identifier (UUID), the batchId the creation answered. A value that is not a UUID is refused with 400 PBP-0001. examples: - 0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/BoletoBatchResponse" description: The batch with its outcome, its counts and every item, derived at the instant of the read. "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send it again. security: - BearerAuth: [] summary: Get a boleto batch tags: - Boletos x-mint: href: /en/reference/interfaces/payments-btg/get-a-boleto-batch /v1/boletos/batches/{batch_id}/cancel: post: description: "Cancels the cancelable items of one boleto batch of the X-Organization-Id organization and answers one result per item, in ascending position. Only an item in CREATED status that is registered at the payment provider is canceled, through the same cancellation as POST /v1/boletos/{id}/cancel and with the request's reason; every other item is answered NOT_CANCELABLE with PBP-0103 and is not touched, its status saying why. An item whose cancellation is attempted and refused, or fails, is answered CANCEL_FAILED with the code and message of that refusal, and the other items are still canceled. Canceling only part of a batch is not an error: a batch that is found is answered 200, and each item's status is the one its boleto has after the attempt. A retry carrying the same Idempotency-Key returns the stored answer of the first call, without executing anything, while the service keeps the idempotency record of that call; once the record has expired, the same key is answered from the items' current state, so an item the first call canceled comes back NOT_CANCELABLE with status CANCELED. To cancel one boleto of a batch on its own, use POST /v1/boletos/{id}/cancel. A request refused before any item is touched keeps its own status and code, in this order: 401 or 403 for authentication and authorization; 400 PBP-0012 for a missing or malformed Idempotency-Key; 400 PBP-0001 when batch_id is not a UUID or the body fails schema validation, including reason absent or not a string; 400 PBP-0025 when X-Organization-Id is missing or not a canonical UUID; 400 PBP-0001 when reason is blank once trimmed, longer than 500 characters or carries markup, with the same messages as POST /v1/boletos/{id}/cancel; and 404 PBP-0005 when the batch does not exist or belongs to another organization, with the same body for both." operationId: cancelBoletoBatch parameters: - description: "Organization the batch belongs to. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. A batch of another organization is answered 404, exactly as one that does not exist." in: header name: X-Organization-Id schema: description: "Organization the batch belongs to. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. A batch 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, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." in: header name: Idempotency-Key required: true schema: description: "Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." type: string - description: Batch identifier (UUID), the batchId the creation answered. A value that is not a UUID is refused with 400 PBP-0001. in: path name: batch_id required: true schema: description: Batch identifier (UUID), the batchId the creation answered. A value that is not a UUID is refused with 400 PBP-0001. examples: - 0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b format: uuid type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CancelBoletoBatchRequest" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/CancelBoletoBatchResponse" description: "One result per item of the batch, in ascending position: whether this request canceled the item (CANCELED), could not cancel it (NOT_CANCELABLE) or attempted it and was refused (CANCEL_FAILED), and the status of its boleto after the attempt. Canceling only part of a batch is not an error." "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Conflict. While an earlier request under the same `Idempotency-Key` is still being processed, a request under that key is answered PBP-0007 and is not run. Send it again under the SAME key after a short wait: the key answers this code for at most five minutes after the earlier request arrived. Afterwards the same key answers with the earlier request's stored answer, with 500 PBP-0002 when that answer cannot be replayed, or, when no answer was kept, by running the request. Do not send it under a new key to get past this answer: the earlier request may still take effect." "413": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Request Entity Too Large "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send the same request again with the same Idempotency-Key. security: - BearerAuth: [] summary: Cancel a boleto batch tags: - Boletos x-mint: href: /en/reference/interfaces/payments-btg/cancel-a-boleto-batch /v1/boletos/installments: post: description: "Creates a series of 2 to 36 independent boletos, one per installment, with totalAmount split evenly, the remainder going to the last installment, or with the amounts given in installmentAmounts. Installment k falls due on firstDueDate plus (k-1) times intervalDays days, with intervalDays from 1 to 365 and no business-day adjustment. The answer is immediate and nothing is issued in it: the series and its installments are recorded PENDING, and each installment is registered with the banking provider afterwards, one at a time. This answer always carries status CREATED and closed false; follow the series at GET /v1/boletos/installments/{series_id} and each installment at GET /v1/boletos/{id}. The organization comes from the X-Organization-Id header and the ledger from ledgerId, with the same refusals as POST /v1/boletos, and every installment is written with that pair. The account in midazAccountId must belong to that organization and ledger, and it is checked once per series. Nothing is recorded when a request is refused, and the refusals come in this order: 401 PBP-0003 and 403 PBP-0004 for authentication and authorization; the Idempotency-Key, 400 PBP-0012 when it is missing or malformed, 409 PBP-0007 while the original request is still running, and 422 PBP-0013 when the same key arrives with another body or under another organization; 400 PBP-0001 for a body that fails schema validation, including one that sends guarantor, which this operation does not accept, for installments or intervalDays of zero or less, and for an ourNumbers item that is not a number, named as ourNumbers[] counted from 0; 400 PBP-0025 for the organization, then 400 PBP-0026 for the ledger; 400 PBP-0001 for a date or an amount that cannot be read; 422 PBP-0006 for a type a series does not carry, QR_CODE or HYBRID; 422 PBP-0102 for a payer document whose check digit fails or a first due date before today; 422 PBP-0006 for a refused fine, interest or discount; 422 PBP-0102 for intervalDays above 365, installments outside 2 to 36, an installmentAmounts list of another length, or an amount below 0.01 or with more than two decimal places; the numbers, when ourNumbers is present and not null: 422 PBP-0102 for an ourNumbers list that does not hold one number per installment, an empty one included, 422 PBP-0006 when the connected provider does not accept a number chosen by the payee, or 422 PBP-0017 when this instance has no provider to judge them by, 400 PBP-0001 for an ourNumbers item wider than the provider accepts, named as ourNumbers[], and 422 PBP-0102 when two installments carry the same number, with the installments, counted from 1, in duplicateInstallmentNumbers; the account, 404 PBP-0005 when it does not exist or belongs to another organization or ledger, 422 PBP-0106 when account validation is not configured on this instance, and 503 PBP-0301 when the ledger credential is unavailable; the final beneficiary, established once per series, 503 PBP-0118 when the account holder's registration data cannot be read or reading it is not configured, 400 PBP-0116 when it is incomplete, 422 PBP-0117 when the holder cannot be a final beneficiary and 422 PBP-0119 when the payer is the holder; 422 PBP-0102 when installmentAmounts does not add up to totalAmount; only for a series with numbers, the provider account the numbers are reserved in, 422 PBP-0017 when this instance has no account discovery, 422 PBP-0014 when the provider refuses the lookup and 503 PBP-0015 when it does not answer; last, 422 PBP-0108 when a number is already held by an active boleto of this tenant on the same provider account, before the provider is called and with nothing of the series recorded, the problem carrying the installment as installmentNumber and, when the holder can be read, its id as ourNumberHolderBoletoId. A series without numbers never depends on the account discovery. A refusal releases the Idempotency-Key, and so do 503 PBP-0301, 503 PBP-0118 and 503 PBP-0015: a retry under the same key runs the request again." operationId: createBoletoInstallments parameters: - description: "Midaz organization the account and every installment live under. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025." in: header name: X-Organization-Id schema: description: "Midaz organization the account and every installment live under. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025." type: string - description: "Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." in: header name: Idempotency-Key required: true schema: description: "Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateInstallmentsRequest" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CreateInstallmentsResponse" description: Created "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Conflict. While an earlier request under the same `Idempotency-Key` is still being processed, a request under that key is answered PBP-0007 and is not run. Send it again under the SAME key after a short wait: the key answers this code for at most five minutes after the earlier request arrived. Afterwards the same key answers with the earlier request's stored answer, with 500 PBP-0002 when that answer cannot be replayed, or, when no answer was kept, by running the request. Do not send it under a new key to get past this answer: the earlier request may still take effect." "413": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Request Entity Too Large "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Service Unavailable. PBP-0301 means the ledger credential needed to check the account could not be resolved, or the ledger refused it. PBP-0118 means the account holder's registration data, which establishes the final beneficiary, could not be read, or reading it is not configured on this instance. PBP-0015 means the provider did not answer the discovery of the account a series' ourNumbers are reserved in; a series without numbers never receives it. Nothing was recorded, and all three release the Idempotency-Key: wait and send the same request again with the same key. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send the same request again with the same Idempotency-Key." security: - BearerAuth: [] summary: Issue installment boletos tags: - Boletos x-mint: href: /en/reference/interfaces/payments-btg/issue-installment-boletos /v1/boletos/installments/{series_id}: get: description: "Returns an installment series and every one of its installments, in installmentNumber order. status is the emission outcome of the series, derived from its installments on every read: CREATED while some installment has no emission outcome yet, COMPLETED when every installment has one and none is FAILED, PARTIAL_FAILURE when some, not all, are FAILED, and FAILED when all of them are; an installment that FAILED says why in errorMessage. The outcome is not final: an installment the provider accepted can still end FAILED, so a COMPLETED series can become PARTIAL_FAILURE or FAILED. closed says, apart from it, whether every installment is SETTLED, CANCELED, INACTIVATED or FAILED; it can return to false when the provider reverts the cancellation of an installment, and a client waiting for the final outcome waits for closed to be true. The X-Organization-Id header is required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025, and a series_id that is not a UUID with 400 PBP-0001. A series whose installments belong to another organization is answered 404 PBP-0005, exactly as a series that does not exist, and never 403. 401 and 403 answer authentication and authorization." operationId: getInstallmentSeries parameters: - description: "Midaz organization the installments were written with. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. A series of another organization is answered 404, as a missing one." in: header name: X-Organization-Id schema: description: "Midaz organization the installments were written with. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. A series of another organization is answered 404, as a missing one." 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: OK "400": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "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" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send it again. security: - BearerAuth: [] summary: Get installment series tags: - Boletos x-mint: href: /en/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/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send it again. security: - BearerAuth: [] summary: Get boleto by ID tags: - Boletos x-mint: href: /en/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, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." in: header name: Idempotency-Key required: true schema: description: "Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." type: string - description: 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/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Conflict. While an earlier request under the same `Idempotency-Key` is still being processed, a request under that key is answered PBP-0007 and is not run. Send it again under the SAME key after a short wait: the key answers this code for at most five minutes after the earlier request arrived. Afterwards the same key answers with the earlier request's stored answer, with 500 PBP-0002 when that answer cannot be replayed, or, when no answer was kept, by running the request. Do not send it under a new key to get past this answer: the earlier request may still take effect." "413": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Request Entity Too Large "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send the same request again with the same Idempotency-Key. security: - BearerAuth: [] summary: Cancel an issued boleto tags: - Boletos x-mint: href: /en/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. A HYBRID boleto's PDF also prints its Pix QR code, so it is served only once the provider has registered the boleto, exactly like its `qrCode`: while the boleto is PENDING the response is 503 with a Retry-After header, and a FAILED one is answered 422." 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/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "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" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send it again. security: - BearerAuth: [] summary: Download boleto PDF tags: - Boletos x-mint: href: /en/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/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send it again. security: - BearerAuth: [] summary: Get boleto dashboard tags: - Dashboards x-mint: href: /en/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/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send it again. security: - BearerAuth: [] summary: Get payment dashboard tags: - Dashboards x-mint: href: /en/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/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send it again. security: - BearerAuth: [] summary: List payments tags: - Payments x-mint: href: /en/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, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." in: header name: Idempotency-Key required: true schema: description: "Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/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/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/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Not Found. 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/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Conflict. While an earlier request under the same `Idempotency-Key` is still being processed, a request under that key is answered PBP-0007 and is not run. Send it again under the SAME key after a short wait: the key answers this code for at most five minutes after the earlier request arrived. Afterwards the same key answers with the earlier request's stored answer, with 500 PBP-0002 when that answer cannot be replayed, or, when no answer was kept, by running the request. Do not send it under a new key to get past this answer: the earlier request may still take effect." "413": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Request Entity Too Large "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Unprocessable Entity. 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/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/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 a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. 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: /en/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/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "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" 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. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send it again." 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: /en/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, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." in: header name: Idempotency-Key required: true schema: description: "Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/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/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/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Conflict. While an earlier request under the same `Idempotency-Key` is still being processed, a request under that key is answered PBP-0007 and is not run. Send it again under the SAME key after a short wait: the key answers this code for at most five minutes after the earlier request arrived. Afterwards the same key answers with the earlier request's stored answer, with 500 PBP-0002 when that answer cannot be replayed, or, when no answer was kept, by running the request. Do not send it under a new key to get past this answer: the earlier request may still take effect." "413": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Request Entity Too Large "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Unprocessable Entity. 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/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/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 a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. 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: /en/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/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "404": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Not Found "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "503": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send it again. security: - BearerAuth: [] summary: Get payment by ID tags: - Payments x-mint: href: /en/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, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." in: header name: Idempotency-Key required: true schema: description: "Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012." type: string - description: 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/problem+json: schema: $ref: "#/components/schemas/Detail" description: Bad Request "401": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again." "403": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed." "409": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: "Conflict. While an earlier request under the same `Idempotency-Key` is still being processed, a request under that key is answered PBP-0007 and is not run. Send it again under the SAME key after a short wait: the key answers this code for at most five minutes after the earlier request arrived. Afterwards the same key answers with the earlier request's stored answer, with 500 PBP-0002 when that answer cannot be replayed, or, when no answer was kept, by running the request. Do not send it under a new key to get past this answer: the earlier request may still take effect." "413": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Request Entity Too Large "422": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Unprocessable Entity "500": content: application/problem+json: schema: $ref: "#/components/schemas/Detail" description: Internal Server Error "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/problem+json: schema: $ref: "#/components/schemas/Detail" description: Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send the same request again with the same Idempotency-Key. security: - BearerAuth: [] summary: Cancel a payment tags: - Payments x-mint: href: /en/reference/interfaces/payments-btg/cancel-payment /v1/webhooks/btg: post: description: "Accepts a settlement event pushed by the payment provider, persists it with the personal data it carries masked 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, except that the members named for the payer, the beneficiary, the beneficiary's account, the account information, the customer, the guarantor or drawer, the debtor, the receiver, the merchant, the Pix key, the tax id, the CPF and the CNPJ are masked before they are stored, wherever they appear in the body. Every text or number inside such a member is masked, and a number is stored as masked text; booleans and null are kept. Personal data under any other member name is 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. When a notification id is reused by a delivery whose pactualId, entity or status differs from the delivery already stored under that id, the new delivery is a different notification: it is stored as a separate delivery under the key derived from pactualId, entity, status and createTimestamp, while a delivery with the same three values is a repeat of the stored one. 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: /en/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 with the personal data it carries masked 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, except that the members named for the payer, the beneficiary, the beneficiary's account, the account information, the customer, the guarantor or drawer, the debtor, the receiver, the merchant, the Pix key, the tax id, the CPF and the CNPJ are masked before they are stored, wherever they appear in the body. Every text or number inside such a member is masked, and a number is stored as masked text; booleans and null are kept. Personal data under any other member name is 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. When a notification id is reused by a delivery whose pactualId, entity or status differs from the delivery already stored under that id, the new delivery is a different notification: it is stored as a separate delivery under the key derived from pactualId, entity, status and createTimestamp, while a delivery with the same three values is a repeat of the stored one. 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: /en/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