Pix Automático

Pix Automático is Bacen's recurring Pix product, which lets you charge a payer automatically over time without asking for a new authorization at each payment.

A Pix Pull Subscription authorizes recurring debits from a payer's account, defining the terms under which charges can be issued. A Pix Pull Request then issues each scheduled charge against an active subscription.

This guide walks you through both resources: authorizing subscriptions and issuing the scheduled charges that settle them.

RESOURCE SUMMARY
Pix Pull Subscription
Authorize recurring Pix payments (Pix Automático) from a payer's account.
Pix Pull Request
Issue a charge against an active Pix Automático subscription.

Pix Pull Subscription Overview

A Pix Pull Subscription is a recurring authorization (Pix Automático) that lets a receiver pull Pix payments from a payer's account on a defined schedule.

Here we will show you how to create and manage them.

The Pix Pull Subscription Status

You can use asynchronous Webhooks to monitor status changes. A Pix Pull Subscription follows this life cycle:

pix-pull-subscription-status

StatusDescription
CreatedThe subscription was created in Stark Infra.
PendingThe subscription was delivered to the payer PSP and awaits the payer's answer.
FailedThe subscription was not accepted by the payer PSP.
DeniedThe subscription was denied by the payer.
ApprovedThe subscription was approved by the payer.
ActiveThe subscription was approved and recognized by Stark Infra; Pix Pull Requests can now be created.
ExpiredThe subscription reached its end date and is no longer active.
CanceledThe subscription was canceled (by the payer, receiver or a PSP).

The Pix Pull Subscription Logs

Every time we change a Pix Pull Subscription, we create a Log. Logs are useful for understanding its life cycle, and we fire a Webhook whenever a new Log is created. The possible logs:

pix-pull-subscription-logs

Log typeStatusDescription
CreatedCreatedCreated in Stark Infra.
DeliveringCreatedSent to the other PSP.
DeliveredPendingDelivered to the payer PSP.
FailedFailedNot accepted by the payer PSP or a process failure occurred.
ApprovedPendingApproved by the payer.
DeniedDeniedDenied by the payer or payer PSP.
ConfirmedActiveApproved and recognized by Stark Infra.
ExpiredExpiredReached its end date.
CancelingActiveCancellation request sent to the other PSP.
CanceledCanceledThe subscription was canceled.

Authorization Journeys

A Pix Pull Subscription can be authorized through four journeys, selected via the subscription type. Each journey has a receiver-side and a payer-side communication flow:

1st journey — Push notification (type "push")

pix-pull-subscription-1st-authorization-journey-receiver-flow

pix-pull-subscription-1st-authorization-journey-payer-flow

2nd journey — QR Code (type "qrcode")

pix-pull-subscription-2nd-authorization-journey-receiver-flow

pix-pull-subscription-2nd-authorization-journey-payer-flow

3rd journey — QR Code with authorization upon payment (type "qrcodeAndPayment")

pix-pull-subscription-3rd-authorization-journey-receiver-flow

pix-pull-subscription-3rd-authorization-journey-payer-flow

4th journey — Billing QR Code with authorization offer (type "paymentAndOrQrcode")

pix-pull-subscription-4th-authorization-journey-receiver-flow

pix-pull-subscription-4th-authorization-journey-payer-flow

Rules & Limits

The Pix Pull Subscription ecosystem follows a set of rules regarding cycle intervals, payment scheduling and settlement. Understanding these rules is essential for designing a payment flow aligned with your business needs.

Interval Cycle

Subscriptions are structured around a well-defined billing cycle, set by the receiver. Supported intervals: week, month, quarter, semester, year. Only one automatic debit can be settled per cycle, and the behavior depends on the date of the first installment.

  • Rule 1: weekly cycles are based on the weekday - if the first cycle starts on a Tuesday, it ends the following Monday and the second cycle starts the next Tuesday.
  • Rule 2: for other intervals the reference is the calendar day - if the first installment is on the 1st of the month, the next cycle starts on the 1st of the following month.
  • Rule 3: edge case for Rule 2 - if the day is not available in the following month (e.g. February), use the next available date, but the original day remains the reference for future cycles.

Examples

  • Weekly cycle starting January 27th, 2025: 1st cycle Jan 27 to Feb 2; 2nd cycle Feb 3 to Feb 10; 3rd cycle Feb 11 to Feb 18.
  • Monthly cycle starting January 31st, 2025: 1st cycle Jan 31 to Feb 28; 2nd cycle Mar 1 to Mar 30; 3rd cycle Mar 31 to Apr 30.
  • Quarter cycle starting February 5th, 2025: 1st cycle Feb 5 to May 4; 2nd cycle May 5 to Aug 4.
  • Semester cycle starting March 1st: 1st cycle Mar 1 to Aug 31; 2nd cycle Sep 1 to Feb 27 (2026).
  • Year cycle starting July 21st: 1st cycle Jul 21 to Jul 20 (2026); 2nd cycle Jul 21 (2026) to Jul 20 (2027).

Note: as the receiver, you do not need to request payment on the first day of the cycle - it can be triggered on any day before the cycle ends. For example, a monthly subscription starting on March 1st can have its second installment charged anytime between April 1st and April 30th.

Amount Limits

The receiver may define a fixed or variable charge amount.

  • Fixed: the payer authorizes the exact value for automatic debit.
  • Variable: the payer sets a maximum amount, and the receiver can define a minimum limit for what the payer is allowed to approve.

