# Pix Subscription

Pix Subscription enables recurring payments through a one-time user authorization. Once the payer grants permission, you can periodically charge them automatically, no further action is required from the payer.

The flow consists of three main steps:

1. Create an Invoice Pull Subscription to obtain the payer's authorization for recurring charges.

2. Create an Invoice with the amount you want to charge.

3. Create an Invoice Pull Request to trigger the automatic debit from the payer's account on a scheduled date.

The Invoice can also be used to charge the customer through other channels (such as SMS, WhatsApp, or mobile apps), with enhanced features (like splits, fines, and more).

NOTE: Read Core Concepts before continuing this guide.

**RESOURCE SUMMARY**

Invoice Pull SubscriptionA set of parameters and permissions that define recurring Pix payments, including recurrence settings and payer authorization. The pullMode parameter determines whether you or Stark Bank will manage invoices and pull requests.InvoiceRepresents the charge for each billing cycle with a fixed amount. In automatic mode, Stark Bank creates invoices automatically. In manual mode, you create them for each cycle.Invoice Pull RequestTriggers the automatic debit for a specific invoice linked to an active Invoice Pull Subscription.

## Setup

For each environment: (Sandbox or Production)

1. Create an account at Stark Bank.

2. Create a webhook with the following subscriptions to receive events in your desired URL:

invoice

invoice-pull-subscription

invoice-pull-request

2.1. Via Internet Banking: 

Integrations > Webhook > New Webhook

2.2. Via API: 

Use the POST /webhook route to create the webhook

## Authorization Journeys

At Stark Bank, authorizations are handled through Invoice Pull Subscriptions, which can be created using four different journeys:

Push notification (1st journey): If you know the payer's bank account information, you can send a push request directly to their bank. The payer will then receive a notification in their banking app to accept or deny the subscription type = push

QR Code with direct authorization (2nd journey): A QR Code is generated with the subscription details, without needing the payer's bank info. The payer can scan the code or use the "copy & paste" function in their bank app to authorize the subscription type = qrcode

QR Code with authorization upon payment (3rd journey): The QR Code includes both the subscription details and an instant payment. The subscription is only activated once the payment is completed type = qrcodeAndPayment

QR Code for billing with authorization offer (4th journey): A QR Code is generated for a due payment that includes a subscription offer. Once the payer settles the payment, they are presented with the option to accept the subscription type = paymentAndOrQrcode.

## Rules & Limits

The Pix 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 include: 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.

Key rules

Rule 1: Weekly cycles are based on the weekday. If the first cycle starts on a Tuesday, it ends the following Monday. 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 day of the month, the next cycle starts on the 1st day of the following month;
Rule 3: It is an edge case for rule 2. If the day isn't available in the following month (e.g., February or months with fewer days), use the next available date. Still, the original day remains the reference for future cycles.

Examples

Weekly cycle that started at January 27th of 2025:

The first cycle starts at January 27th and finishes at February 2nd;
The second cycle starts at February 3rd and finishes at February 10th;
The third cycle starts at February 11th and finishes at February 18th.

Monthly cycle that started at January 31st of 2025:

The first cycle starts at January 31st and finishes at February 28th;
The second cycle starts at March 1st and finishes at March 30th;
The third cycle starts at March 31st and finishes at April 30th.

Quarter cycle that started at February 5th of 2025:

The first cycle starts at February 5th and finishes at May 4th;
The second cycle starts at May 5th and finishes at August 4th.

Semester cycle that started at March 1st:

The first cycle starts at March 1st and finishes at August 31st;
The second cycle starts at September 1st and finishes at February 27th (following year).

Year cycle that started at July 21st:

The first cycle starts at July 21st and finishes at July 20th (of the next year);
The second cycle starts at July 21st (of the next year) and finishes at July 20th (following year);

Note: You don't need to request a payment on the first day of the cycle. It can be triggered on any day before the cycle ends.

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 can set 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.

Invoice Pull Request Period

Once cycles and limits are defined, it's time to schedule the automatic debit with an Invoice 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 an Invoice 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 Bank. A webhook will be triggered if the automatic debit fails.

If the collection of an invoice pull request fails, use the following retry rules to process it:

