---
updatedAt: 2026-05-15T20:15:05.000Z
agentTools:
siteIndex: https://developers.pismo.io/llms.txt
projectIndex: https://developers.pismo.io/pismo-docs/llms.txt
---
# List payment orders
List payment orders. By default, payment orders from the last 30 days with 20 records per page are returned, but you can use the `beginDate` and `endDate` query parameters to specify a different date range.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "Instant payments - Automatic Pix",
"description": "API to handle Automatic Pix transactions",
"termsOfService": "https://developers.pismo.io/terms/",
"contact": {
"name": "API Support",
"url": "https://developers.pismo.io/support/",
"email": "support@pismo.com.br"
},
"license": {
"name": "Copyright Pismo",
"url": "https://developers.pismo.io/licenses/"
},
"version": "1.0"
},
"servers": [
{
"url": "https://sandbox-cdn.pismolabs.io",
"description": "Ext API server for testing"
},
{
"url": "https://sandbox-cdn.pismolabs.io/inst-pull-pay",
"description": "Ext API server for testing Automatic Pix."
}
],
"tags": [
{
"name": "Automatic Pix data"
}
],
"components": {
"parameters": {
"AfterIdQuery": {
"in": "query",
"name": "afterId",
"description": "Last returned item ID from response. Use this field to return more results.",
"required": false,
"schema": {
"type": "string"
}
},
"AuthHeader": {
"in": "header",
"name": "Authorization",
"required": true,
"description": "Account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a 401 Unauthorized message.",
"schema": {
"type": "string",
"example": "Bearer eyJhbGci...IUzUx"
}
},
"BeginDateQueryOptional": {
"name": "beginDate",
"in": "query",
"description": "RFC 3339 begin date filter. For example: `2023-04-12T23:20:50.52Z`. \n\nMaximum days allowed between `beginDate` and `endDate` is 30.\nThe default is 30 days prior to the current date.\n",
"required": false,
"schema": {
"type": "string"
},
"example": "2023-04-12T23:20:50.52Z"
},
"EndDateQueryOptional": {
"name": "endDate",
"in": "query",
"description": "RFC 3339 end date filter. For example: `2023-04-12T23:20:50.52Z`. \n\nMaximum days allowed between `beginDate` and `endDate` is 30.\nThe default is the current date and time.\n",
"required": false,
"schema": {
"type": "string"
},
"example": "2023-04-12T23:20:50.52Z"
},
"PaymentOrderStatusQuery": {
"name": "status",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"PENDING",
"WAITING_CUSTOMER",
"REGISTERED",
"ACTIVE",
"CANCELLED",
"CANCELLING",
"EXPIRED",
"REJECTED",
"CONCLUDED"
]
},
"description": "Payment order status filter",
"example": "PENDING"
},
"PerPageQuery": {
"name": "perPage",
"in": "query",
"description": "Per page amount (min=1, max=100). Default is `20`.",
"required": false,
"schema": {
"type": "string"
}
},
"RecurrenceIdQuery": {
"name": "recurrenceId",
"in": "query",
"description": "BACEN (Brazil Central Bank) recurrence ID filter",
"required": false,
"schema": {
"type": "string"
}
},
"RoleTypeQuery": {
"name": "roleType",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"PAYEE",
"PAYER"
]
},
"description": "Role type filter."
}
},
"schemas": {
"AccountID": {
"type": "integer",
"description": "Pismo account ID.",
"example": 5869300
},
"AccountNumber2": {
"type": "string",
"description": "Payer's account number.",
"maxLength": 20,
"example": "98765432"
},
"AccountType": {
"type": "string",
"enum": [
"CACC",
"SLRY",
"SVGS",
"TRAN"
],
"maxLength": 4,
"description": "Account type:
\n `CACC` - Checking account
\n `SVGS` - Savings account
\n `TRAN` - Transactional account (Brazil only). Also known as \"conta corrente\" in Portuguese, this is a bank account type designed for everyday financial transactions and is the most common type individuals and businesses use for day-to-day banking.
\n `SLRY` - Salary account. Employer deposits a fixed amount every month.
\n",
"example": "TRAN"
},
"AdditionalInformation": {
"type": "string",
"description": "Additional information",
"maxLength": 105
},
"Amount": {
"type": "number",
"description": "Amount to be transferred.",
"example": 1050.44
},
"Bank": {
"type": "string",
"description": "ISPB (Identifcador do Sistema de Pagamento Brazil) - the Brazilian Payment System ID for the receiving bank, an 8-digit value.",
"maxLength": 8,
"example": "237"
},
"Branch": {
"type": "string",
"description": "This could be a bank-assigned branch ID or the branch's ISPB number.",
"maxLength": 4,
"example": "011"
},
"CityCode": {
"type": "string",
"minLength": 7,
"maxLength": 7,
"description": "\nAn IBGE municipal code is a 7-digit numerical ID that the Brazilian Institute of Geography and Statistics (IBGE) assigns to uniquely ID each municipality and federal district in Brazil.\n",
"example": "3550308"
},
"CalendarDueDate": {
"type": "string",
"description": "Calendar due date",
"example": "2030-10-10"
},
"CalendarWorkingDay": {
"type": "boolean",
"description": "Calendar working day?",
"example": false
},
"CreatedAt": {
"type": "string",
"format": "datetime",
"description": "Created at datetime. RFC 3339 format \n",
"example": "2025-11-14T17:54:40Z"
},
"customer.DetailMessage": {
"type": "object",
"properties": {
"external": {
"type": "array",
"items": {
"$ref": "#/components/schemas/customer.ExternalMessage"
}
},
"parameters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/customer.ParameterMessage"
}
},
"payload": {
"type": "array",
"items": {
"$ref": "#/components/schemas/customer.PayloadMessage"
}
}
}
},
"customer.Error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error's code.",
"example": "EPT0001"
},
"details": {
"$ref": "#/components/schemas/customer.DetailMessage"
},
"message": {
"type": "string",
"description": "Error's message.",
"example": "User not found"
}
}
},
"customer.ExternalMessage": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Error code.",
"example": "PBE315"
},
"message": {
"type": "string",
"description": "Error message.",
"example": "Generic error"
}
}
},
"customer.ParameterMessage": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "Parameter field",
"example": "Query parameter"
},
"message": {
"type": "string",
"description": "Message about parameter",
"example": "Generic error"
}
}
},
"customer.PayloadMessage": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "Payload parameter",
"example": "Entity.field"
},
"message": {
"type": "string",
"description": "Message about error",
"example": "Generic error"
}
}
},
"Debtor": {
"type": "object",
"required": [
"document_number",
"document_type",
"name"
],
"properties": {
"document_number": {
"$ref": "#/components/schemas/DocumentNumber"
},
"document_type": {
"$ref": "#/components/schemas/PersonType"
},
"name": {
"$ref": "#/components/schemas/Name"
}
}
},
"DocumentNumber": {
"type": "string",
"description": "A government document number, such as a Social Security number (US) or Cadastro de Pessoas Físicas number (Brazil). Must be numeric with 11-14 digits.\n",
"minLength": 1,
"maxLength": 14,
"example": "123412341234"
},
"DynamicAmount": {
"type": "boolean",
"description": "Does recurrence have a dynamic amount? \n\nIf `true`, `min_payment_amount` is **REQUIRED**. \n\nIf `false`, `amount` is **REQUIRED**. Default is `false`.\n",
"default": false,
"example": false
},
"EndToEndID": {
"type": "string",
"description": "This field is a Brazil Central Bank (BCB) requirement to track all steps of Pix transactions.
\nBasically, there are two steps to a Pix transaction:
\n 1. Initialize a transaction
\n 2. Confirm a transaction
\nThe `end_to_end_id` is sent to the BCB in both steps in order to identify all transaction information.
\n",
"example": "E3030629420200808195101608910248"
},
"LastID": {
"type": "integer",
"description": "Last returned item ID. Use this ID to get more results.",
"example": 1602619
},
"MaxPaymentAmount": {
"type": "number",
"description": "Payer-defined maximum payment amount for dynamic amount recurrences.",
"example": 86753.09
},
"MinPaymentAmount": {
"type": "number",
"description": "Payee-defined minimum payment amount for dynamic amount recurrences.",
"example": 10.09
},
"Name": {
"type": "string",
"description": "Name",
"maxLength": 200,
"example": "Walter Melon"
},
"NextPage": {
"type": "boolean",
"description": "Are tbere more results?",
"example": false
},
"NullType": {
"title": "Null type reference",
"description": "Used to add nullability to a ref",
"enum": [
null
]
},
"NumberElements": {
"type": "number",
"description": "Total items returned in query"
},
"PageSize": {
"type": "number",
"description": "Maximum elements returned per query."
},
"Payee": {
"type": "object",
"required": [
"document_number",
"document_type",
"name",
"bank",
"branch",
"account_number",
"account_type"
],
"properties": {
"name": {
"$ref": "#/components/schemas/Name"
},
"document_number": {
"$ref": "#/components/schemas/DocumentNumber"
},
"document_type": {
"$ref": "#/components/schemas/PersonType"
},
"bank": {
"$ref": "#/components/schemas/Bank"
},
"branch": {
"$ref": "#/components/schemas/Branch"
},
"account_number": {
"$ref": "#/components/schemas/AccountNumber2"
},
"account_type": {
"$ref": "#/components/schemas/AccountType"
}
}
},
"Payer": {
"type": "object",
"required": [
"document_number",
"document_type",
"name",
"bank",
"branch",
"account_number"
],
"properties": {
"document_number": {
"$ref": "#/components/schemas/DocumentNumber"
},
"document_type": {
"$ref": "#/components/schemas/PersonType"
},
"name": {
"$ref": "#/components/schemas/Name"
},
"bank": {
"$ref": "#/components/schemas/Bank"
},
"branch": {
"$ref": "#/components/schemas/Branch"
},
"account_number": {
"$ref": "#/components/schemas/AccountNumber2"
},
"account_type": {
"$ref": "#/components/schemas/AccountType"
},
"city_code": {
"$ref": "#/components/schemas/CityCode"
}
}
},
"PaymentOrderReason": {
"description": "Payment order cancellation reason: \n\n* `ACCT` - Paying or receiving user's transactional account closed\n* `BLCK` - Paying or receiving user's transactional account blocked\n* `CCLD` - Recurring payments authorization cancelled\n* `FAIL` - Settlement process failure or error\n* `OTHR` - Paying or receiving user requested cancellation for other reasons\n* `SLBD` - Paying user request\n* `SLCR` - Receiving user request\n",
"type": "string",
"enum": [
"ACCT",
"BLCK",
"CCLD",
"FAIL",
"OTHR",
"SLBD",
"SLCR"
],
"example": "ACCT"
},
"PaymentOrderReasonDescription": {
"description": "Payment order cancellation reason desciption\n",
"type": "string",
"example": "Paying user's account has been closed."
},
"PaymentOrderStatus": {
"description": "Payment order status: \n\n* `PENDING` - Payment order exists in the database.\n* `WAITING_CUSTOMER`- Waiting on the payee to update the payment order amount. Refer to the [Update order](https://developers.pismo.io/pismo-docs/reference/update-order-automatic-pix) endpoint.\n* `REGISTERED` - Payment order was registered to SPI instant payment system. \n* `ACTIVE` - Payer PSP accepted payment order.\n* `REJECTED` - Payer PSP rejected payment order. Check `reason.code` and `reason.description`.\n* `CANCELLING` - Payment order was previously accepted, cancel process has begun. and it's waiting on counterparty acknowledgement.\n* `CANCELLED` - Payment order was previously accepted and then cancelled. Check `reason.code` and `reason.description`.\n* `EXPIRED` - Pix transaction was not found by the due date. Will trigger retry if applicable to the recurrence.\n* `CONCLUDED` - Pix transaction was found and payment order is concluded.\n",
"type": "string",
"enum": [
"PENDING",
"WAITING_CUSTOMER",
"REGISTERED",
"ACTIVE",
"CANCELLED",
"CANCELLING",
"EXPIRED",
"REJECTED",
"CONCLUDED"
],
"example": "PENDING"
},
"PaymentOrderType": {
"description": "Payment order type:\n\n* `SCHEDULE` - Standard scheduled payment order created from the recurrence cycle.\n* `RETRY_OVERDUE` - Retry generated when a payment order expired unpaid, or when the payer PSP did not respond or responded FAIL before the due date. A new payment order of the same type is created for retry, respecting the recurrence retry policy.\n* `RETRY_ERROR` - Intraday retry (only on the settlement date, until 21:00) created after a settlement failure that occurred after the payment order was already sent to SPI (BCB \"Guia Pix Automático\" §5.2, `finalidadeDoAgendamento = RIFL`). One payment order is created per retry requested by the payer PSP.\n",
"type": "string",
"enum": [
"SCHEDULE",
"RETRY_OVERDUE",
"RETRY_ERROR"
],
"example": "SCHEDULE"
},
"PaymentOrderResponse": {
"type": "object",
"properties": {
"account_id": {
"$ref": "#/components/schemas/AccountID"
},
"recurrence_id": {
"$ref": "#/components/schemas/RecurrenceID"
},
"end_to_end_id": {
"$ref": "#/components/schemas/EndToEndID"
},
"status": {
"$ref": "#/components/schemas/PaymentOrderStatus"
},
"type": {
"$ref": "#/components/schemas/PaymentOrderType"
},
"transaction_identification": {
"$ref": "#/components/schemas/TransactionIdentification"
},
"calendar": {
"type": "object",
"properties": {
"due_date": {
"$ref": "#/components/schemas/CalendarDueDate"
},
"working_day": {
"$ref": "#/components/schemas/CalendarWorkingDay"
}
}
},
"amount": {
"$ref": "#/components/schemas/Amount"
},
"dynamic_amount": {
"$ref": "#/components/schemas/DynamicAmount"
},
"additional_information": {
"$ref": "#/components/schemas/AdditionalInformation"
},
"max_payment_amount": {
"$ref": "#/components/schemas/MaxPaymentAmount"
},
"min_amount_allowed": {
"$ref": "#/components/schemas/MinPaymentAmount"
},
"reason": {
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/PaymentOrderReason"
},
"description": {
"$ref": "#/components/schemas/PaymentOrderReasonDescription"
}
}
},
"payer": {
"oneOf": [
{
"$ref": "#/components/schemas/Payer"
},
{
"$ref": "#/components/schemas/NullType"
}
]
},
"payee": {
"$ref": "#/components/schemas/Payee"
},
"debtor": {
"$ref": "#/components/schemas/Debtor"
},
"created_at": {
"$ref": "#/components/schemas/CreatedAt"
},
"updated_at": {
"$ref": "#/components/schemas/UpdatedAt"
},
"taxes": {
"$ref": "#/components/schemas/TaxesWithCategory"
}
}
},
"PersonType": {
"type": "string",
"description": "Person type: \n* `LEGAL_PERSON` - An actual person with legal rights.\n* `NATURAL_PERSON` - An entity, such as an organization or company.\n",
"enum": [
"LEGAL_PERSON",
"NATURAL_PERSON"
],
"example": "NATURAL_PERSON"
},
"QueryFilters": {
"type": "object",
"properties": {
"label": {
"type": "string",
"description": "Filter label"
},
"value": {
"type": "string",
"description": "Filter value"
},
"operator": {
"type": "string",
"description": "Filter operator"
}
},
"description": "Filters used in query",
"example": {
"label": "status",
"value": "CREATED"
}
},
"RecordsWithCategory": {
"type": "object",
"properties": {
"tax_type": {
"$ref": "#/components/schemas/TaxType"
},
"tax_category": {
"$ref": "#/components/schemas/TaxCategory"
},
"amount": {
"$ref": "#/components/schemas/TaxAmount"
}
}
},
"RecurrenceID": {
"type": "string",
"description": "BACEN recurrence ID",
"example": "RN000000012025050500012345678"
},
"TaxAmount": {
"type": "number",
"description": "Tax amount. Must be greater than zero.",
"example": 1050.44
},
"TaxCategory": {
"type": "string",
"description": "Tax category: \n* `INF` (Conta e Ordem) = Tax information\n* `COR` (Informar no momento da emissão)) = Corrected tax\n",
"example": "INF",
"enum": [
"INF",
"COR"
]
},
"TaxIdentifier": {
"type": "string",
"description": "Tax identifier, referring to the NF-e, NFS-e or aggregating tax document. \n\nIn Brazil, NF-e and NFS-e are the two primary types of mandatory electronic invoices (Notas Fiscais) used for tax compliance.\n* NF-e (Nota Fiscal Eletrônica): Used for the sale and movement of physical goods or products. It is regulated at the state level by SEFAZ (SEFAZ (Secretaria da Fazenda) is the State Department of Finance in Brazil.) and travels with the goods.\n* NFS-e (Nota Fiscal de Serviços Eletrônica): Used for the provision of services (e.g., consulting, repairs, digital subscriptions). It is regulated by individual city governments.\n\nThe value entered must correspond to the tax document used for calculating the IBS and CBS taxes associated with the transaction.\n",
"example": "IS0435879820240605bcdb1fhn43a",
"maxLength": 50
},
"TaxType": {
"type": "string",
"description": "Tax type:\n* `IBS` = Goods and services tax. A state and municipal tax that unifies and replaces the main subnational consumption taxes (state ICMS and municipal ISS).\n* `CBS` = Contribution on goods and services. A federal tax that consolidates and replaces previous federal social contributions and taxes (PIS, Cofins, and IPI)\n",
"enum": [
"CBS",
"IBS"
],
"example": "IBS"
},
"TaxesWithCategory": {
"description": "Now only available on ext env and just for direct participants. Tax information related to the transaction.",
"type": "object",
"properties": {
"tax_identifier": {
"$ref": "#/components/schemas/TaxIdentifier"
},
"records": {
"type": "array",
"description": "Tax records. It is **REQUIRED** to pass a minimum of 2 objects and a maximum of 4 objects, at least one with `CBS` tax type and at least one with `IBS` tax type.\n",
"items": {
"$ref": "#/components/schemas/RecordsWithCategory"
}
}
}
},
"TransactionIdentification": {
"type": "string",
"description": "Transaction ID from a successful payment. **REQUIRED** for the `AUT3` journey.",
"maxLength": 35,
"example": "ttx2020010300000000000000000000001"
},
"UpdatedAt": {
"type": "string",
"description": "Scheduled item last updated time, RFC 3339 format",
"example": "2024-11-14T17:54:40Z"
}
},
"responses": {
"400BadRequest": {
"description": "Bad request",
"headers": {
"x-cid": {
"description": "Request tracking ID.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
}
}
}
},
"401Unauthorized": {
"description": "Unauthorized. Missing or invalid authentication token.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
}
}
}
},
"404NotFound": {
"description": "Not found",
"headers": {
"x-cid": {
"description": "Request tracking ID.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
}
}
}
},
"500InternalServer": {
"description": "Internal Server Error",
"headers": {
"x-cid": {
"description": "Request tracking ID.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
}
}
}
}
}
},
"paths": {
"/inst-pull-pay/v1/pix/automatic/payment/order": {
"get": {
"summary": "List payment orders",
"description": "List payment orders. By default, payment orders from the last 30 days with 20 records per page are returned, but you can use the `beginDate` and `endDate` query parameters to specify a different date range.\n",
"operationId": "list-payment-orders",
"tags": [
"Automatic Pix data"
],
"parameters": [
{
"$ref": "#/components/parameters/RecurrenceIdQuery"
},
{
"$ref": "#/components/parameters/RoleTypeQuery"
},
{
"$ref": "#/components/parameters/PerPageQuery"
},
{
"$ref": "#/components/parameters/AuthHeader"
},
{
"$ref": "#/components/parameters/PaymentOrderStatusQuery"
},
{
"$ref": "#/components/parameters/AfterIdQuery"
},
{
"$ref": "#/components/parameters/BeginDateQueryOptional"
},
{
"$ref": "#/components/parameters/EndDateQueryOptional"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PaymentOrderResponse"
}
},
"page_size": {
"$ref": "#/components/schemas/PageSize"
},
"number_elements": {
"$ref": "#/components/schemas/NumberElements"
},
"next_page": {
"$ref": "#/components/schemas/NextPage"
},
"last_id": {
"$ref": "#/components/schemas/LastID"
},
"filters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/QueryFilters"
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
},
"500": {
"$ref": "#/components/responses/500InternalServer"
}
}
}
}
}
}
```