In addition, the payer's bank is required to establish general maximum charge limits for Pix Subscription transactions.

Retry Rules for the Receiver Bank

When creating a subscription, you can define whether Pix Pull Request retries are allowed. If enabled, retries follow these rules:

  • Rule 1: you may retry the payment one day before the expected settlement date (initial requests require a two-day lead).
  • Rule 2: a maximum of 3 retries within 7 days of the original payment date.
  • Rule 3: retry attempts must use the same amount as the original request.
  • Rule 4: you cannot retry within a new cycle window.

Example: a request scheduled for December 4th may be retried on up to 3 different days between December 5th and 11th, as long as those days do not overlap with a new cycle.

The Pix Pull Subscription Object

Attributes

id STRING

Unique id for the Pix pull subscription.

bacenId STRING

Central Bank identifier of the recurring authorization.

amount INTEGER

Fixed amount in cents pulled on each cycle. 0 when the amount is variable.

amountMinLimit INTEGER

Minimum amount in cents allowed per pull when the amount is variable.

interval STRING

Billing interval. Options: "week", "month", "quarter", "semester", "year".

description STRING

Description presented to the payer.

referenceCode STRING

Free reference code for the subscription.

installmentStart STRING

Date when the recurring authorization starts.

installmentEnd STRING

Date when the recurring authorization ends.

due STRING

Due datetime for the payer to approve the authorization.

pullRetryLimit INTEGER

Maximum number of pull retries allowed per cycle.

type STRING

Subscription type. Options: "push", "qrcode", "qrcodeAndPayment", "paymentAndOrQrcode".

externalId STRING

Unique external id to prevent duplicates.

receiverName STRING

Name of the receiver (creditor).

receiverTaxId STRING

CPF or CNPJ of the receiver.

receiverBankCode STRING

Bank ISPB code of the receiver.

senderTaxId STRING

CPF or CNPJ of the payer (debtor).

senderAccountNumber STRING

Account number of the payer.

senderBranchCode STRING

Branch code of the payer's account.

senderBankCode STRING

Bank ISPB code of the payer.

senderFinalName STRING

Name of the final payer, when different from the account holder.

senderFinalTaxId STRING

CPF or CNPJ of the final payer, when different from the account holder.

senderCityCode STRING

IBGE city code of the payer.

status STRING

Current status. Options: "created", "pending", "approved", "active", "failed", "denied", "canceled", "expired".

tags LIST OF STRINGS

Tags associated with the Pix pull subscription.

flow STRING

Direction of the subscription. Options: "out" (you are the receiver), "in" (you are the payer).

created STRING

Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00".

updated STRING

Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00".

Creating Pix Pull Subscriptions

Create recurring Pix authorizations (Pix Automático).

Authorization is obtained through one of four journeys via the subscription type: push (push notification to the payer's bank), qrcode (QR Code with direct authorization), qrcodeAndPayment (QR Code with authorization upon payment), and paymentAndOrQrcode (billing QR Code with an authorization offer).

ENDPOINT
POST /v2/pix-pull-subscription
REQUEST

Python

import starkinfra

subscriptions = starkinfra.pixpullsubscription.create([
    starkinfra.PixPullSubscription(
        type="push",
        external_id="my-subscription-id-1",
        bacen_id="RR20220101200181830000000000001",
        reference_code="contract-12345",
        interval="month",
        installment_start="2022-01-01",
        amount=1000,
        receiver_name="Iron Bank S.A.",
        receiver_tax_id="20.018.183/0001-80",
        sender_tax_id="012.345.678-90",
        sender_account_number="00000-0",
        sender_branch_code="0001",
        tags=["automatic", "pix"]
    )
])

for subscription in subscriptions:
    print(subscription)

Javascript

PHP
Java
Ruby
Elixir
C#
Go
Clojure
Curl
curl --location --request POST '{{baseUrl}}/v2/pix-pull-subscription' \
--header 'Access-Id: {{accessId}}' \
--header 'Access-Time: {{accessTime}}' \
--header 'Access-Signature: {{accessSignature}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "subscriptions": [
        {
            "type": "push",
            "externalId": "my-subscription-id-1",
            "bacenId": "RR20220101200181830000000000001",
            "referenceCode": "contract-12345",
            "interval": "month",
            "installmentStart": "2022-01-01",
            "amount": 1000,
            "receiverName": "Iron Bank S.A.",
            "receiverTaxId": "20.018.183/0001-80",
            "senderTaxId": "012.345.678-90",
            "senderAccountNumber": "00000-0",
            "senderBranchCode": "0001",
            "tags": ["automatic", "pix"]
        }
    ]
}'
  
RESPONSE
Python
[
    PixPullSubscription(
        id="5656565656565656",
        bacen_id="RR20220101200181830000000000001",
        amount=1000,
        amount_min_limit=0,
        interval="month",
        description="",
        reference_code="contract-12345",
        installment_start="2022-01-01T00:00:00+00:00",
        installment_end="",
        due="",
        pull_retry_limit=3,
        type="push",
        external_id="my-subscription-id-1",
        receiver_name="Iron Bank S.A.",
        receiver_tax_id="20.018.183/0001-80",
        receiver_bank_code="20018183",
        sender_tax_id="012.345.678-90",
        sender_account_number="00000-0",
        sender_branch_code="0001",
        sender_bank_code="00000000",
        sender_final_name="",
        sender_final_tax_id="",
        sender_city_code="",
        status="created",
        tags=["automatic", "pix"],
        flow="out",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    )
]
  