| Reason | Log Type | Action |
| --- | --- | --- |
| receiverUserRequest | canceled | Create the request with attemptType="default" – in this case, the Stark client has canceled the invoicePullRequest before it was settled, so it is possible to create another request for the same cycle. |
| pixRequestFailed | canceled | Intraday retry (Stark Bank will retry on behalf of the Stark client). |
| notSettled | failed | Retry must be performed by the receiver Stark client by creating a new request with the same invoiceId and attemptType="retry". |

Note: The logs "canceled", "denied", or "success" in any scenario not specified above do not allow a retry.

Invoice Pull Request Retry Rules

When creating a subscription, you can define whether retries are allowed. If enabled, the retry follows these rules:

Rule 1: You may retry the payment one day before the expected settlement date (unlike initial requests, which require a two-day lead);
Rule 2: A maximum of 3 retries can occur 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 don't overlap with a new cycle.

## Sandbox

In the Sandbox environment, all Invoice Pull Subscriptions are automatically approved within 15 minutes.

If you don't have a Sandbox account, you can open one here:

Create a Workspace in Sandbox

## Invoice Pull Subscription Overview

An Invoice Pull Subscription is a recurring payment agreement between a payer and a receiver, authorized through the Pix Automatic infrastructure. Once active, it allows the receiver to periodically trigger automatic debits by issuing invoices that match the agreed conditions—such as amount, frequency, and billing cycle—without requiring new consent for each transaction.

### The Invoice Pull Subscription Object

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `amount` | INTEGER | Fixed amount to be charged every cycle in cents. |
| `amountMinLimit` | INTEGER | This parameter allows the receiver to set a mandatory minimum amount for the payer's security limit. Its purpose is to prevent the authorization from being created with a limit insufficient to cover future charges. This should only be used if the main amount parameter of the Invoice Pull Subscription is set to 0. Example: For a subscription with a variable average cost of R$ 120.00, the company can set the amountMinLimit parameter at R$ 120.00. This way, the client is required to configure their security limit (ceiling) above R$ 120.00, reducing the risk of failures due to limit exceeded in the future. |
| `bacenId` | STRING | Central Bank identifier. |
| `brcode` | STRING | BR Code for the subscription. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `data` | STRING | This field contains additional data provided at the moment of Invoice Pull Subscription creation: For Journey type 1 (type=push): related to the payer user's bank account. For Journey type 2 (type=qrcode): the data field is not required. For Journey types 3 (type=qrcodeAndPayment) and 4 (paymentAndOrQrcode): information about the immediate charge value. The immediate charge value can be the same as, less than, or greater than the recurring authorization amount (Invoice Subscription). Retrieve bank data: When listing an active Invoice Pull Subscription, we return account, bank, branch, and CPF information in the data field for the user who accepted the authorization. |
| `displayDescription` | STRING | Description presented to the payer. |
| `due` | STRING | Due date for payer approval or denial. |
| `end` | STRING | Final date of the subscription. |
| `externalId` | STRING | Unique external ID to prevent duplicate subscriptions. |
| `id` | STRING | Unique id for the subscription. |
| `interval` | STRING | Cycle definition. Options: "week", "month", "quarter", "semester", "year". |
| `name` | STRING | Debtor full name. |
| `pullMode` | STRING | Manual: The Stark client is responsible for creating the Invoice and performing both attempts and retries for settlement. If the authorization amount is zero (i.e., variable amount), the pullMode must be "manual". Automatic: Stark Bank is responsible for creating the Invoice with fixed amount as well as the attempts and retries for settlement (scheduled on d+2, d+4, and d+6). |
| `pullRetryLimit` | INTEGER | Number of retries allowed. Options: 0, 3. |
| `referenceCode` | STRING | Unique reference code for the contract. |
| `start` | STRING | Expected date to settle first pull request. |
| `status` | STRING | Current subscription status. |
| `tags` | LIST OF STRINGS | Tags associated with the subscription. |
| `taxId` | STRING | Debtor CPF or CNPJ. |
| `type` | STRING | Subscription journey type. Options: "push", "qrcode", "qrcodeAndPayment", "paymentAndOrQrCode". |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### The Invoice Pull Subscription Status

Invoice Pull Subscriptions will have the following life cycle:

| Status | Description |
| --- | --- |
| Created | The Invoice Pull Subscription was created in Stark Bank. |
| Failed | The Invoice Pull Subscription was unsuccessful. |
| Active | The Invoice Pull Subscription was successfully accepted by the payer. |
| Canceled | The Invoice Pull Subscription was canceled (it can be canceled by the payer or the receiver). |
| Expired | The Invoice Pull Subscription achieved the final date and it is not active anymore. |

