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

# Create recurrence

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

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.  

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

## Headers

- `x-account-id` 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?
  - `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 — Cardholder government document number. This can be from any document that identifies the cardholder such as a Tax ID, State ID, or driver's license.
    - `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 — Cardholder government document number. This can be from any document that identifies the cardholder such as a Tax ID, State ID, or driver's license.
    - `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/current account. 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 /> `SVGS` - Savings account<br /> `TRAN` - Payment account. Payment institutions offer payment accounts to move funds and make payments, while banks offer checking accounts that include full financial services such as credit and investments.<br /> `SLRY` - Salary account. Employer deposits a fixed amount every month.<br />
    - `city_code` string — The <a href='https://www.ibge.gov.br/explica/codigos-dos-municipios.php' target="_blank">IBGE</a> (Instituto Brasileiro de Geografia e Estatística) city code.
  - `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, double — Fee amount.
  - `min_payment_amount` number — Minimum payment amount for dynamic amount recurrences, defined by payee.
  - `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 NFe, NFSe 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 For more information, refer to [Pix automatic use cases (journeys)](https://developers.pismo.io/pismo-docs/docs/pix-automatic-beta-copy-2#pix-automatic-use-cases-journeys).
  - `contract_id` string — Payee-created external ID for their reference.
  - `description` string — Recurrence payment description
  - `amount` number, double — Fee amount.
  - `min_payment_amount` number — Minimum payment amount for dynamic amount recurrences, defined by payee.
  - `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?
  - `is_working_days` boolean — If the recurrence will only execute on working days
  - `expiration_date` string — Card expiration date (format = yymm). If passed, the card expiration date is not calculated using the "Card expiration (# of months)" program parameter.
  - `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 — Cardholder government document number. This can be from any document that identifies the cardholder such as a Tax ID, State ID, or driver's license.
    - `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/current account. 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 /> `SVGS` - Savings account<br /> `TRAN` - Payment account. Payment institutions offer payment accounts to move funds and make payments, while banks offer checking accounts that include full financial services such as credit and investments.<br /> `SLRY` - Salary account. Employer deposits a fixed amount every month.<br />
  - `payer` Payer
    - `document_number` string, required — Cardholder government document number. This can be from any document that identifies the cardholder such as a Tax ID, State ID, or driver's license.
    - `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/current account. 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 /> `SVGS` - Savings account<br /> `TRAN` - Payment account. Payment institutions offer payment accounts to move funds and make payments, while banks offer checking accounts that include full financial services such as credit and investments.<br /> `SLRY` - Salary account. Employer deposits a fixed amount every month.<br />
    - `city_code` string — The <a href='https://www.ibge.gov.br/explica/codigos-dos-municipios.php' target="_blank">IBGE</a> (Instituto Brasileiro de Geografia e Estatística) city code.
  - `debtor` Debtor
    - `document_number` string, required — Cardholder government document number. This can be from any document that identifies the cardholder such as a Tax ID, State ID, or driver's license.
    - `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' | 'EXPIRED' | 'CANCELLED' | 'FINISHED' — Recurrence status * `CREATED` - Recurrence created, waiting on journey acceptance. * `ACCEPTED` - Payer accepted recurrence, awaiting confirmation from receiver's PSP. * `APPROVED` - Payer accepted recurrence and receiver's PSP confirmed. * `REJECTED` - Payer or receiver's PSP rejected recurrence during `ACCEPTED` validation. For example: receiver's account is inactive. * `EXPIRED` - Recurrence expired after last scheduled payment date. * `CANCELLED` - Payer or reciever cancelled recurrence. * `FINISHED` - Deprecated
  - `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[]
    - `mti` string — Message type ID. For example: `0100` = auth. request, `0110`` = auth. response, `0120` = auth. advice. For more information, see [MTI](https://en.wikipedia.org/wiki/ISO_8583#Message_type_indicator_(MTI)).
    - `authorization_code` string — Authorization code.
    - `response_code` string — Network two-digit response code. For example: 00 = approve, 51 = insufficient funds, 57 = card not active, 96 = system failure, etc. For more information, see [Validation codes for authorization events](https://developers.pismo.io/pismo-docs/docs/validation-codes-for-authorization-events). If `approve` = `false`, you can use this value to respond to the network.
    - `authorization_date_time` string — Authorization date and time in Coordinated Universal Time (UTC), i.e., 2020-01-01T10:10:00.000-03:00.
    - `custom_code` 'FL2' | 'FL8' | 'FLB' | 'FLE' | 'DCM' | 'VMN' | '998' | 'LUD' | 'LUE' | 'LUT' | 'LGE' | '810' | 'PFT' | 'IAT' | 'BND' | 'ANF' | 'CTE' | 'CED' | 'ZBD' | 'FRB' | 'UBT' | 'FL6' | 'BNF' | 'BNP' | 'BNR' | 'VED' | 'BNU' | 'VEV' | 'UBN' | 'CSU' | 'NPL' | 'OP1' | 'TNF' | 'Z26' | 'Z24' | 'Z29' | 'Z23' | 'Z22' — Internal custom code generated in authorization flow for declined requests, indicating the reason the request was declined. For more information, see [authorization validations](https://developers.pismo.io/pismo-docs/docs/validation-codes-for-authorization-events#authorization-validations).
    - `match_address` boolean — Is cardholder address street and number the same as that contained on the platform?
    - `match_postal_code` boolean — Is cardholder postal code the same as the one contained on the platform?
    - `postal_five_digits` boolean — Is this a valid postal code with five digits?
    - `no_address_data` boolean — Is address registered on platform?
    - `authorization_id` integer — Authorization ID
    - `account_id` integer — Account ID
    - `installment_value` string — Installment value. If there are no installments, this is the same as `contract_amount`.
    - `interest_rate` number — Monthly interest rate
    - `number_of_installments` number — Number of installments
    - `contract_amount` string — Transaction value
    - `crediario_responses` CrediarioResponse[] — If there is more than one installment, this is the data for them.
      - `installmentValue` string — Installment value
      - `monthlyInterestRate` string — Monthly interest rate
      - `totalAmount` string — Total amount
      - `numberOfInstallments` string — Number of installments
      - `feeAmount` string — Fee amount
      - `taxesAmount` string — Taxes amount
      - `taxesPercentageOfTotalAmount` string — Taxes percentage of total amount
      - `feePercentageOfTotalAmount` string — Fee percentage of total amount
      - `planType` string — Plan type - with interest (20), without interest(21) or a crediario type(25)
      - `annualInterestRate` string — Annual interest rate
      - `monthlyTotalEffectiveCost` string — Monthly total effective cost
      - `annualTotalEffectiveCost` string — Aannual total effective cost
      - `installmentDate` string — Installment date - format = yyyymmdd
      - `insurance` string — Insurance
      - `insurancePercentageOfTotalAmount` string — Insurance percentage of total amount
      - `other` string — Any other added values, if applicable, that the cardholder is paying
      - `otherPercentageOfTotalAmount` string — Other percentage of total amount
      - `totalAmountToMerchant` string — Total amount to be paid to merchant (purchase amount)
      - `merchantAmountPercentage` string — Percentage of the total amount to be paid to merchant
      - `reservedForFutureUse` string — Reserved for future use
  - `created_at` string, date-time — Datetime program calendar strategy was created. Format = YYYY-MM-DDTHH:MM:SS:MM.
  - `updated_at` string, date-time — Datetime program calendar strategy was updated. Format = YYYY-MM-DDTHH:MM:SS:MM
  - `taxes` TaxesWithCategory — Now only available on ext env and just for direct parciapants. Tax information related to the transaction.
    - `tax_identifier` string — Tax identifier, referring to the NFe, NFSe 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` — Access token is missing or invalid
- `404` — Not Found
- `500` — Internal server error

---

[API](https://skmtc.net/pismo/apis/platform-authentication.md) · [All operations](https://skmtc.net/pismo/apis/platform-authentication/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pismo/platform-authentication/revisions/935b62e16de4/schema)