Javascript
PHP
Java
Ruby
Elixir
C#
Go
Clojure
Curl
{
    "message": "Subscriptions successfully created",
    "subscriptions": [
        {
            "id": "5656565656565656",
            "bacenId": "RR20220101200181830000000000001",
            "amount": 1000,
            "amountMinLimit": 0,
            "interval": "month",
            "description": "",
            "referenceCode": "contract-12345",
            "installmentStart": "2022-01-01T00:00:00+00:00",
            "installmentEnd": "",
            "due": "",
            "pullRetryLimit": 3,
            "type": "push",
            "externalId": "my-subscription-id-1",
            "receiverName": "Iron Bank S.A.",
            "receiverTaxId": "20.018.183/0001-80",
            "receiverBankCode": "20018183",
            "senderTaxId": "012.345.678-90",
            "senderAccountNumber": "00000-0",
            "senderBranchCode": "0001",
            "senderBankCode": "00000000",
            "senderFinalName": "",
            "senderFinalTaxId": "",
            "senderCityCode": "",
            "status": "created",
            "tags": ["automatic", "pix"],
            "flow": "out",
            "created": "2022-01-01T00:00:00+00:00",
            "updated": "2022-01-01T00:00:00+00:00"
        }
    ]
}
  
Listing Pix Pull Subscriptions
List and filter all Pix pull subscriptions. Results are paged.
ENDPOINT
GET /v2/pix-pull-subscription
REQUEST
Python
import starkinfra

subscriptions = starkinfra.pixpullsubscription.query(
    limit=10,
    status="active"
)

for subscription in subscriptions:
    print(subscription)
  
Javascript
PHP
Java
Ruby
Elixir
C#
Go
Clojure
Curl
curl --location --request GET '{{baseUrl}}/v2/pix-pull-subscription?limit=10&status=active' \
--header 'Access-Id: {{accessId}}' \
--header 'Access-Time: {{accessTime}}' \
--header 'Access-Signature: {{accessSignature}}'
  
RESPONSE
Python
PixPullSubscription(
    id="5656565656565656",
    bacen_id="RR20220101200181830000000000001",
    amount=1000,
    amount_min_limit=0,
    interval="month",
    description="",
    reference_code="contract-12345",
    installment_start="2022-01-01T00:00:00+00:00",
    installment_end="",
    due="",
    pull_retry_limit=3,
    type="push",
    external_id="my-subscription-id-1",
    receiver_name="Iron Bank S.A.",
    receiver_tax_id="20.018.183/0001-80",
    receiver_bank_code="20018183",
    sender_tax_id="012.345.678-90",
    sender_account_number="00000-0",
    sender_branch_code="0001",
    sender_bank_code="00000000",
    sender_final_name="",
    sender_final_tax_id="",
    sender_city_code="",
    status="active",
    tags=["automatic", "pix"],
    flow="out",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-02T00:00:00+00:00"
)
  
Javascript
PHP
Java
Ruby
Elixir
C#
Go
Clojure
Curl
{
    "cursor": null,
    "subscriptions": [
        {
            "id": "5656565656565656",
            "bacenId": "RR20220101200181830000000000001",
            "amount": 1000,
            "amountMinLimit": 0,
            "interval": "month",
            "description": "",
            "referenceCode": "contract-12345",
            "installmentStart": "2022-01-01T00:00:00+00:00",
            "installmentEnd": "",
            "due": "",
            "pullRetryLimit": 3,
            "type": "push",
            "externalId": "my-subscription-id-1",
            "receiverName": "Iron Bank S.A.",
            "receiverTaxId": "20.018.183/0001-80",
            "receiverBankCode": "20018183",
            "senderTaxId": "012.345.678-90",
            "senderAccountNumber": "00000-0",
            "senderBranchCode": "0001",
            "senderBankCode": "00000000",
            "senderFinalName": "",
            "senderFinalTaxId": "",
            "senderCityCode": "",
            "status": "active",
            "tags": ["automatic", "pix"],
            "flow": "out",
            "created": "2022-01-01T00:00:00+00:00",
            "updated": "2022-01-02T00:00:00+00:00"
        }
    ]
}
  
Getting a Pix Pull Subscription
Get a single Pix pull subscription by its id.
ENDPOINT
GET /v2/pix-pull-subscription/:id
REQUEST
Python
import starkinfra

subscription = starkinfra.pixpullsubscription.get("5656565656565656")

print(subscription)
  
Javascript
PHP
Java
Ruby
Elixir
C#
Go
Clojure
Curl
curl --location --request GET '{{baseUrl}}/v2/pix-pull-subscription/5656565656565656' \
--header 'Access-Id: {{accessId}}' \
--header 'Access-Time: {{accessTime}}' \
--header 'Access-Signature: {{accessSignature}}'
  