### The Invoice Pull Subscription Logs

Every time we change an Invoice Pull Subscription, we create a Log. Logs are pretty useful for understanding the life cycle of each subscription. Whenever a new Log is created, we will fire a webhook to your registered URL.

Check out this diagram to understand the possible Invoice Pull Subscription Logs:

| Log type | Status | Description |
| --- | --- | --- |
| Created | Created | The Invoice Pull Subscription was created in Stark Bank. |
| Approved | Created | The Invoice Pull Subscription was accepted and Stark Bank is confirming it. |
| Cancelling | Created | The Invoice Pull Subscription was canceled and Stark Bank is confirming it. |
| Failed | Failed | The Invoice Pull Subscription was unsuccessful. |
| Confirmed | Active | The Invoice Pull Subscription was successfully accepted by the payer. |
| Canceled | Canceled | The Invoice Pull Subscription was canceled (it can be canceled by the payer or the receiver). |
| Expired | Expired | The Invoice Pull Subscription achieved the final date and it is not active anymore. |

Note: You only receive these webhooks if you have the invoice-subscription subscription set.

### Creating Invoice Pull Subscriptions QR Code

To create an invoice pull subscription using a QR code, you must do a POST Invoice Pull Subscription defining the type of authorization journey that is expected. If it is a journey that uses a QR code, you will receive a field that contains the information of the QR code that can be used either to generate a QR code image or to use in the "copy & paste" function.

### Listen to Invoice Pull Subscription QR Code webhooks

After the QR code is read, the payer's bank is able to approve the subscription with the payer's information. At this point, it is expected to receive an inbound webhook of approval that represents that the subscription was accepted.

### Creating Invoice Pull Subscriptions with Push Notification

To create an invoice pull subscription using a push notification, you must do a POST Invoice Pull Subscription defining the type "pull" which is the first authorization journey.

### Listen to Invoice Pull Subscription Push Notification webhooks

After the push notification is delivered to the user, the payer's bank is able to approve the subscription with the payer's information. At this point, it is expected to receive an inbound webhook of approval that represents that the subscription was accepted.

### Cancelling Invoice Pull Subscriptions

When an Invoice Pull Subscription is canceled either by you or the payer's bank, we create a log and send a webhook confirming that the subscription was terminated. It is possible to identify the cause of cancellation through the "reason" field. The possible reasons are described below:

NOTE: Only created or active subscriptions can be canceled.

| Reason | Description |
| --- | --- |
| accountClosed | The payer account is closed. |
| invalidSenderAccountNumber | The payer account number is not valid or was closed. |
| receiverOrganizationClosed | The receiver organization was closed. |
| senderDeceased | The payer user passed away. |
| subscriptionRequestFailed | The payer bank had an internal error to accept the subscription. |
| fraud | The payer bank identified a fraud. |
| subscriptionRequestNotResponded | The subscription was not answered by the payer bank. |
| subscriptionRequestAlreadyResponded | The subscription request was already responded through another journey. |
| receiverUserRequested | The cancelation was requested by the Stark Bank client. |
| senderUserRequested | The payer requested the cancelation. |
| subscriptionRequestNotResponded | The subscription request was not responded by the payer bank. |
| notRespondedBySender | The subscription request expired. |
| userRejected | The user denied the subscription (first journey). |
| duplicatedSubscription | The user already confirmed the subscription previously. |
| paymentNotFound | The payment was not found to authorize the subscription (third journey). |

## Invoice Pull Request Overview

An Invoice Pull Request is a command sent to the payer's bank to trigger the automatic debit of a previously issued invoice linked to an active Invoice Pull Subscription. It confirms the receiver's intent to collect the agreed amount within the current billing cycle and initiates the settlement process through the Pix infrastructure.

### The Invoice Pull Request Object

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the pull request. |
| `attemptType` | STRING | Type of attempt. Options: "default", "retry". |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `displayDescription` | STRING | Description presented to the payer. |
| `due` | STRING | Expected date of settlement. |
| `externalId` | STRING | Unique external ID for the pull request. |
| `installmentId` | STRING | ID of the installment linked to the pull request. |
| `invoiceId` | STRING | ID of the invoice to be pulled. |
| `status` | STRING | Current pull request status. |
| `subscriptionId` | STRING | ID of the invoice pull subscription. |
| `tags` | LIST OF STRINGS | Tags associated with the pull request. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### The Invoice Pull Request Status

