> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # List payments > Lists payments with optional status, type, creation-date and due-date filters, paginated. ## OpenAPI ````yaml /pt/openapi/v3-current/payments.yaml get /v1/payments openapi: 3.1.0 info: description: >- API for the Lerian Payments interface via BTG. It covers boleto issuance, cancellation, and queries; bill payments (bankslip, utilities, and DARF) and queries; aggregated boleto and payment dashboards; provider connection and outbound webhook configuration; and the provider webhook receiver for settlement events. ERROR BODIES. A failed request arrives as an RFC 9457 problem document on application/problem+json. Branch on the code member. A license refusal carries an LCS code, listed in the License Manager error list. title: Payments — via BTG API version: 1.0.0 servers: - url: https://api.example.com description: >- Replace the example host with the URL provided during environment onboarding. security: [] tags: - description: >- Tenant-level setup: connecting the banking provider and configuring where status notifications are delivered. name: Admin - description: Issuing, querying and cancelling boletos, and retrieving the rendered PDF. name: Boletos - description: >- Aggregated counts, amounts and breakdowns over a period, for boletos and for payments. name: Dashboards - description: >- Paying bankslips, utility bills and DARF tax slips, and querying those payments. name: Payments - description: >- The webhook the payment provider posts settlement events to. Authenticated with a credential agreed with the provider, not with the platform identity used by the rest of this API. name: Settlement paths: /v1/payments: get: tags: - Payments summary: List payments 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: [] components: schemas: 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 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 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 ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object 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 PayeeResponse: additionalProperties: false properties: name: type: string taxId: type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.