RESPONSE
Python
PixPullSubscription(
    id="5656565656565656",
    bacen_id="RR20220101200181830000000000001",
    amount=1000,
    amount_min_limit=0,
    interval="month",
    description="",
    reference_code="contract-12345",
    installment_start="2022-01-01T00:00:00+00:00",
    installment_end="",
    due="",
    pull_retry_limit=3,
    type="push",
    external_id="my-subscription-id-1",
    receiver_name="Iron Bank S.A.",
    receiver_tax_id="20.018.183/0001-80",
    receiver_bank_code="20018183",
    sender_tax_id="012.345.678-90",
    sender_account_number="00000-0",
    sender_branch_code="0001",
    sender_bank_code="00000000",
    sender_final_name="",
    sender_final_tax_id="",
    sender_city_code="",
    status="active",
    tags=["automatic", "pix"],
    flow="out",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-02T00:00:00+00:00"
)
  
Javascript
PHP
Java
Ruby
Elixir
C#
Go
Clojure
Curl
{
    "subscription": {
        "id": "5656565656565656",
        "bacenId": "RR20220101200181830000000000001",
        "amount": 1000,
        "amountMinLimit": 0,
        "interval": "month",
        "description": "",
        "referenceCode": "contract-12345",
        "installmentStart": "2022-01-01T00:00:00+00:00",
        "installmentEnd": "",
        "due": "",
        "pullRetryLimit": 3,
        "type": "push",
        "externalId": "my-subscription-id-1",
        "receiverName": "Iron Bank S.A.",
        "receiverTaxId": "20.018.183/0001-80",
        "receiverBankCode": "20018183",
        "senderTaxId": "012.345.678-90",
        "senderAccountNumber": "00000-0",
        "senderBranchCode": "0001",
        "senderBankCode": "00000000",
        "senderFinalName": "",
        "senderFinalTaxId": "",
        "senderCityCode": "",
        "status": "active",
        "tags": ["automatic", "pix"],
        "flow": "out",
        "created": "2022-01-01T00:00:00+00:00",
        "updated": "2022-01-02T00:00:00+00:00"
    }
}
  
Updating a Pix Pull Subscription
Approve, deny or activate a Pix pull subscription. The allowed status transitions depend on whether you are the payer or the receiver.
When confirming a received subscription, include the senderCityCode field.
ENDPOINT
PATCH /v2/pix-pull-subscription/:id
REQUEST
Python
import starkinfra

subscription = starkinfra.pixpullsubscription.update(
    "5656565656565656",
    status="approved",
    sender_city_code="3550308"
)

print(subscription)
  
Javascript
PHP
Java
Ruby
Elixir
C#
Go
Clojure
Curl
curl --location --request PATCH '{{baseUrl}}/v2/pix-pull-subscription/5656565656565656' \
--header 'Access-Id: {{accessId}}' \
--header 'Access-Time: {{accessTime}}' \
--header 'Access-Signature: {{accessSignature}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "status": "approved",
    "senderCityCode": "3550308"
}'
  
RESPONSE
Python
PixPullSubscription(
    id="5656565656565656",
    bacen_id="RR20220101200181830000000000001",
    amount=1000,
    amount_min_limit=0,
    interval="month",
    description="",
    reference_code="contract-12345",
    installment_start="2022-01-01T00:00:00+00:00",
    installment_end="",
    due="",
    pull_retry_limit=3,
    type="push",
    external_id="my-subscription-id-1",
    receiver_name="Iron Bank S.A.",
    receiver_tax_id="20.018.183/0001-80",
    receiver_bank_code="20018183",
    sender_tax_id="012.345.678-90",
    sender_account_number="00000-0",
    sender_branch_code="0001",
    sender_bank_code="00000000",
    sender_final_name="",
    sender_final_tax_id="",
    sender_city_code="3550308",
    status="approved",
    tags=["automatic", "pix"],
    flow="out",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-02T00:00:00+00:00"
)
  
Javascript
PHP
Java
Ruby
Elixir
C#
Go
Clojure
Curl
{
    "message": "Subscription successfully updated",
    "subscription": {
        "id": "5656565656565656",
        "bacenId": "RR20220101200181830000000000001",
        "amount": 1000,
        "amountMinLimit": 0,
        "interval": "month",
        "description": "",
        "referenceCode": "contract-12345",
        "installmentStart": "2022-01-01T00:00:00+00:00",
        "installmentEnd": "",
        "due": "",
        "pullRetryLimit": 3,
        "type": "push",
        "externalId": "my-subscription-id-1",
        "receiverName": "Iron Bank S.A.",
        "receiverTaxId": "20.018.183/0001-80",
        "receiverBankCode": "20018183",
        "senderTaxId": "012.345.678-90",
        "senderAccountNumber": "00000-0",
        "senderBranchCode": "0001",
        "senderBankCode": "00000000",
        "senderFinalName": "",
        "senderFinalTaxId": "",
        "senderCityCode": "3550308",
        "status": "approved",
        "tags": ["automatic", "pix"],
        "flow": "out",
        "created": "2022-01-01T00:00:00+00:00",
        "updated": "2022-01-02T00:00:00+00:00"
    }
}
  
Canceling a Pix Pull Subscription
Cancel a Pix pull subscription.
ENDPOINT
DELETE /v2/pix-pull-subscription/:id
REQUEST
Python
import starkinfra

subscription = starkinfra.pixpullsubscription.cancel("5656565656565656")

print(subscription)
  
Javascript
PHP
Java
Ruby
Elixir
C#
Go
Clojure
Curl
curl --location --request DELETE '{{baseUrl}}/v2/pix-pull-subscription/5656565656565656' \
--header 'Access-Id: {{accessId}}' \
--header 'Access-Time: {{accessTime}}' \
--header 'Access-Signature: {{accessSignature}}'
  