Invoice Pull Requests will have the following life cycle:

| Status | Description |
| --- | --- |
| Created | The Invoice Pull Request was created in Stark Bank. |
| Pending | The Invoice Pull Request was sent by Stark Bank. |
| Scheduled | The Invoice Pull Request created the payment schedule in the payer's bank. |
| Success | The Invoice Pull Request created a successful settlement. |
| Canceled | The Invoice Pull Request was canceled. |
| Failed | The Invoice Pull Request was unsuccessful. |

### The Invoice Pull Request Logs

Every time we change an Invoice Pull Request, we create a Log. Logs are pretty useful for understanding the life cycle of each pull request.

Whenever a new Log is created, we will fire a webhook to your registered URL. Check out this diagram to understand the possible Invoice Pull Request Logs:

| Log type | Status | Description |
| --- | --- | --- |
| Created | Created | The Invoice Pull Request was created in Stark Bank. |
| Pending | Pending | The Invoice Pull Request was sent by Stark Bank. |
| Scheduled | Scheduled | The Invoice Pull Request created the payment schedule in the payer's bank. |
| Success | Success | The Invoice Pull Request created a successful settlement. |
| Cancelling | Scheduled | The Invoice Pull Request is in the process of cancellation. |
| Canceled | Canceled | The Invoice Pull Request was canceled. |
| Failed | Failed | The Invoice Pull Request was unsuccessful. |

Note: You only receive these webhooks if you have the invoice-pull-request subscription set.

### Creating Invoice Pull Requests

To create an invoice pull request, you must do a POST Invoice Pull Request.

### Listen to Invoice Pull Request webhooks

You can subscribe to receive notifications for events related to Invoice Pull Requests by setting up a webhook with the "invoice-pull-request" subscription. This allows you to stay informed about the status and updates of your Invoice Pull Requests in real-time.

### Cancelling Invoice Pull Requests

To cancel an Invoice Pull Request you must DELETE it. Only pending or scheduled pull requests can be canceled.

When an Invoice Pull Request is canceled either by you or the payer's bank, we create a log and send a webhook confirming that the request was canceled. It is possible to identify the cause of cancellation through the "reason" field. The possible reasons are described below:

| Reason | Description |
| --- | --- |
| senderInternalError | The payer had an internal error to create the pull request. |
| senderAccountClosed | The payer account was closed. |
| senderAccountBlocked | The payer account is blocked. |
| internalSettlementNotAllowed | Cannot send requests or update an account within the same institution or participant. |
| amountNotAllowed | The request amount exceeds the max amount limit of the subscription. |
| wrongAmount | The amount on the request does not match the accepted amount on the subscription. |
| senderTaxIdMismatch | The payer tax ID does not match the tax ID of subscription. |
| participantNotActive | The participant is not active on the SPI. |
| invalidDueDate | The due date of pull request is incoherent with subscription interval. |
| invalidRetryDate | The pull request retry was sent after the allowed date. |
| invalidTimePeriod | The pull request was sent out of the allowed time period. |
| retryNotAllowed | The subscription does not allow pull request retries. |
| invalidSubscriptionBacenId | The subscription Bacen ID is invalid or not found. |
| invalidAction | The subscription is not confirmed. |
| repeatedPullRequest | A pull request for the same subscription and interval is already scheduled. |
| pullRequestAlreadySettled | A pull request for the same subscription and interval has already succeeded. |
| invalidAttemptType | The pull request retry does not correspond with a previously failed pull request. |
| retryLimitExceeded | The number of allowed pull request retries has been exceeded. |
| invalidSenderBankCode | The debtor bank code is invalid or missing. |
| invalidSenderFinalTaxId | The debtor tax ID is invalid or not found. |
| accountClosed | The payer account was closed. |
| accountBlocked | The payer account is blocked. |
| NotSettled | The request was not settled. |
| subscriptionCanceled | The subscription was canceled. |
| pixRequestFailed | The payer bank had an internal error to settle the Pix. |
| other | The payer bank did not define the specific reason. |
| receiverUserRequested | The cancelation was requested by the Stark Bank client. |
| senderUserRequested | The payer requested the cancelation. |

---

## Other Languages

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