---
updatedAt: 2026-05-15T20:15:05.000Z
---
Fetch the complete documentation index at: https://developers.pismo.io/pismo-docs/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.
# List recurrences
List Pix Automatic recurrences. By default, recurrences 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.0.1",
"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"
}
},
"AutomaticPixExecutionStatusOptionalQuery": {
"name": "status",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"CREATED",
"PENDING",
"EXPIRED",
"ACCEPTED",
"REJECTED",
"IN_PROGRESS",
"FINISHED",
"CANCELLED",
"RECEIVED",
"CONFIRMED",
"WAITING_CUSTOMER"
]
},
"description": "Execution status filter",
"example": "CREATED"
},
"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"
},
"PerPageQuery": {
"name": "perPage",
"in": "query",
"description": "Per page amount (min=1, max=100). Default is `20`.",
"required": false,
"schema": {
"type": "string"
}
},
"RoleTypeQuery": {
"name": "roleType",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"PAYEE",
"PAYER"
]
},
"description": "Role type filter."
}
},
"schemas": {
"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"
},
"AllowAttemptsAfterExpiration": {
"type": "boolean",
"description": "Will charge continue after due date?\n\nIf `true` the recurence will receive a `recurrence_id` starting with `RR`. Otherwise, it will start with `RN`.\n"
},
"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",
"description": "The IBGE (Instituto Brasileiro de Geografia e Estatística) city code.",
"example": "3550308"
},
"ContractID": {
"type": "string",
"description": "Payee-created external ID for their reference.\n",
"maxLength": 35,
"example": "5509-uroo-78944-9987"
},
"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"
},
"FirstPaymentDate": {
"type": "string",
"format": "datetime",
"description": "First charge/payment date. Format = yyyy-mm-dd",
"example": "2025-04-25"
},
"FrequencyType": {
"type": "string",
"description": "Recurrence payment type",
"enum": [
"WEEK",
"MONTH",
"QUARTER",
"SEMESTER",
"YEAR"
],
"example": "MONTH"
},
"JourneyType": {
"type": "string",
"description": "Recurrence payment type: \n\n `AUT1` - Bank notification. If the merchant has the payer's banking information, a push notification can be sent directly to the payer's bank app, prompting them to authorize the recurring payment.\n \n `AUT2` - Authorization via QR code. Payer scans a merchant provided QR code to authorize recurring payments. This method does not initiate an immediate payment, allowing the first payment to be scheduled for a later date.\n \n `AUT3` - Authorization via QR code with first payment. Similar to the second method, but the QR code includes information for both the authorization and the initial payment, enabling the payer to authorize the recurring payment and make the first payment in a single step.\n \n `AUT4` - Post-payment sign-up path. After completing a one-time payment via QR code, the payer is offered the option to authorize recurring payments for future transactions\n",
"enum": [
"AUT1",
"AUT2",
"AUT3",
"AUT4"
],
"example": "AUT1"
},
"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
},
"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"
}
}
},
"PismoRecurrenceID": {
"type": "string",
"description": "Pismo recurrence ID.",
"example": "49940-9995-u88"
},
"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"
}
}
},
"Recurrence": {
"type": "object",
"properties": {
"id": {
"$ref": "#/components/schemas/PismoRecurrenceID"
},
"role_type": {
"$ref": "#/components/schemas/RoleType"
},
"details": {
"$ref": "#/components/schemas/RecurrenceDetails"
},
"created_at": {
"$ref": "#/components/schemas/CreatedAt"
},
"updated_at": {
"$ref": "#/components/schemas/UpdatedAt"
},
"status": {
"$ref": "#/components/schemas/RecurrenceStatus"
},
"taxes": {
"$ref": "#/components/schemas/TaxesWithCategory"
}
}
},
"RecurrenceDescription": {
"type": "string",
"description": "Recurrence payment description",
"maxLength": 35,
"example": "Gym membership"
},
"RecurrenceDetails": {
"type": "object",
"properties": {
"recurrence_id": {
"$ref": "#/components/schemas/RecurrenceID"
},
"journey_type": {
"$ref": "#/components/schemas/JourneyType"
},
"contract_id": {
"$ref": "#/components/schemas/ContractID"
},
"description": {
"$ref": "#/components/schemas/RecurrenceDescription"
},
"amount": {
"$ref": "#/components/schemas/Amount"
},
"maximum_debit_allowed": {
"$ref": "#/components/schemas/MaxPaymentAmount"
},
"minimum_debit_allowed": {
"$ref": "#/components/schemas/MinPaymentAmount"
},
"frequency_type": {
"$ref": "#/components/schemas/FrequencyType"
},
"allow_attempts_after_expiration": {
"$ref": "#/components/schemas/AllowAttemptsAfterExpiration"
},
"first_payment_date": {
"$ref": "#/components/schemas/FirstPaymentDate"
},
"payee": {
"$ref": "#/components/schemas/Payee"
},
"payer": {
"$ref": "#/components/schemas/Payer"
},
"debtor": {
"$ref": "#/components/schemas/Debtor"
}
}
},
"RecurrenceID": {
"type": "string",
"description": "BACEN recurrence ID",
"example": "RN000000012025050500012345678"
},
"RecurrenceStatus": {
"type": "string",
"description": "Recurrence status",
"enum": [
"CREATED",
"ACCEPTED",
"APPROVED",
"REJECTED",
"FINISHED",
"EXPIRED",
"CANCELLED"
],
"example": "CREATED"
},
"RoleType": {
"type": "string",
"description": "Role type",
"enum": [
"PAYEE",
"PAYER"
]
},
"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"
}
}
}
},
"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": {
"get": {
"summary": "List recurrences",
"description": "List Pix Automatic recurrences. By default, recurrences 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-recurrence-automatic",
"tags": [
"Automatic Pix data"
],
"parameters": [
{
"$ref": "#/components/parameters/RoleTypeQuery"
},
{
"$ref": "#/components/parameters/PerPageQuery"
},
{
"$ref": "#/components/parameters/AfterIdQuery"
},
{
"$ref": "#/components/parameters/BeginDateQueryOptional"
},
{
"$ref": "#/components/parameters/EndDateQueryOptional"
},
{
"$ref": "#/components/parameters/AutomaticPixExecutionStatusOptionalQuery"
},
{
"$ref": "#/components/parameters/AuthHeader"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Recurrence"
}
},
"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"
}
}
}
}
}
}
```