RESPONSE
Python
PixPullSubscription(
    id="5656565656565656",
    bacen_id="RR20220101200181830000000000001",
    amount=1000,
    amount_min_limit=0,
    interval="month",
    description="",
    reference_code="contract-12345",
    installment_start="2022-01-01T00:00:00+00:00",
    installment_end="",
    due="",
    pull_retry_limit=3,
    type="push",
    external_id="my-subscription-id-1",
    receiver_name="Iron Bank S.A.",
    receiver_tax_id="20.018.183/0001-80",
    receiver_bank_code="20018183",
    sender_tax_id="012.345.678-90",
    sender_account_number="00000-0",
    sender_branch_code="0001",
    sender_bank_code="00000000",
    sender_final_name="",
    sender_final_tax_id="",
    sender_city_code="",
    status="canceled",
    tags=["automatic", "pix"],
    flow="out",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-03T00:00:00+00:00"
)
  
Javascript
PHP
Java
Ruby
Elixir
C#
Go
Clojure
Curl
{
    "message": "Subscription successfully canceled",
    "subscription": {
        "id": "5656565656565656",
        "bacenId": "RR20220101200181830000000000001",
        "amount": 1000,
        "amountMinLimit": 0,
        "interval": "month",
        "description": "",
        "referenceCode": "contract-12345",
        "installmentStart": "2022-01-01T00:00:00+00:00",
        "installmentEnd": "",
        "due": "",
        "pullRetryLimit": 3,
        "type": "push",
        "externalId": "my-subscription-id-1",
        "receiverName": "Iron Bank S.A.",
        "receiverTaxId": "20.018.183/0001-80",
        "receiverBankCode": "20018183",
        "senderTaxId": "012.345.678-90",
        "senderAccountNumber": "00000-0",
        "senderBranchCode": "0001",
        "senderBankCode": "00000000",
        "senderFinalName": "",
        "senderFinalTaxId": "",
        "senderCityCode": "",
        "status": "canceled",
        "tags": ["automatic", "pix"],
        "flow": "out",
        "created": "2022-01-01T00:00:00+00:00",
        "updated": "2022-01-03T00:00:00+00:00"
    }
}
  
Pix Pull Request Overview
A Pix Pull Request is a single charge issued against an active Pix Pull Subscription (Pix Automático), pulling a payment from the payer's account.
Here we will show you how to create and manage them.
The Pix Pull Request Status
 
You can use asynchronous Webhooks to monitor status changes. A Pix Pull Request follows this life cycle:
pix-pull-request-status
StatusDescription
CreatedThe Pix Pull Request was created in Stark Infra.
ProcessingThe request was delivered to the payer PSP.
ScheduledThe request was scheduled by the payer PSP.
DeniedThe request was denied by the payer PSP.
SuccessThe request was settled.
FailedThe request was unsuccessful.
CanceledThe request was canceled.
ExpiredThe request expired.
The Pix Pull Request Logs
 
Every time we change a Pix Pull Request, we create a Log. Logs are useful for understanding its life cycle, and we fire a Webhook whenever a new Log is created. The possible logs:
pix-pull-request-logs
Log typeStatusDescription
CreatedCreatedCreated in Stark Infra.
SentProcessingDelivered to the payer PSP.
ScheduledScheduledScheduled by the payer PSP.
DeniedDeniedDenied by the payer PSP.
SuccessSuccessThe request was settled.
CancelingScheduledCancellation requested.
CanceledCanceledThe request was canceled.
ExpiredExpiredThe request expired.
Receiving a Pix Pull Request
In this section we will show you how to receive and handle a Pix Pull Request as the payer bank.
receiving-a-pix-pull-request
Rules & Limits
The Pix Pull Request ecosystem follows a set of rules regarding cycle intervals, payment scheduling and settlement. Understanding these rules is essential for designing a payment flow aligned with your business needs.
Scheduling
Once cycles and limits are defined, schedule the Pix Pull Request. To receive a payment on a specific date, the request must be sent 2 to 10 days before the expected settlement.
Example: to receive funds on July 14th, the request must be made between July 4th and July 12th.
Retry Rules for the Payer Bank
When a Pix Pull Request is successfully created, the payer's bank must attempt settlement in at least two time windows:
  • First attempt: between 00h00 and 08h00.
  • Second attempt: between 18h00 and 21h00.
