Sign in

v1

latestOpenAPI 3.1.0Copyright Pismo2026-07-247702,7523.1 MB
Automatic Pix

Create recurrence

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

post/inst-pull-pay/v1/pix/automatic

Headers

x-account-idinteger required

Account ID

Idempotency-Keystring required

A unique ID to ensure the operation remains idempotent, allowing for operation repitition without causing unintended effects or duplication. An idempotent operation is one that can be applied multiple times, yet the outcome remains the same. it ensures that network errors, retries, or failures can occur without introducing inconsistencies.

x-tenantstring

Organization ID

Request body

contract_idstring required

Payee-created external ID for their reference.

descriptionstring required

Recurrence payment description

frequency_type'WEEK' | 'MONTH' | 'QUARTER' | 'SEMESTER' | 'YEAR' required

Recurrence payment type

allow_attempts_after_expirationboolean required

Will charge continue after due date?

first_payment_datestring datetime required

First charge/payment date, must be more than 2 days ahead the recurrence creation date. Format = yyyy-mm-dd

dynamic_amountboolean

Does recurrence have a dynamic amount?

If true, min_payment_amount is REQUIRED.

If false, amount is REQUIRED. Default is false.

amountnumber double

Fee amount.

min_payment_amountnumber

Minimum payment amount for dynamic amount recurrences, defined by payee.

last_payment_datestring datetime

Last charge/payment date. Format = yyyy-mm-dd

expiration_datestring 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

Example request

{
  "contract_id": "5509-uroo-78944-9987",
  "description": "Gym membership",
  "frequency_type": "MONTH",
  "first_payment_date": "2025-04-25",
  "debtor": {
    "document_number": "7777888hh",
    "document_type": "NATURAL_PERSON",
    "name": "Paul Bearer"
  },
  "payer": {
    "document_number": "7777888hh",
    "document_type": "NATURAL_PERSON",
    "name": "Paul Bearer",
    "bank": "237",
    "branch": "011",
    "account_number": "98765432",
    "account_type": "TRAN",
    "city_code": "3550308"
  },
  "amount": 215,
  "min_payment_amount": 10.09,
  "last_payment_date": "2026-06-10",
  "expiration_date": "2020-08-13T13:49:03.000Z",
  "taxes": {
    "tax_identifier": "IS0435879820240605bcdb1fhn43a",
    "records": [
      {
        "tax_type": "IBS",
        "amount": 1050.44
      }
    ]
  }
}

Response

OK

recurrence_idstring

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).

contract_idstring

Payee-created external ID for their reference.

descriptionstring

Recurrence payment description

amountnumber double

Fee amount.

min_payment_amountnumber

Minimum payment amount for dynamic amount recurrences, defined by payee.

max_payment_amountnumber

Payer-defined maximum payment amount for dynamic amount recurrences.

dynamic_amountboolean

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_expirationboolean

Will charge continue after due date?

is_working_daysboolean

If the recurrence will only execute on working days

expiration_datestring

Card expiration date (format = yymm). If passed, the card expiration date is not calculated using the "Card expiration (# of months)" program parameter.

first_payment_datestring datetime

First charge/payment date. Format = yyyy-mm-dd

last_payment_datestring datetime

Last charge/payment date. Format = yyyy-mm-dd

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_identificationstring

Recurrence transaction ID.

created_atstring date-time

Datetime program calendar strategy was created. Format = YYYY-MM-DDTHH:MM:SS:MM.

updated_atstring date-time

Datetime program calendar strategy was updated. Format = YYYY-MM-DDTHH:MM:SS:MM

Example response

{
  "recurrence_id": "RN000000012025050500012345678",
  "journey_type": "AUT1",
  "contract_id": "5509-uroo-78944-9987",
  "description": "Gym membership",
  "amount": 215,
  "min_payment_amount": 10.09,
  "max_payment_amount": 86753.09,
  "frequency_type": "MONTH",
  "expiration_date": "2803",
  "first_payment_date": "2025-04-25",
  "last_payment_date": "2026-06-10",
  "payee": {
    "name": "Paul Bearer",
    "document_number": "7777888hh",
    "document_type": "NATURAL_PERSON",
    "bank": "237",
    "branch": "011",
    "account_number": "98765432",
    "account_type": "TRAN"
  },
  "payer": {
    "document_number": "7777888hh",
    "document_type": "NATURAL_PERSON",
    "name": "Paul Bearer",
    "bank": "237",
    "branch": "011",
    "account_number": "98765432",
    "account_type": "TRAN",
    "city_code": "3550308"
  },
  "debtor": {
    "document_number": "7777888hh",
    "document_type": "NATURAL_PERSON",
    "name": "Paul Bearer"
  },
  "status": "REJECTED",
  "reason_code": "ACCL",
  "transaction_identification": "1a84daf6-a61b-4aba-919a-a9943db7102e",
  "authorizations": [
    {
      "mti": "0100",
      "authorization_code": "F0JR9H",
      "response_code": "00",
      "authorization_date_time": "2020-01-01T10:10:00.000-03:00",
      "custom_code": "FLB",
      "match_address": true,
      "match_postal_code": true,
      "postal_five_digits": true,
      "no_address_data": true,
      "authorization_id": 4923745,
      "account_id": 24141240,
      "installment_value": "100.00",
      "interest_rate": 2,
      "number_of_installments": 2,
      "contract_amount": "100.00",
      "crediario_responses": [
        {
          "installmentValue": "51.86",
          "monthlyInterestRate": "2.00",
          "totalAmount": "103.72",
          "numberOfInstallments": "2",
          "feeAmount": "0.00",
          "taxesAmount": "0.86",
          "taxesPercentageOfTotalAmount": "0.83",
          "feePercentageOfTotalAmount": "0.00",
          "planType": "",
          "annualInterestRate": "",
          "monthlyTotalEffectiveCost": "",
          "annualTotalEffectiveCost": "",
          "installmentDate": "",
          "insurance": "",
          "insurancePercentageOfTotalAmount": "",
          "other": "",
          "otherPercentageOfTotalAmount": "",
          "totalAmountToMerchant": "",
          "merchantAmountPercentage": "",
          "reservedForFutureUse": ""
        }
      ]
    }
  ],
  "created_at": "2024-09-12T16:46:16.43663522",
  "updated_at": "2024-09-12T16:46:16.43663522",
  "taxes": {
    "tax_identifier": "IS0435879820240605bcdb1fhn43a",
    "records": [
      {
        "tax_type": "IBS",
        "tax_category": "INF",
        "amount": 1050.44
      }
    ]
  }
}