# Pix Pull Subscription

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 Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `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". |

### Create Pix Pull Subscriptions

`POST /v2/pix-pull-subscription`

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `subscriptions` | REQUIRED | List of 1 to 100 subscription objects to create. Each object accepts the parameters described below. |
| `type` | OPTIONAL | Subscription journey type. Options: "push", "qrcode", "qrcodeAndPayment", "paymentAndOrQrcode". |
| `externalId` | REQUIRED | Unique string to prevent duplicates. |
| `bacenId` | REQUIRED | Central Bank identifier of the recurring authorization. |
| `referenceCode` | REQUIRED | Free reference code for the subscription. |
| `interval` | REQUIRED | Billing interval. Options: "week", "month", "quarter", "semester", "year". |
| `installmentStart` | REQUIRED | Date when the recurring authorization starts. |
| `receiverName` | REQUIRED | Name of the receiver (creditor). |
| `receiverTaxId` | REQUIRED | CPF or CNPJ of the receiver. |
| `senderTaxId` | REQUIRED | CPF or CNPJ of the payer (debtor). |
| `senderAccountNumber` | REQUIRED | Account number of the payer. |
| `senderBranchCode` | REQUIRED | Branch code of the payer's account. |
| `amount` | OPTIONAL | Fixed amount in cents pulled on each cycle. Omit for a variable amount. |
| `amountMinLimit` | OPTIONAL | Minimum amount in cents allowed per pull when the amount is variable. |
| `pullRetryLimit` | OPTIONAL | Maximum number of pull retries allowed per cycle. |
| `installmentEnd` | OPTIONAL | Date when the recurring authorization ends. |
| `due` | OPTIONAL | Due datetime for the payer to approve the authorization. |
| `description` | OPTIONAL | Description presented to the payer. |
| `senderBankCode` | REQUIRED | Bank ISPB code of the payer. Example: "20018183". |
| `senderFinalName` | OPTIONAL | Name of the final payer, when different from the account holder. |
| `senderFinalTaxId` | OPTIONAL | CPF or CNPJ of the final payer, when different from the account holder. |
| `senderCityCode` | REQUIRED | IBGE city code of the payer. |
| `receiverBankCode` | REQUIRED | Bank ISPB code of the receiver. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. |

**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)
```

**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"
    )
]
```

### List Pix Pull Subscriptions

`GET /v2/pix-pull-subscription`

List and filter all Pix pull subscriptions. Results are paged.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `externalIds` | OPTIONAL | Filter by the external ids provided on creation. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter by status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `flows` | OPTIONAL | Filter by flow direction. Options: "in", "out". |

**Request**

```python
import starkinfra

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

for subscription in subscriptions:
    print(subscription)
```

**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"
)
```

### Get a Pix Pull Subscription

`GET /v2/pix-pull-subscription/:id`

Get a single Pix pull subscription by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the Pix pull subscription entity. |

**Request**

```python
import starkinfra

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

print(subscription)
```

**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"
)
```

### Update a Pix Pull Subscription

`PATCH /v2/pix-pull-subscription/:id`

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.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the Pix pull subscription entity. |
| `status` | REQUIRED | New status. As the receiver, you may set status to "approved" or "denied" when the subscription's type is "subscriptionAndPayment". As the sender, you may set it to "confirmed" or "denied" for a delivered subscription; when confirming, the senderCityCode field is required. |
| `reason` | OPTIONAL | Reason for the status change, required when denying. The available values depend on whether you are the sender or the receiver. Options: "accountClosed", "accountBlocked", "invalidBranchCode", "notRecognizedBySender", "userRejected", "notOffered". |
| `senderCityCode` | OPTIONAL | IBGE city code of the payer. Required when status is being patched to "confirmed" (as the sender, when confirming a delivered subscription). |

**Request**

```python
import starkinfra

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

print(subscription)
```

**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"
)
```

### Cancel a Pix Pull Subscription

`DELETE /v2/pix-pull-subscription/:id`

Cancel a Pix pull subscription.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the Pix pull subscription entity. |
| `reason` | OPTIONAL | Reason for the cancellation. The available values depend on whether you are the sender or the receiver. Options: "accountClosed", "receiverOrganizationClosed", "receiverInternalError", "senderDeceased", "fraud", "senderUserRequested", "receiverUserRequested", "paymentNotFound". |

**Request**

```python
import starkinfra

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

print(subscription)
```

**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"
)
```

### List Pix Pull Subscription Logs

`GET /v2/pix-pull-subscription/log`

Get a paged list of all Pix pull subscription logs.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. |
| `subscriptionIds` | OPTIONAL | Filter logs by the Pix pull subscription ids they belong to. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `types` | OPTIONAL | Filter by log types. Options: "created", "delivering", "delivered", "approved", "confirmed", "failed", "denied", "canceling", "canceled", "expired". |

**Request**

```python
import starkinfra

logs = starkinfra.pixpullsubscription.log.query(
    limit=10,
    types=["approved"]
)

for log in logs:
    print(log)
```

**Response**

```python
Log(
    id="6767676767676767",
    subscription=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"
    ),
    type="approved",
    errors=[],
    reason="",
    created="2022-01-02T00:00:00+00:00"
)
```

### Get a Pix Pull Subscription Log

`GET /v2/pix-pull-subscription/log/:id`

Get a single Pix pull subscription log by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the log entity. |

**Request**

```python
import starkinfra

log = starkinfra.pixpullsubscription.log.get("6767676767676767")

print(log)
```

**Response**

```python
Log(
    id="6767676767676767",
    subscription=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"
    ),
    type="approved",
    errors=[],
    reason="",
    created="2022-01-02T00:00:00+00:00"
)
```

## Available Languages

Code samples on this page are in Python. The same content is available with samples in:

- [Python](https://docs.starkinfra.com/api/v2/pix-pull-subscription-python.md)
- [Node.js](https://docs.starkinfra.com/api/v2/pix-pull-subscription-node.md)
- [PHP](https://docs.starkinfra.com/api/v2/pix-pull-subscription-php.md)
- [Java](https://docs.starkinfra.com/api/v2/pix-pull-subscription-java.md)
- [Ruby](https://docs.starkinfra.com/api/v2/pix-pull-subscription-ruby.md)
- [Elixir](https://docs.starkinfra.com/api/v2/pix-pull-subscription-elixir.md)
- [.NET](https://docs.starkinfra.com/api/v2/pix-pull-subscription-dotnet.md)
- [Go](https://docs.starkinfra.com/api/v2/pix-pull-subscription-go.md)
- [Clojure](https://docs.starkinfra.com/api/v2/pix-pull-subscription-clojure.md)
- [cURL](https://docs.starkinfra.com/api/v2/pix-pull-subscription-curl.md)