Note: after 21:00, settlement attempts are no longer accepted by Stark Infra. A webhook is triggered if the automatic debit fails.
The Pix Pull Request Object
Attributes
id STRING
Unique id for the Pix pull request.
amount INTEGER
Amount in cents to be pulled.
description STRING
Description of the pull request.
due STRING
Due datetime for the pull.
endToEndId STRING
End-to-end id of the Pix pull request.
reconciliationId STRING
Reconciliation id (txid) of the pull.
subscriptionId STRING
Id of the Pix pull subscription this request belongs to.
subscriptionBacenId STRING
Central Bank id of the related subscription.
receiverName STRING
Name of the receiver (creditor).
receiverTaxId STRING
CPF or CNPJ of the receiver.
receiverBankCode STRING
Bank ISPB code of the receiver.
receiverAccountNumber STRING
Account number of the receiver.
receiverBranchCode STRING
Branch code of the receiver's account.
receiverAccountType STRING
Type of the receiver's account.
senderTaxId STRING
CPF or CNPJ of the payer (debtor).
senderBankCode STRING
Bank ISPB code of the payer.
senderFinalName STRING
Name of the final payer, when different from the account holder.
senderFinalTaxId STRING
CPF or CNPJ of the final payer, when different from the account holder.
attemptType STRING
Pull attempt type. Options: "default", "scheduledRetry", "instantRetry".
tags LIST OF STRINGS
Tags associated with the Pix pull request.
flow STRING
Direction of the pull request. Options: "out" (you are the receiver), "in" (you are the payer).
status STRING
Current status. Options: "created", "processing", "scheduled", "denied", "success", "failed", "canceled", "expired".
created STRING
Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00".
updated STRING
Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00".
Creating Pix Pull Requests
Issue charges against active Pix pull subscriptions.
As the receiver bank, create a Pix Pull Request to instruct a debit from the payer's account on a scheduled date. Stark Infra verifies that the subscription is approved, the amount is within the authorized limit, the settlement date matches the subscription's charge cycle, payer/receiver details match the contract, the request is made between 10 and 2 days before settlement, and there is no other scheduled request for the same cycle.
creating-a-pix-pull-request
ENDPOINT
POST /v2/pix-pull-request
REQUEST
Python
import starkinfra

requests = starkinfra.pixpullrequest.create([
    starkinfra.PixPullRequest(
        subscription_id="5656565656565656",
        amount=1000,
        due="2022-02-01T00:00:00+00:00",
        attempt_type="default",
        end_to_end_id="E20018183202201010000000000001",
        reconciliation_id="txid1234567890",
        receiver_account_number="00000-0",
        receiver_account_type="checking",
        tags=["automatic", "pix"]
    )
])

for request in requests:
    print(request)
  
Javascript
PHP
Java
Ruby
Elixir
C#
Go
Clojure
Curl
curl --location --request POST '{{baseUrl}}/v2/pix-pull-request' \
--header 'Access-Id: {{accessId}}' \
--header 'Access-Time: {{accessTime}}' \
--header 'Access-Signature: {{accessSignature}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "requests": [
        {
            "subscriptionId": "5656565656565656",
            "amount": 1000,
            "due": "2022-02-01T00:00:00+00:00",
            "attemptType": "default",
            "endToEndId": "E20018183202201010000000000001",
            "reconciliationId": "txid1234567890",
            "receiverAccountNumber": "00000-0",
            "receiverAccountType": "checking",
            "tags": ["automatic", "pix"]
        }
    ]
}'
  
RESPONSE
Python
[
    PixPullRequest(
        id="4646464646464646",
        amount=1000,
        description="",
        due="2022-02-01T00:00:00+00:00",
        end_to_end_id="E20018183202201010000000000001",
        reconciliation_id="txid1234567890",
        subscription_id="5656565656565656",
        subscription_bacen_id="RR20220101200181830000000000001",
        receiver_name="Iron Bank S.A.",
        receiver_tax_id="20.018.183/0001-80",
        receiver_bank_code="20018183",
        receiver_account_number="00000-0",
        receiver_branch_code="0001",
        receiver_account_type="checking",
        sender_tax_id="012.345.678-90",
        sender_bank_code="00000000",
        sender_final_name="",
        sender_final_tax_id="",
        attempt_type="default",
        tags=["automatic", "pix"],
        flow="out",
        status="created",
        created="2022-01-15T00:00:00+00:00",
        updated="2022-01-15T00:00:00+00:00"
    )
]
  
Javascript
PHP
Java
Ruby
Elixir
C#
Go
Clojure
Curl
{
    "message": "Requests successfully created",
    "requests": [
        {
            "id": "4646464646464646",
            "amount": 1000,
            "description": "",
            "due": "2022-02-01T00:00:00+00:00",
            "endToEndId": "E20018183202201010000000000001",
            "reconciliationId": "txid1234567890",
            "subscriptionId": "5656565656565656",
            "subscriptionBacenId": "RR20220101200181830000000000001",
            "receiverName": "Iron Bank S.A.",
            "receiverTaxId": "20.018.183/0001-80",
            "receiverBankCode": "20018183",
            "receiverAccountNumber": "00000-0",
            "receiverBranchCode": "0001",
            "receiverAccountType": "checking",
            "senderTaxId": "012.345.678-90",
            "senderBankCode": "00000000",
            "senderFinalName": "",
            "senderFinalTaxId": "",
            "attemptType": "default",
            "tags": ["automatic", "pix"],
            "flow": "out",
            "status": "created",
            "created": "2022-01-15T00:00:00+00:00",
            "updated": "2022-01-15T00:00:00+00:00"
        }
    ]
}
  
Listing Pix Pull Requests
List and filter all Pix pull requests. Results are paged.
ENDPOINT
GET /v2/pix-pull-request
REQUEST
Python
import starkinfra

requests = starkinfra.pixpullrequest.query(
    limit=10,
    subscription_ids=["5656565656565656"]
)

for request in requests:
    print(request)
  
Javascript
PHP
Java
Ruby
Elixir
C#
Go
Clojure
Curl
curl --location --request GET '{{baseUrl}}/v2/pix-pull-request?limit=10&subscriptionIds=5656565656565656' \
--header 'Access-Id: {{accessId}}' \
--header 'Access-Time: {{accessTime}}' \
--header 'Access-Signature: {{accessSignature}}'
  
