---
title: "Create recurrence"
method: POST
path: "/inst-pull-pay/v1/pix/automatic"
tags: ["Automatic Pix"]
---

# Create recurrence

`POST /inst-pull-pay/v1/pix/automatic`

## Request

- Base URL: `https://sandbox-cdn.pismolabs.io`
- URL: `https://sandbox-cdn.pismolabs.io/inst-pull-pay/v1/pix/automatic`
- Auth: none declared. Required headers: `x-account`, `Idempotency-Key`

Initiate a payment request to create a Pix Automatic recurrence payment authorization. 

The Central Bank of Brazil (BACEN) created Pix Automatic - a feature that allows for scheduled and automatic recurring transfers.  

BACEN rules state that a recurrence must support retry attempts to allow execution of additional charges in case the original payment is not completed.

**Retries flow** 

* If the payment order is not paid by 22:00 on the due date, and the recurrence allows retries, Pismo automatically generates a new payment order for that unpaid cycle.

* The new payment order is created with type = `RETRY_OVERDUE`, and its due date is set to D+2, in compliance with Central Bank requirements. Retries can occur up to 3 times, within a maximum period of 7 days after the original due date.

* After these 3 retry attempts, the payment order cycle can no longer be processed via the automatic Pix flow. The payee must manage further collection outside of this flow.