RESPONSE
Python
PixPullRequest(
    id="4646464646464646",
    amount=1000,
    description="",
    due="2022-02-01T00:00:00+00:00",
    end_to_end_id="E20018183202201010000000000001",
    reconciliation_id="txid1234567890",
    subscription_id="5656565656565656",
    subscription_bacen_id="RR20220101200181830000000000001",
    receiver_name="Iron Bank S.A.",
    receiver_tax_id="20.018.183/0001-80",
    receiver_bank_code="20018183",
    receiver_account_number="00000-0",
    receiver_branch_code="0001",
    receiver_account_type="checking",
    sender_tax_id="012.345.678-90",
    sender_bank_code="00000000",
    sender_final_name="",
    sender_final_tax_id="",
    attempt_type="default",
    tags=["automatic", "pix"],
    flow="out",
    status="success",
    created="2022-01-15T00:00:00+00:00",
    updated="2022-02-01T00:00:00+00:00"
)
  
Javascript
PHP
Java
Ruby
Elixir
C#
Go
Clojure
Curl
{
    "cursor": null,
    "requests": [
        {
            "id": "4646464646464646",
            "amount": 1000,
            "description": "",
            "due": "2022-02-01T00:00:00+00:00",
            "endToEndId": "E20018183202201010000000000001",
            "reconciliationId": "txid1234567890",
            "subscriptionId": "5656565656565656",
            "subscriptionBacenId": "RR20220101200181830000000000001",
            "receiverName": "Iron Bank S.A.",
            "receiverTaxId": "20.018.183/0001-80",
            "receiverBankCode": "20018183",
            "receiverAccountNumber": "00000-0",
            "receiverBranchCode": "0001",
            "receiverAccountType": "checking",
            "senderTaxId": "012.345.678-90",
            "senderBankCode": "00000000",
            "senderFinalName": "",
            "senderFinalTaxId": "",
            "attemptType": "default",
            "tags": ["automatic", "pix"],
            "flow": "out",
            "status": "success",
            "created": "2022-01-15T00:00:00+00:00",
            "updated": "2022-02-01T00:00:00+00:00"
        }
    ]
}
  
Getting a Pix Pull Request
Get a single Pix pull request by its id.
ENDPOINT
GET /v2/pix-pull-request/:id
REQUEST
Python
import starkinfra

request = starkinfra.pixpullrequest.get("4646464646464646")

print(request)
  
Javascript
PHP
Java
Ruby
Elixir
C#
Go
Clojure
Curl
curl --location --request GET '{{baseUrl}}/v2/pix-pull-request/4646464646464646' \
--header 'Access-Id: {{accessId}}' \
--header 'Access-Time: {{accessTime}}' \
--header 'Access-Signature: {{accessSignature}}'
  
RESPONSE
Python
PixPullRequest(
    id="4646464646464646",
    amount=1000,
    description="",
    due="2022-02-01T00:00:00+00:00",
    end_to_end_id="E20018183202201010000000000001",
    reconciliation_id="txid1234567890",
    subscription_id="5656565656565656",
    subscription_bacen_id="RR20220101200181830000000000001",
    receiver_name="Iron Bank S.A.",
    receiver_tax_id="20.018.183/0001-80",
    receiver_bank_code="20018183",
    receiver_account_number="00000-0",
    receiver_branch_code="0001",
    receiver_account_type="checking",
    sender_tax_id="012.345.678-90",
    sender_bank_code="00000000",
    sender_final_name="",
    sender_final_tax_id="",
    attempt_type="default",
    tags=["automatic", "pix"],
    flow="out",
    status="success",
    created="2022-01-15T00:00:00+00:00",
    updated="2022-02-01T00:00:00+00:00"
)
  
Javascript
PHP
Java
Ruby
Elixir
C#
Go
Clojure
Curl
{
    "request": {
        "id": "4646464646464646",
        "amount": 1000,
        "description": "",
        "due": "2022-02-01T00:00:00+00:00",
        "endToEndId": "E20018183202201010000000000001",
        "reconciliationId": "txid1234567890",
        "subscriptionId": "5656565656565656",
        "subscriptionBacenId": "RR20220101200181830000000000001",
        "receiverName": "Iron Bank S.A.",
        "receiverTaxId": "20.018.183/0001-80",
        "receiverBankCode": "20018183",
        "receiverAccountNumber": "00000-0",
        "receiverBranchCode": "0001",
        "receiverAccountType": "checking",
        "senderTaxId": "012.345.678-90",
        "senderBankCode": "00000000",
        "senderFinalName": "",
        "senderFinalTaxId": "",
        "attemptType": "default",
        "tags": ["automatic", "pix"],
        "flow": "out",
        "status": "success",
        "created": "2022-01-15T00:00:00+00:00",
        "updated": "2022-02-01T00:00:00+00:00"
    }
}
  
Updating a Pix Pull Request
Schedule or deny a Pix pull request. Only the payer may update a pull request.
ENDPOINT
PATCH /v2/pix-pull-request/:id
REQUEST
Python
import starkinfra

request = starkinfra.pixpullrequest.update(
    "4646464646464646",
    status="denied",
    reason="senderAccountClosed"
)

print(request)
  