For more information, refer to [Pix Automatic](https://developers.pismo.io/pismo-docs/docs/pix-automatic)

## Headers

- `x-account` integer, required
- `Idempotency-Key` string, required
- `x-tenant` string

## Request body

- RecurrenceRequest: Recurrence request
  - `contract_id` string, required: Payee-created external ID for their reference.
  - `description` string, required: Recurrence payment description
  - `frequency_type` 'WEEK' | 'MONTH' | 'QUARTER' | 'SEMESTER' | 'YEAR', required: Recurrence payment type
  - `allow_attempts_after_expiration` boolean, required: Will charge continue after due date? If `true` the recurence will receive a `recurrence_id` starting with `RR`. Otherwise, it will start with `RN`.
  - `first_payment_date` string, datetime, required: First charge/payment date, must be more than 2 days ahead the recurrence creation date. Format = yyyy-mm-dd
  - `debtor` Debtor, required
    - `document_number` string, required: 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.
    - `document_type` 'LEGAL_PERSON' | 'NATURAL_PERSON', required: Person type: * `LEGAL_PERSON` - An actual person with legal rights. * `NATURAL_PERSON` - An entity, such as an organization or company.
    - `name` string, required: Name
  - `payer` Payer, required
    - `document_number` string, required: 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.
    - `document_type` 'LEGAL_PERSON' | 'NATURAL_PERSON', required: Person type: * `LEGAL_PERSON` - An actual person with legal rights. * `NATURAL_PERSON` - An entity, such as an organization or company.
    - `name` string, required: Name
    - `bank` string, required: <a href="https://bank.codes/numero-do-banco/bank/banco-central-do-brasil/" target="_blank">ISPB (Identifcador do Sistema de Pagamento Brazil)</a> - the Brazilian Payment System ID for the receiving bank, an 8-digit value.
    - `branch` string, required: This could be a bank-assigned branch ID or the branch's ISPB number.
    - `account_number` string, required: Payer's account number.
    - `account_type` 'CACC' | 'SLRY' | 'SVGS' | 'TRAN': Account type: <br /> `CACC` - Checking account<br /> `SVGS` - Savings account<br /> `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. <br /> `SLRY` - Salary account. Employer deposits a fixed amount every month.<br />
    - `city_code` string: An <a href='https://www.ibge.gov.br/explica/codigos-dos-municipios.php' target="_blank">IBGE</a> 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.
  - `dynamic_amount` boolean: Does recurrence have a dynamic amount? If `true`, `min_payment_amount` is **REQUIRED**. If `false`, `amount` is **REQUIRED**. Default is `false`.
  - `amount` number: Amount to be transferred.
  - `min_payment_amount` number: Payee-defined minimum payment amount for dynamic amount recurrences.
  - `last_payment_date` string, datetime: Last charge/payment date. Format = yyyy-mm-dd
  - `expiration_date` string, datetime: Authorization expiration date, must be at least 2 days before the `first_payment_date`. RFC 3339 value. Format = YYYY-MM-DDThh:mm:ss.SSSZ If not passed, the `expiration_date` is automatically generated, up to 2 days before the `first_payment_date`, or a maximum of 30 days from the current date, whichever is due first
  - `taxes` TaxesWithOutCategory: Only available in EXT environment for direct parciapants. Tax information related to the transaction.
    - `tax_identifier` string: Tax identifier, referring to the NF-e, NFS-e or aggregating tax document. In Brazil, NF-e and NFS-e are the two primary types of mandatory electronic invoices (Notas Fiscais) used for tax compliance. * 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. * 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. The value entered must correspond to the tax document used for calculating the IBS and CBS taxes associated with the transaction.
    - `records` RecordsWithOutCategory[]: Tax records. At least 2 objects are **REQUIRED** - at least one with `CBS` tax type and at least one with `IBS` tax type
      - `tax_type` 'CBS' | 'IBS': Tax type: * `IBS` = Goods and services tax. A state and municipal tax that unifies and replaces the main subnational consumption taxes (state ICMS and municipal ISS). * `CBS` = Contribution on goods and services. A federal tax that consolidates and replaces previous federal social contributions and taxes (PIS, Cofins, and IPI)
      - `amount` number: Tax amount. Must be greater than zero.

## Response `200`

OK

- RecurrenceResponse: Recurrence response
  - `recurrence_id` string: BACEN recurrence ID
  - `journey_type` 'AUT1' | 'AUT2' | 'AUT3' | 'AUT4': Recurrence payment type: `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. `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. `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. `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
  - `contract_id` string: Payee-created external ID for their reference.
  - `description` string: Recurrence payment description
  - `amount` number: Amount to be transferred.
  - `min_payment_amount` number: Payee-defined minimum payment amount for dynamic amount recurrences.
  - `max_payment_amount` number: Payer-defined maximum payment amount for dynamic amount recurrences.
  - `dynamic_amount` boolean: Does recurrence have a dynamic amount? If `true`, `min_payment_amount` is **REQUIRED**. If `false`, `amount` is **REQUIRED**. Default is `false`.
  - `frequency_type` 'WEEK' | 'MONTH' | 'QUARTER' | 'SEMESTER' | 'YEAR': Recurrence payment type
  - `allow_attempts_after_expiration` boolean: Will charge continue after due date? If `true` the recurence will receive a `recurrence_id` starting with `RR`. Otherwise, it will start with `RN`.
  - `is_working_days` boolean: If the recurrence will only execute on working days
  - `expiration_date` string, datetime: Authorization expiration date. RFC 3339 value. Format = YYYY-MM-DDThh:mm:ss.SSSZ
  - `first_payment_date` string, datetime: First charge/payment date. Format = yyyy-mm-dd
  - `last_payment_date` string, datetime: Last charge/payment date. Format = yyyy-mm-dd
  - `payee` Payee
    - `name` string, required: Name
    - `document_number` string, required: 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.
    - `document_type` 'LEGAL_PERSON' | 'NATURAL_PERSON', required: Person type: * `LEGAL_PERSON` - An actual person with legal rights. * `NATURAL_PERSON` - An entity, such as an organization or company.
    - `bank` string, required: <a href="https://bank.codes/numero-do-banco/bank/banco-central-do-brasil/" target="_blank">ISPB (Identifcador do Sistema de Pagamento Brazil)</a> - the Brazilian Payment System ID for the receiving bank, an 8-digit value.
    - `branch` string, required: This could be a bank-assigned branch ID or the branch's ISPB number.
    - `account_number` string, required: Payer's account number.
    - `account_type` 'CACC' | 'SLRY' | 'SVGS' | 'TRAN', required: Account type: <br /> `CACC` - Checking account<br /> `SVGS` - Savings account<br /> `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. <br /> `SLRY` - Salary account. Employer deposits a fixed amount every month.<br />
  - `payer` Payer
    - `document_number` string, required: 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.
    - `document_type` 'LEGAL_PERSON' | 'NATURAL_PERSON', required: Person type: * `LEGAL_PERSON` - An actual person with legal rights. * `NATURAL_PERSON` - An entity, such as an organization or company.
    - `name` string, required: Name
    - `bank` string, required: <a href="https://bank.codes/numero-do-banco/bank/banco-central-do-brasil/" target="_blank">ISPB (Identifcador do Sistema de Pagamento Brazil)</a> - the Brazilian Payment System ID for the receiving bank, an 8-digit value.
    - `branch` string, required: This could be a bank-assigned branch ID or the branch's ISPB number.
    - `account_number` string, required: Payer's account number.
    - `account_type` 'CACC' | 'SLRY' | 'SVGS' | 'TRAN': Account type: <br /> `CACC` - Checking account<br /> `SVGS` - Savings account<br /> `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. <br /> `SLRY` - Salary account. Employer deposits a fixed amount every month.<br />
    - `city_code` string: An <a href='https://www.ibge.gov.br/explica/codigos-dos-municipios.php' target="_blank">IBGE</a> 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.
  - `debtor` Debtor
    - `document_number` string, required: 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.
    - `document_type` 'LEGAL_PERSON' | 'NATURAL_PERSON', required: Person type: * `LEGAL_PERSON` - An actual person with legal rights. * `NATURAL_PERSON` - An entity, such as an organization or company.
    - `name` string, required: Name
  - `status` 'CREATED' | 'ACCEPTED' | 'APPROVED' | 'REJECTED' | 'FINISHED' | 'EXPIRED' | 'CANCELLED': Recurrence status
  - `reason_code` 'ACCL' | 'CPCL' | 'DCSD' | 'ERSL' | 'FRUD' | 'PCFD' | 'SLCR' | 'SLDB' | 'OTHS' | 'NRES': Cancellation reason code: * `ACCL` - Paying receiving user's account cancelled * `CPCL` - Receiving company closure * `DCSD` - Paying user death * `ERSL` - Receiving user, or their participant, request cancelled due to confirmation request error * `FRUD` - Fraud * `PCFD` - Receiving user participant request because the same recurrence was confirmed another way, for example, via QR code * `SLCR` - Receiving user request * `SLDB` - Paying user request * `OTHS` - Requested by either the payer's participant or the receiver's participant for other reasons not specified in the previous categories * `NRES` - Receiving PSP request due to lack of response to pain.009 within the regulatory period
  - `transaction_identification` string: Recurrence transaction ID.
  - `authorizations` AuthorizationResponse[]
    - `id` string: Authorization ID the same as BACEN (Brazil Central Bank) IdSoliReq (request identification code)
    - `expiration_date` string, datetime: Authorization expiration date. RFC 3339 value. Format = YYYY-MM-DDThh:mm:ss.SSSZ
    - `creted_at` string, datetime: Created at datetime. RFC 3339 format
    - `updated_at` string: Scheduled item last updated time, RFC 3339 format
    - `reason_code` 'AC01' | 'AC04' | 'AC06' | 'AP01' | 'AP02' | 'AP03' | 'AP04' | 'AP05' | 'AP06' | 'AP07' | 'AP08' | 'AP09' | 'AP10' | 'AP11' | 'AP12' | 'AP13' | 'AP14' | 'AP15' | 'CH16' | 'MD01' | 'MD20': Authorization reason code. **Note:** "pain.009" is a message sent to the payer when the payee starts a #1 journey (`AUT1`) Automatic Pix recurrence * `AC01` - Account not found or not belonging to the paying user * `AC04` - Paying user's transactional account is closed * `AC06` - Paying user's transactional account is blocked * `AP01` - Discrepancy in the field for updating periodic payments recurrence data and the periodic payments recurrence status - lack of synchronization * `AP02` - Paying user's CPF/CNPJ not found or different from the one in the original pain.009. Or, in the case of cancellation, the paying user's CPF/CNPJ does not match the one contained in the perioduc payments recurrence data. * `AP03` - Paying user's branch not found * `AP04` - Invalid recurrence ID or does not match the original * `AP05` - Inconsistent recurrence status for periodic payments * `AP06` - Receiving user's CPF/CNPJ is different from the one in the pain.009 or the payload. Or, in the case of cancellation, the receiving user's CPF/CNPJ does not match the one contained in the periodic payments recurrence data. * `AP07` - Paying user's recurrence confirmation performed after the confirmation request's expiration or cancellation (pain.009) * `AP08` - First immediate payment associated with the recurrence was not identified. (Valid only for Authorization Journey 3 (`AUT3`)) * `AP09` - Recurrence confirmation request for periodic payments was not identified to enable its cancellation * `AP10` - Cancellation requestor's CPF/CNPJ does not match the the paying/receiving user's or the paying/receiving PSP's identification contained in the periodic payments recurrence data. * `AP11` - Paying PSP's ISPB diverges from the information contained in the recurrence for periodic payments * `AP12` - Receiving PSP's ISPB diverges from the information contained in the recurrence for periodic payments * `AP13` = Paying user rejects periodic payments recurrence confirmation request due to receiving user non-recognition * `AP14` - Paying user rejects periodic payments recurrence confirmation request due to receiving user's lack of interest in using Pix Automatic * `AP15` - Paying user's participant rejects recurrence confirmation request for periodic payments as they chose not to offer Pix Automatic usage for corporate clients * `CH16` - Incorrect or incompatible message content with business rules * `MD01` - Cancellation request's recurrence object does not exist. Should not be used for cancellation requests of pain.009 with status = `PDNG`. That is, a recurrence with status = `PDNG` should be considered as an existing recurrence. * `MD20` - Cancellation request's recurrence object has already expired.
    - `status` 'CREATED' | 'RECEIVED' | 'ACCEPTED' | 'REJECTED' | 'EXPIRED' | 'CANCELLED': Authorization status
    - `payer` Payer
      - `document_number` string, required: 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.
      - `document_type` 'LEGAL_PERSON' | 'NATURAL_PERSON', required: Person type: * `LEGAL_PERSON` - An actual person with legal rights. * `NATURAL_PERSON` - An entity, such as an organization or company.
      - `name` string, required: Name
      - `bank` string, required: <a href="https://bank.codes/numero-do-banco/bank/banco-central-do-brasil/" target="_blank">ISPB (Identifcador do Sistema de Pagamento Brazil)</a> - the Brazilian Payment System ID for the receiving bank, an 8-digit value.
      - `branch` string, required: This could be a bank-assigned branch ID or the branch's ISPB number.
      - `account_number` string, required: Payer's account number.
      - `account_type` 'CACC' | 'SLRY' | 'SVGS' | 'TRAN': Account type: <br /> `CACC` - Checking account<br /> `SVGS` - Savings account<br /> `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. <br /> `SLRY` - Salary account. Employer deposits a fixed amount every month.<br />
      - `city_code` string: An <a href='https://www.ibge.gov.br/explica/codigos-dos-municipios.php' target="_blank">IBGE</a> 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.
  - `created_at` string, datetime: Created at datetime. RFC 3339 format
  - `updated_at` string: Scheduled item last updated time, RFC 3339 format
  - `taxes` TaxesWithCategory: Now only available on ext env and just for direct participants. Tax information related to the transaction.
    - `tax_identifier` string: Tax identifier, referring to the NF-e, NFS-e or aggregating tax document. In Brazil, NF-e and NFS-e are the two primary types of mandatory electronic invoices (Notas Fiscais) used for tax compliance. * 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. * 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. The value entered must correspond to the tax document used for calculating the IBS and CBS taxes associated with the transaction.
    - `records` RecordsWithCategory[]: 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.
      - `tax_type` 'CBS' | 'IBS': Tax type: * `IBS` = Goods and services tax. A state and municipal tax that unifies and replaces the main subnational consumption taxes (state ICMS and municipal ISS). * `CBS` = Contribution on goods and services. A federal tax that consolidates and replaces previous federal social contributions and taxes (PIS, Cofins, and IPI)
      - `tax_category` 'INF' | 'COR': Tax category: * `INF` (Conta e Ordem) = Tax information * `COR` (Informar no momento da emissão)) = Corrected tax
      - `amount` number: Tax amount. Must be greater than zero.

## Other responses

- `400`: Bad request
- `401`: Unauthorized. Missing or invalid authentication token.
- `404`: Not found
- `500`: Internal Server Error

---

[API](https://skmtc.dev/pismo/apis/instant-payments-automatic-pix.md) - [All operations](https://skmtc.dev/pismo/apis/instant-payments-automatic-pix/llms.txt) - [OpenAPI document](https://skmtc.dev/pismo/apis/instant-payments-automatic-pix/revisions/88d97a2eb4f6?raw)