Javascript
PHP
Java
Ruby
Elixir
C#
Go
Clojure
Curl
curl --location --request PATCH '{{baseUrl}}/v2/pix-pull-request/4646464646464646' \
--header 'Access-Id: {{accessId}}' \
--header 'Access-Time: {{accessTime}}' \
--header 'Access-Signature: {{accessSignature}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "status": "denied",
    "reason": "senderAccountClosed"
}'
  
RESPONSE
Python
PixPullRequest(
    id="4646464646464646",
    amount=1000,
    description="",
    due="2022-02-01T00:00:00+00:00",
    end_to_end_id="E20018183202201010000000000001",
    reconciliation_id="txid1234567890",
    subscription_id="5656565656565656",
    subscription_bacen_id="RR20220101200181830000000000001",
    receiver_name="Iron Bank S.A.",
    receiver_tax_id="20.018.183/0001-80",
    receiver_bank_code="20018183",
    receiver_account_number="00000-0",
    receiver_branch_code="0001",
    receiver_account_type="checking",
    sender_tax_id="012.345.678-90",
    sender_bank_code="00000000",
    sender_final_name="",
    sender_final_tax_id="",
    attempt_type="default",
    tags=["automatic", "pix"],
    flow="in",
    status="denied",
    created="2022-01-15T00:00:00+00:00",
    updated="2022-01-16T00:00:00+00:00"
)
  
Javascript
PHP
Java
Ruby
Elixir
C#
Go
Clojure
Curl
{
    "message": "Request successfully updated",
    "request": {
        "id": "4646464646464646",
        "amount": 1000,
        "description": "",
        "due": "2022-02-01T00:00:00+00:00",
        "endToEndId": "E20018183202201010000000000001",
        "reconciliationId": "txid1234567890",
        "subscriptionId": "5656565656565656",
        "subscriptionBacenId": "RR20220101200181830000000000001",
        "receiverName": "Iron Bank S.A.",
        "receiverTaxId": "20.018.183/0001-80",
        "receiverBankCode": "20018183",
        "receiverAccountNumber": "00000-0",
        "receiverBranchCode": "0001",
        "receiverAccountType": "checking",
        "senderTaxId": "012.345.678-90",
        "senderBankCode": "00000000",
        "senderFinalName": "",
        "senderFinalTaxId": "",
        "attemptType": "default",
        "tags": ["automatic", "pix"],
        "flow": "in",
        "status": "denied",
        "created": "2022-01-15T00:00:00+00:00",
        "updated": "2022-01-16T00:00:00+00:00"
    }
}
  
Canceling a Pix Pull Request
Cancel a Pix pull request.
ENDPOINT
DELETE /v2/pix-pull-request/:id
REQUEST
Python
import starkinfra

request = starkinfra.pixpullrequest.cancel(
    "4646464646464646",
    reason="senderAccountClosed"
)

print(request)
  
Javascript
PHP
Java
Ruby
Elixir
C#
Go
Clojure
Curl
curl --location --request DELETE '{{baseUrl}}/v2/pix-pull-request/4646464646464646' \
--header 'Access-Id: {{accessId}}' \
--header 'Access-Time: {{accessTime}}' \
--header 'Access-Signature: {{accessSignature}}'
  
RESPONSE
Python
PixPullRequest(
    id="4646464646464646",
    amount=1000,
    description="",
    due="2022-02-01T00:00:00+00:00",
    end_to_end_id="E20018183202201010000000000001",
    reconciliation_id="txid1234567890",
    subscription_id="5656565656565656",
    subscription_bacen_id="RR20220101200181830000000000001",
    receiver_name="Iron Bank S.A.",
    receiver_tax_id="20.018.183/0001-80",
    receiver_bank_code="20018183",
    receiver_account_number="00000-0",
    receiver_branch_code="0001",
    receiver_account_type="checking",
    sender_tax_id="012.345.678-90",
    sender_bank_code="00000000",
    sender_final_name="",
    sender_final_tax_id="",
    attempt_type="default",
    tags=["automatic", "pix"],
    flow="out",
    status="canceled",
    created="2022-01-15T00:00:00+00:00",
    updated="2022-01-16T00:00:00+00:00"
)
  
Javascript
PHP
Java
Ruby
Elixir
C#
Go
Clojure
Curl
{
    "message": "Request successfully canceled",
    "request": {
        "id": "4646464646464646",
        "amount": 1000,
        "description": "",
        "due": "2022-02-01T00:00:00+00:00",
        "endToEndId": "E20018183202201010000000000001",
        "reconciliationId": "txid1234567890",
        "subscriptionId": "5656565656565656",
        "subscriptionBacenId": "RR20220101200181830000000000001",
        "receiverName": "Iron Bank S.A.",
        "receiverTaxId": "20.018.183/0001-80",
        "receiverBankCode": "20018183",
        "receiverAccountNumber": "00000-0",
        "receiverBranchCode": "0001",
        "receiverAccountType": "checking",
        "senderTaxId": "012.345.678-90",
        "senderBankCode": "00000000",
        "senderFinalName": "",
        "senderFinalTaxId": "",
        "attemptType": "default",
        "tags": ["automatic", "pix"],
        "flow": "out",
        "status": "canceled",
        "created": "2022-01-15T00:00:00+00:00",
        "updated": "2022-01-16T00:00:00+00:00"
    }
}