Overview

Setup

Authorization Journeys

Rules & Limits

Sandbox

Pull Subscriptions

Invoice Pull Subscription Overview

The Invoice Pull Subscription Object

Creating Invoice Pull Subscriptions QR Code

Listen to Invoice Pull Subscription QR Code webhooks

Creating Invoice Pull Subscriptions with Push Notification

Listen to Invoice Pull Subscription Push Notification webhooks

Cancelling Invoice Pull Subscriptions

Pull Requests

Invoice Pull Request Overview

The Invoice Pull Request Object

Creating Invoice Pull Requests

Listen to Invoice Pull Request webhooks

Cancelling Invoice Pull Requests

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 Subscription
A 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.
Invoice
Represents 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 Request
Triggers 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:

ReasonLog TypeAction
receiverUserRequestcanceledCreate 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.
pixRequestFailedcanceledIntraday retry (Stark Bank will retry on behalf of the Stark client).
notSettledfailedRetry 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 Status

Invoice Pull Subscriptions will have the following life cycle:

invoice-pull-subscription-status

StatusDescription
CreatedThe Invoice Pull Subscription was created in Stark Bank.
FailedThe Invoice Pull Subscription was unsuccessful.
ActiveThe Invoice Pull Subscription was successfully accepted by the payer.
CanceledThe Invoice Pull Subscription was canceled (it can be canceled by the payer or the receiver).
ExpiredThe 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:

invoice-pull-subscription-log

Log typeStatusDescription
CreatedCreatedThe Invoice Pull Subscription was created in Stark Bank.
ApprovedCreatedThe Invoice Pull Subscription was accepted and Stark Bank is confirming it.
CancellingCreatedThe Invoice Pull Subscription was canceled and Stark Bank is confirming it.
FailedFailedThe Invoice Pull Subscription was unsuccessful.
ConfirmedActiveThe Invoice Pull Subscription was successfully accepted by the payer.
CanceledCanceledThe Invoice Pull Subscription was canceled (it can be canceled by the payer or the receiver).
ExpiredExpiredThe 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.

The Invoice Pull Subscription Object

Attributes

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

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.

invoice-pull-subscription-qr-code

Python

import starkbank

subscriptions = starkbank.invoicepullsubscription.create([
    starkbank.InvoicePullSubscription(
        amount=0,
        amount_min_limit=5000,
        display_description="Dragon Travel Fare",
        external_id="b7e6a2c2-8e2b-4c1a-9e2a-123456789abc",
        interval="month",
        name="John Snow",
        pull_mode="manual",
        pull_retry_limit=3,
        start="2025-09-14T00:00:00Z",
        end="2025-10-14T00:00:00Z",
        reference_code="contract-12345",
        tags=[],
        tax_id="012.345.678-90",
        type="qrcode"
    ),
])

for subscription in subscriptions:
    print(subscription)

Javascript

const starkbank = require('starkbank');

(async() => {
    let subscriptions = await starkbank.invoicePullSubscription.create([{
        amount: 0,
        amountMinLimit: 5000,
        displayDescription: 'Dragon Travel Fare',
        externalId: 'e0ef6c02-f58e-44cd-b04d-e914d4df9405',
        interval: 'month',
        name: 'John Snow',
        pullMode: 'manual',
        pullRetryLimit: 3,
        start: '2025-09-14',
        end: '2025-10-14',
        referenceCode: 'contract-12345',
        tags: [],
        taxId: '012.345.678-90',
        type: 'qrcode'
    }]);

    for (let subscription of subscriptions) {
        console.log(subscription);
    }
})();

PHP

$subscriptions = StarkBankInvoicePullSubscription::create([
    new StarkBankInvoicePullSubscription([
        "amount" => 0,
        "amountMinLimit" => 5000,
        "data" => [
            "amount" => 400000,
            "due" => '2025-10-27',
            "fine" => 2.5,
            "interest" => 1.3
        ],
        "displayDescription" => "Dragon Travel Fare",
        "due" => '2025-10-27',
        "end" => '2025-10-27',
        "externalId" => "php-1911425039",
        "interval" => "month",
        "name" => "John Snow",
        "pullMode" => "manual",
        "pullRetryLimit" => 3,
        "referenceCode" => "contract-12345",
        "start" => '2025-09-22',
        "tags" => [],
        "taxId" => "012.345.678-90",
        "type" => "paymentAndOrQrcode",
    ])
]);

foreach ($subscriptions as $subscription) {
    print_r($subscription);
}

Java

import com.starkbank.*;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;

List subscriptions = new ArrayList<>();

HashMap classData = new HashMap<>();
classData.put("start", "2025-09-30");
classData.put("interval", "month");
classData.put("pullMode", "manual");
classData.put("pullRetryLimit", 3L);
classData.put("type", "paymentAndOrQrcode");
classData.put("amount", 0L);
classData.put("amountMinLimit", 5000L);
classData.put("displayDescription", "Dragon Travel Fare");
classData.put("externalId", "a119bc87-68ac-4558-8a54-22196beebf68");
classData.put("referenceCode", "contract-12345");
classData.put("end", "2025-10-30");
classData.put("name", "John Snow");
classData.put("taxId", "012.345.678-90");
classData.put("tags", new String[]{});

HashMap data = new HashMap<>();
data.put("amount", 400000L);
data.put("due", "2026-06-26T17:59:26.000000+00:00");
data.put("fine", 2.5);
data.put("interest", 1.3);

classData.put("data", data);

subscriptions.add(new InvoicePullSubscription(classData));

subscriptions = InvoicePullSubscription.create(subscriptions);

for (InvoicePullSubscription subscription : subscriptions) {
    System.out.println(subscription);
}

Ruby

Not yet available. Please contact us if you need this SDK.

Elixir

Not yet available. Please contact us if you need this SDK.

C#

using System;
using System.Collections.Generic;

List<StarkBank.InvoicePullSubscription> subscriptions = StarkBank.InvoicePullSubscription.Create(
    new List<StarkBank.InvoicePullSubscription> {
        new InvoicePullSubscription(
            amount: 1000000,
            amountMinLimit: 5000,
            displayDescription: "Dragon Travel Fare",
            externalID: "f4a4c70b-bf5a-400d-8eae-685128691645",
            interval: "month",
            name: "John Snow",
            pullMode: "manual",
            pullRetryLimit: 3,
            start: new DateTime(2025, 9, 14, 0, 0, 0, DateTimeKind.Utc),
            end: new DateTime(2025, 10, 14, 0, 0, 0, DateTimeKind.Utc),
            referenceCode: "contract-12345",
            tags: new List<string>(),
            taxID: "012.345.678-90",
            type: "qrcode"
        )
    }
);

foreach (StarkBank.InvoicePullSubscription subscription in subscriptions)
{
    Console.WriteLine(subscription);
}

Go

package main

import (
    "fmt"
    "time"
    "github.com/starkbank/sdk-go/starkbank/invoicepullsubscription"
)

func main() {

    start := time.Date(2025, 11, 3, 0, 0, 0, 0, time.UTC)
    end := time.Date(2025, 12, 3, 0, 0, 0, 0, time.UTC)
	  due := time.Date(2025, 11, 3, 0, 0, 0, 0, time.UTC)
    data := map[string]interface{}{
			"amount":   400000,
			"due":      &due,
			"fine":     2.5,
			"interest": 1.3,
    }

    invoicePullSubscription, err := invoicepullsubscription.Create(
        []invoicepullsubscription.InvoicePullSubscription{
            {
              Amount:            1000000,
              AmountMinLimit:    5000,
              Data:              data,
              DisplayDescription: "Dragon Travel Fare",
              ExternalId:        fmt.Sprintf("my_external_id_x"),
              Interval:          "month",
              Name:              "John Snow",
              PullMode:          "manual",
              PullRetryLimit:    3,
              Start:             &start,
              End:               &end,
              ReferenceCode:     "contract-12345",
              Tags:              []string{},
              TaxId:             "012.345.678-90",
              Type:              "paymentAndOrQrcode",
            },
        }, nil)

    if err.Errors != nil {
        for _, e := range err.Errors {
            fmt.Printf("code: %s, message: %s", e.Code, e.Message)
        }
    }

    subscription := invoicePullSubscription[0]
    fmt.Printf("%+v", subscription)
}

Clojure

Not yet available. Please contact us if you need this SDK.

Curl

curl --location --request POST '{{baseUrl}}/v2/invoice-pull-subscription' 
--header 'Access-Id: {{accessId}}' 
--header 'Access-Time: {{accessTime}}' 
--header 'Access-Signature: {{accessSignature}}' 
--header 'Content-Type: application/json' 
--data-raw '{
    "subscriptions": [
        {
            "amount": 0,
            "amountMinLimit": 5000,
            "displayDescription": "Dragon Travel Fare",
            "externalId": "b7e6a2c2-8e2b-4c1a-9e2a-123456789abc",
            "interval": "month",
            "name": "John Snow",
            "pullMode": "manual",
            "pullRetryLimit": 3,
            "start": "2025-09-14",
            "end": "2025-10-14",
            "referenceCode": "contract-12345",
            "tags": [],
            "taxId": "012.345.678-90",
            "type": "qrcode"
        }
    ]
}'
RESPONSE

Python

InvoicePullSubscription(
    amount=0,
    amount_min_limit=5000,
    bacen_id=RR2001818320250904xDUK7RgCRT4,
    brcode=00020101021226180014br.gov.bcb.pix5204000053039865802BR5925Stark Sociedade de Credit6009Sao Paulo62070503***80930014br.gov.bcb.pix2571brcode-h.sandbox.starkinfra.com/v2/rec/112e7e1d69aa4c11a9c37810e2038da863041EC6
    created=2025-09-04 20:57:33.833777,
    display_description=Dragon Travel Fare,
    due=2025-09-14 00:00:00,
    end=2025-10-14 00:00:00,
    external_id=b7e6a2c2-8e2b-4c1a-9e2a-123456789abc,
    id=5656565656565656,
    interval=month,
    name=John Snow,
    pull_mode=manual,
    pull_retry_limit=3,
    reference_code=contract-12345,
    start=2025-09-14 00:00:00,
    status=active,
    tags=[],
    tax_id=012.345.678-90,
    type=qrcode,
    updated=2025-09-14 00:00:00
)

Javascript

InvoicePullSubscription {
  id: '4656724615102464',
  start: '2025-09-14T03:00:00+00:00',
  interval: 'month',
  pullMode: 'manual',
  pullRetryLimit: 3,
  type: 'qrcode',
  amount: 0,
  amountMinLimit: 5000,
  displayDescription: 'Dragon Travel Fare',
  due: '2025-09-11T21:42:35.878330+00:00',
  externalId: 'e0ef6c02-f58e-44cd-b04d-e914d4df9405',
  referenceCode: 'contract-12345',
  end: '2025-10-14T03:00:00+00:00',
  name: 'John Snow',
  taxId: '012.345.678-90',
  tags: [],
  status: 'created',
  bacenId: 'RR2001818320250909WDW2JAoiyB2',
  installmentId: null,
  created: '2025-09-09T21:42:36.419070+00:00',
  updated: '2025-09-09T21:42:36.419078+00:00',
  brcode: '00020101021226180014br.gov.bcb.pix5204000053039865802BR5925Stark Sociedade de Credit6009Sao Paulo62070503***80930014br.gov.bcb.pix2571brcode-h.sandbox.starkinfra.com/v2/rec/112e7e1d69aa4c11a9c37810e2038da863041EC6'
}

PHP

StarkBankInvoicePullSubscription Object
(
    [id] => 5476396172312576
    [start] => DateTime Object
        (
            [date] => 2025-09-22 03:00:00.000000
            [timezone_type] => 1
            [timezone] => +00:00
        )

    [interval] => month
    [pullMode] => manual
    [pullRetryLimit] => 3
    [type] => paymentAndOrQrcode
    [amount] => 0
    [amountMinLimit] => 5000
    [displayDescription] => Dragon Travel Fare
    [due] => DateTime Object
        (
            [date] => 2025-10-28 02:59:59.999999
            [timezone_type] => 1
            [timezone] => +00:00
        )

    [externalId] => php-1911425039
    [referenceCode] => contract-12345
    [end] => DateTime Object
        (
            [date] => 2025-10-27 03:00:00.000000
            [timezone_type] => 1
            [timezone] => +00:00
        )

    [data] => Array
        (
            [accountNumber] => 
            [bankCode] => 
            [branchCode] => 
            [taxId] => 
            [invoiceId] => 4891494846562304
        )

    [name] => John Snow
    [taxId] => 012.345.678-90
    [tags] => Array
        (
        )

    [status] => created
    [bacenId] => RR3990842720250922pinlUU2L5FK
    [installmentId] => 
    [created] => DateTime Object
        (
            [date] => 2025-09-22 23:49:45.612723
            [timezone_type] => 1
            [timezone] => +00:00
        )

    [updated] => DateTime Object
        (
            [date] => 2025-09-22 23:49:45.612731
            [timezone_type] => 1
            [timezone] => +00:00
        )

    [brcode] => 00020101021226940014br.gov.bcb.pix2572brcode-h.sandbox.starkinfra.com/v2/cobv/70858fab3c5a4f1d90b6251bf1fce7545204000053039865802BR5925Stark Sociedade de Credit6009Sao Paulo62070503***80930014br.gov.bcb.pix2571brcode-h.sandbox.starkinfra.com/v2/rec/70858fab3c5a4f1d90b6251bf1fce7546304BEE0
)

Java

InvoicePullSubscription({
  "start": "2025-09-30T03:00:00+00:00",
  "interval": "month",
  "pullMode": "manual",
  "pullRetryLimit": 3,
  "type": "paymentAndOrQrcode",
  "amount": 0,
  "amountMinLimit": 5000,
  "displayDescription": "Dragon Travel Fare",
  "due": "2025-09-27T19:10:03.212836+00:00",
  "externalId": "a119bc87-68ac-4558-8a54-22196beebf68",
  "referenceCode": "contract-12345",
  "end": "2025-10-30T03:00:00+00:00",
  "data": {
    "accountNumber": "",
    "bankCode": "",
    "branchCode": "",
    "taxId": "",
    "invoiceId": "5115176743337984"
  },
  "name": "John Snow",
  "taxId": "012.345.678-90",
  "tags": [],
  "status": "created",
  "bacenId": "RR2001818320250925Hwxx57HVzsx",
  "brcode": "00020101021226940014br.gov.bcb.pix2572brcode-h.sandbox.starkinfra.com/v2/cobv/d8c82e1aac93422a98a6aabf818d3d425204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***80930014br.gov.bcb.pix2571brcode-h.sandbox.starkinfra.com/v2/rec/d8c82e1aac93422a98a6aabf818d3d426304AE03",
  "created": "2025-09-25T19:10:06.675254+00:00",
  "updated": "2025-09-25T19:10:06.675262+00:00",
  "id": "4715015777026048"
})

Ruby

Not yet available. Please contact us if you need this SDK.

Elixir

Not yet available. Please contact us if you need this SDK.

C#

InvoicePullSubscription(
  Start: 9/14/2025 12:00:00AM,
  Interval: month,
  PullMode: manual,
  PullRetryLimit: 3,
  Type: qrcode,
  Amount: 1000000,
  AmountMinLimit: 5000,
  DisplayDescription: Dragon Travel Fare,
  Due: 9/11/2025 6:58:02PM,
  ExternalID: f4a4c70b-bf5a-400d-8eae-685128691645,
  ReferenceCode: contract-12345,
  End: 10/14/2025 12:00:00AM,
  Name: John Snow,
  TaxID: 012.345.678-90,
  Tags: {  },
  Status: created,
  BacenID: RR2001818320250909fxSoQw3VO04,
  Brcode: 00020101021226180014br.gov.bcb.pix5204000053039865802BR5925Stark Sociedade de Credit6009Sao Paulo62070503***80930014br.gov.bcb.pix2571brcode-h.sandbox.starkinfra.com/v2/rec/112e7e1d69aa4c11a9c37810e2038da863041EC6,
  Created: 9/9/2025 6:58:03PM,
  Updated: 9/9/2025 6:58:03PM,
  ID: 4582433332658176
)

Go

{
    Id:4879987618349056
    Start:2025-11-03 03:00:00 +0000 +0000
    Interval:month
    PullMode:manual
    PullRetryLimit:3
    Type:paymentAndOrQrcode
    Amount:1000000
    AmountMinLimit:5000
    DisplayDescription:Dragon Travel Fare
    Due:2025-11-01 18:31:12.093382 +0000 +0000
    ExternalId:my_external_id
    ReferenceCode:contract-12345
    End:2025-12-03 03:00:00 +0000 +0000
    Data:map[accountNumber: amount:400000 bankCode: branchCode: due:2025-11-03 00:00:00 +0000 UTC fine:2.5 interest:1.3 invoiceId:6423983947776000 taxId:]
    Name:John Snow
    TaxId:012.345.678-90
    Tags:[]
    Status:created
    BacenId:RR2001818320251030TJXeAo9rTrq
    Brcode:00020101021226940014br.gov.bcb.pix2572brcode-h.sandbox.starkinfra.com/v2/cobv/e52bd01806ed42b987e51993540820c75204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***80930014br.gov.bcb.pix2571brcode-h.sandbox.starkinfra.com/v2/rec/e52bd01806ed42b987e51993540820c763045188
    Created:2025-10-30 18:31:12.582504 +0000 +0000
    Updated:2025-10-30 18:31:12.582511 +0000 +0000
}

Clojure

Not yet available. Please contact us if you need this SDK.

Curl

{
    "message": "Subscriptions successfully created",
    "subscriptions": [
        {
            "amount": 0,
            "amountMinLimit": 5000,
            "bacenId": "RR20018183202509096amQtgYdMTf",
            "brcode": "00020101021226180014br.gov.bcb.pix5204000053039865802BR5925Stark Sociedade de Credit6009Sao Paulo62070503***80930014br.gov.bcb.pix2571brcode-h.sandbox.starkinfra.com/v2/rec/112e7e1d69aa4c11a9c37810e2038da863041EC6",
            "created": "2025-09-09T21:34:55.854022+00:00",
            "updated": "2025-09-09T21:34:55.854028+00:00",
            "displayDescription": "Dragon Travel Fare",
            "referenceCode": "contract-12345",
            "due": "2025-09-11T21:34:55.157021+00:00",
            "externalId": "b7e6a2c2-8e2b-4c1a-9e2a-123456789abc",
            "id": "6633844090339328",
            "start": "2025-09-14T03:00:00+00:00",
            "end": "2025-10-14T03:00:00+00:00",
            "interval": "month",
            "data": {},
            "pullMode": "manual",
            "pullRetryLimit": 3,
            "name": "John Snow",
            "taxId": "012.345.678-90",
            "status": "created",
            "tags": [],
            "type": "qrcode"
        }
    ]
}

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.

RESPONSE

Python

{
   "event":{
      "id":"5054340314169344",
      "subscription":"invoice-subscription",
      "created":"2025-07-29T18:00:22.593217+00:00",
      "workspaceId":"6275127679385600",
      "isDelivered":true,
      "log":{
         "created":"2025-01-01T18:58:40.092412+00:00",
         "errors":[],
         "id":"5506769686102016",
         "subscription":{
            "amount":0,
            "amountMinLimit":5000,
            "bacenId":"RN000000002025010199999999999",
            "brcode":"00020101021226600014br.gov.bcb.pix2538invoice-h.sandbox.starkbank.com/57301741758054405204000053039865802BR5910NightKing6010Winterfell62280524invoice/573017417580544063046B79",
            "created":"2025-01-01T18:58:38.092412+00:00",
            "data":{
               "amount":400000,
               "due":"2026-05-12T17:59:26.000000+00:00",
               "fine":2.5,
               "interest":1.3
            },
            "displayDescription":"Dragon Travel Fare",
            "due":"2025-01-03T18:58:38.092412+00:00",
            "end":"2025-06-16T00:00:00.000000+00:00",
            "externalId":"my-unique-id-12345678",
            "id":"5632510516002816",
            "interval":"month",
            "name":"John Snow",
            "pullMode":"manual",
            "pullRetryLimit":3,
            "referenceCode":"contract-12345",
            "start":"2025-01-16T00:00:00.000000+00:00",
            "status":"active",
            "tags":[
                "order/123",
                "customer/456"
            ],
            "taxId":"012.345.678-90",
            "type":"paymentAndOrQrcode",
            "updated":"2025-01-01T18:58:38.092412+00:00"
         },
         "type":"confirmed"
      }
   }
}

Javascript

{
   "event":{
      "id":"5054340314169344",
      "subscription":"invoice-subscription",
      "created":"2025-07-29T18:00:22.593217+00:00",
      "workspaceId":"6275127679385600",
      "isDelivered":true,
      "log":{
         "created":"2025-01-01T18:58:40.092412+00:00",
         "errors":[],
         "id":"5506769686102016",
         "subscription":{
            "amount":0,
            "amountMinLimit":5000,
            "bacenId":"RN000000002025010199999999999",
            "brcode":"00020101021226600014br.gov.bcb.pix2538invoice-h.sandbox.starkbank.com/57301741758054405204000053039865802BR5910NightKing6010Winterfell62280524invoice/573017417580544063046B79",
            "created":"2025-01-01T18:58:38.092412+00:00",
            "data":{
               "amount":400000,
               "due":"2026-05-12T17:59:26.000000+00:00",
               "fine":2.5,
               "interest":1.3
            },
            "displayDescription":"Dragon Travel Fare",
            "due":"2025-01-03T18:58:38.092412+00:00",
            "end":"2025-06-16T00:00:00.000000+00:00",
            "externalId":"my-unique-id-12345678",
            "id":"5632510516002816",
            "interval":"month",
            "name":"John Snow",
            "pullMode":"manual",
            "pullRetryLimit":3,
            "referenceCode":"contract-12345",
            "start":"2025-01-16T00:00:00.000000+00:00",
            "status":"active",
            "tags":[
                "order/123",
                "customer/456"
            ],
            "taxId":"012.345.678-90",
            "type":"paymentAndOrQrcode",
            "updated":"2025-01-01T18:58:38.092412+00:00"
         },
         "type":"confirmed"
      }
   }
}

PHP

{
   "event":{
      "id":"5054340314169344",
      "subscription":"invoice-subscription",
      "created":"2025-07-29T18:00:22.593217+00:00",
      "workspaceId":"6275127679385600",
      "isDelivered":true,
      "log":{
         "created":"2025-01-01T18:58:40.092412+00:00",
         "errors":[],
         "id":"5506769686102016",
         "subscription":{
            "amount":0,
            "amountMinLimit":5000,
            "bacenId":"RN000000002025010199999999999",
            "brcode":"00020101021226600014br.gov.bcb.pix2538invoice-h.sandbox.starkbank.com/57301741758054405204000053039865802BR5910NightKing6010Winterfell62280524invoice/573017417580544063046B79",
            "created":"2025-01-01T18:58:38.092412+00:00",
            "data":{
               "amount":400000,
               "due":"2026-05-12T17:59:26.000000+00:00",
               "fine":2.5,
               "interest":1.3
            },
            "displayDescription":"Dragon Travel Fare",
            "due":"2025-01-03T18:58:38.092412+00:00",
            "end":"2025-06-16T00:00:00.000000+00:00",
            "externalId":"my-unique-id-12345678",
            "id":"5632510516002816",
            "interval":"month",
            "name":"John Snow",
            "pullMode":"manual",
            "pullRetryLimit":3,
            "referenceCode":"contract-12345",
            "start":"2025-01-16T00:00:00.000000+00:00",
            "status":"active",
            "tags":[
                "order/123",
                "customer/456"
            ],
            "taxId":"012.345.678-90",
            "type":"paymentAndOrQrcode",
            "updated":"2025-01-01T18:58:38.092412+00:00"
         },
         "type":"confirmed"
      }
   }
}

Java

{
   "event":{
      "id":"5054340314169344",
      "subscription":"invoice-subscription",
      "created":"2025-07-29T18:00:22.593217+00:00",
      "workspaceId":"6275127679385600",
      "isDelivered":true,
      "log":{
         "created":"2025-01-01T18:58:40.092412+00:00",
         "errors":[],
         "id":"5506769686102016",
         "subscription":{
            "amount":0,
            "amountMinLimit":5000,
            "bacenId":"RN000000002025010199999999999",
            "brcode":"00020101021226600014br.gov.bcb.pix2538invoice-h.sandbox.starkbank.com/57301741758054405204000053039865802BR5910NightKing6010Winterfell62280524invoice/573017417580544063046B79",
            "created":"2025-01-01T18:58:38.092412+00:00",
            "data":{
               "amount":400000,
               "due":"2026-05-12T17:59:26.000000+00:00",
               "fine":2.5,
               "interest":1.3
            },
            "displayDescription":"Dragon Travel Fare",
            "due":"2025-01-03T18:58:38.092412+00:00",
            "end":"2025-06-16T00:00:00.000000+00:00",
            "externalId":"my-unique-id-12345678",
            "id":"5632510516002816",
            "interval":"month",
            "name":"John Snow",
            "pullMode":"manual",
            "pullRetryLimit":3,
            "referenceCode":"contract-12345",
            "start":"2025-01-16T00:00:00.000000+00:00",
            "status":"active",
            "tags":[
                "order/123",
                "customer/456"
            ],
            "taxId":"012.345.678-90",
            "type":"paymentAndOrQrcode",
            "updated":"2025-01-01T18:58:38.092412+00:00"
         },
         "type":"confirmed"
      }
   }
}

Ruby

{
   "event":{
      "id":"5054340314169344",
      "subscription":"invoice-subscription",
      "created":"2025-07-29T18:00:22.593217+00:00",
      "workspaceId":"6275127679385600",
      "isDelivered":true,
      "log":{
         "created":"2025-01-01T18:58:40.092412+00:00",
         "errors":[],
         "id":"5506769686102016",
         "subscription":{
            "amount":0,
            "amountMinLimit":5000,
            "bacenId":"RN000000002025010199999999999",
            "brcode":"00020101021226600014br.gov.bcb.pix2538invoice-h.sandbox.starkbank.com/57301741758054405204000053039865802BR5910NightKing6010Winterfell62280524invoice/573017417580544063046B79",
            "created":"2025-01-01T18:58:38.092412+00:00",
            "data":{
               "amount":400000,
               "due":"2026-05-12T17:59:26.000000+00:00",
               "fine":2.5,
               "interest":1.3
            },
            "displayDescription":"Dragon Travel Fare",
            "due":"2025-01-03T18:58:38.092412+00:00",
            "end":"2025-06-16T00:00:00.000000+00:00",
            "externalId":"my-unique-id-12345678",
            "id":"5632510516002816",
            "interval":"month",
            "name":"John Snow",
            "pullMode":"manual",
            "pullRetryLimit":3,
            "referenceCode":"contract-12345",
            "start":"2025-01-16T00:00:00.000000+00:00",
            "status":"active",
            "tags":[
                "order/123",
                "customer/456"
            ],
            "taxId":"012.345.678-90",
            "type":"paymentAndOrQrcode",
            "updated":"2025-01-01T18:58:38.092412+00:00"
         },
         "type":"confirmed"
      }
   }
}

Elixir

{
   "event":{
      "id":"5054340314169344",
      "subscription":"invoice-subscription",
      "created":"2025-07-29T18:00:22.593217+00:00",
      "workspaceId":"6275127679385600",
      "isDelivered":true,
      "log":{
         "created":"2025-01-01T18:58:40.092412+00:00",
         "errors":[],
         "id":"5506769686102016",
         "subscription":{
            "amount":0,
            "amountMinLimit":5000,
            "bacenId":"RN000000002025010199999999999",
            "brcode":"00020101021226600014br.gov.bcb.pix2538invoice-h.sandbox.starkbank.com/57301741758054405204000053039865802BR5910NightKing6010Winterfell62280524invoice/573017417580544063046B79",
            "created":"2025-01-01T18:58:38.092412+00:00",
            "data":{
               "amount":400000,
               "due":"2026-05-12T17:59:26.000000+00:00",
               "fine":2.5,
               "interest":1.3
            },
            "displayDescription":"Dragon Travel Fare",
            "due":"2025-01-03T18:58:38.092412+00:00",
            "end":"2025-06-16T00:00:00.000000+00:00",
            "externalId":"my-unique-id-12345678",
            "id":"5632510516002816",
            "interval":"month",
            "name":"John Snow",
            "pullMode":"manual",
            "pullRetryLimit":3,
            "referenceCode":"contract-12345",
            "start":"2025-01-16T00:00:00.000000+00:00",
            "status":"active",
            "tags":[
                "order/123",
                "customer/456"
            ],
            "taxId":"012.345.678-90",
            "type":"paymentAndOrQrcode",
            "updated":"2025-01-01T18:58:38.092412+00:00"
         },
         "type":"confirmed"
      }
   }
}

C#

{
   "event":{
      "id":"5054340314169344",
      "subscription":"invoice-subscription",
      "created":"2025-07-29T18:00:22.593217+00:00",
      "workspaceId":"6275127679385600",
      "isDelivered":true,
      "log":{
         "created":"2025-01-01T18:58:40.092412+00:00",
         "errors":[],
         "id":"5506769686102016",
         "subscription":{
            "amount":0,
            "amountMinLimit":5000,
            "bacenId":"RN000000002025010199999999999",
            "brcode":"00020101021226600014br.gov.bcb.pix2538invoice-h.sandbox.starkbank.com/57301741758054405204000053039865802BR5910NightKing6010Winterfell62280524invoice/573017417580544063046B79",
            "created":"2025-01-01T18:58:38.092412+00:00",
            "data":{
               "amount":400000,
               "due":"2026-05-12T17:59:26.000000+00:00",
               "fine":2.5,
               "interest":1.3
            },
            "displayDescription":"Dragon Travel Fare",
            "due":"2025-01-03T18:58:38.092412+00:00",
            "end":"2025-06-16T00:00:00.000000+00:00",
            "externalId":"my-unique-id-12345678",
            "id":"5632510516002816",
            "interval":"month",
            "name":"John Snow",
            "pullMode":"manual",
            "pullRetryLimit":3,
            "referenceCode":"contract-12345",
            "start":"2025-01-16T00:00:00.000000+00:00",
            "status":"active",
            "tags":[
                "order/123",
                "customer/456"
            ],
            "taxId":"012.345.678-90",
            "type":"paymentAndOrQrcode",
            "updated":"2025-01-01T18:58:38.092412+00:00"
         },
         "type":"confirmed"
      }
   }
}

Go

{
   "event":{
      "id":"5054340314169344",
      "subscription":"invoice-subscription",
      "created":"2025-07-29T18:00:22.593217+00:00",
      "workspaceId":"6275127679385600",
      "isDelivered":true,
      "log":{
         "created":"2025-01-01T18:58:40.092412+00:00",
         "errors":[],
         "id":"5506769686102016",
         "subscription":{
            "amount":0,
            "amountMinLimit":5000,
            "bacenId":"RN000000002025010199999999999",
            "brcode":"00020101021226600014br.gov.bcb.pix2538invoice-h.sandbox.starkbank.com/57301741758054405204000053039865802BR5910NightKing6010Winterfell62280524invoice/573017417580544063046B79",
            "created":"2025-01-01T18:58:38.092412+00:00",
            "data":{
               "amount":400000,
               "due":"2026-05-12T17:59:26.000000+00:00",
               "fine":2.5,
               "interest":1.3
            },
            "displayDescription":"Dragon Travel Fare",
            "due":"2025-01-03T18:58:38.092412+00:00",
            "end":"2025-06-16T00:00:00.000000+00:00",
            "externalId":"my-unique-id-12345678",
            "id":"5632510516002816",
            "interval":"month",
            "name":"John Snow",
            "pullMode":"manual",
            "pullRetryLimit":3,
            "referenceCode":"contract-12345",
            "start":"2025-01-16T00:00:00.000000+00:00",
            "status":"active",
            "tags":[
                "order/123",
                "customer/456"
            ],
            "taxId":"012.345.678-90",
            "type":"paymentAndOrQrcode",
            "updated":"2025-01-01T18:58:38.092412+00:00"
         },
         "type":"confirmed"
      }
   }
}

Clojure

{
   "event":{
      "id":"5054340314169344",
      "subscription":"invoice-subscription",
      "created":"2025-07-29T18:00:22.593217+00:00",
      "workspaceId":"6275127679385600",
      "isDelivered":true,
      "log":{
         "created":"2025-01-01T18:58:40.092412+00:00",
         "errors":[],
         "id":"5506769686102016",
         "subscription":{
            "amount":0,
            "amountMinLimit":5000,
            "bacenId":"RN000000002025010199999999999",
            "brcode":"00020101021226600014br.gov.bcb.pix2538invoice-h.sandbox.starkbank.com/57301741758054405204000053039865802BR5910NightKing6010Winterfell62280524invoice/573017417580544063046B79",
            "created":"2025-01-01T18:58:38.092412+00:00",
            "data":{
               "amount":400000,
               "due":"2026-05-12T17:59:26.000000+00:00",
               "fine":2.5,
               "interest":1.3
            },
            "displayDescription":"Dragon Travel Fare",
            "due":"2025-01-03T18:58:38.092412+00:00",
            "end":"2025-06-16T00:00:00.000000+00:00",
            "externalId":"my-unique-id-12345678",
            "id":"5632510516002816",
            "interval":"month",
            "name":"John Snow",
            "pullMode":"manual",
            "pullRetryLimit":3,
            "referenceCode":"contract-12345",
            "start":"2025-01-16T00:00:00.000000+00:00",
            "status":"active",
            "tags":[
                "order/123",
                "customer/456"
            ],
            "taxId":"012.345.678-90",
            "type":"paymentAndOrQrcode",
            "updated":"2025-01-01T18:58:38.092412+00:00"
         },
         "type":"confirmed"
      }
   }
}

Curl

{
   "event":{
      "id":"5054340314169344",
      "subscription":"invoice-subscription",
      "created":"2025-07-29T18:00:22.593217+00:00",
      "workspaceId":"6275127679385600",
      "isDelivered":true,
      "log":{
         "created":"2025-01-01T18:58:40.092412+00:00",
         "errors":[],
         "id":"5506769686102016",
         "subscription":{
            "amount":0,
            "amountMinLimit":5000,
            "bacenId":"RN000000002025010199999999999",
            "brcode":"00020101021226600014br.gov.bcb.pix2538invoice-h.sandbox.starkbank.com/57301741758054405204000053039865802BR5910NightKing6010Winterfell62280524invoice/573017417580544063046B79",
            "created":"2025-01-01T18:58:38.092412+00:00",
            "data":{
               "amount":400000,
               "due":"2026-05-12T17:59:26.000000+00:00",
               "fine":2.5,
               "interest":1.3
            },
            "displayDescription":"Dragon Travel Fare",
            "due":"2025-01-03T18:58:38.092412+00:00",
            "end":"2025-06-16T00:00:00.000000+00:00",
            "externalId":"my-unique-id-12345678",
            "id":"5632510516002816",
            "interval":"month",
            "name":"John Snow",
            "pullMode":"manual",
            "pullRetryLimit":3,
            "referenceCode":"contract-12345",
            "start":"2025-01-16T00:00:00.000000+00:00",
            "status":"active",
            "tags":[
                "order/123",
                "customer/456"
            ],
            "taxId":"012.345.678-90",
            "type":"paymentAndOrQrcode",
            "updated":"2025-01-01T18:58:38.092412+00:00"
         },
         "type":"confirmed"
      }
   }
}

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.

pix-subscription-push-notification

Python

import starkbank

subscriptions = starkbank.invoicepullsubscription.create([
    starkbank.InvoicePullSubscription(
        amount=0,
        amount_min_limit=5000,
        data={
            "account_number": "9123900000",
            "bank_code": "05097757",
            "branch_code": "1126",
            "tax_id": "20.018.183/0001-80"
        },
        display_description="Dragon Travel Fare",
        external_id="b7e6a2c2-8e2b-4c1a-9e2a-123456789abc",
        interval="month",
        name="John Snow",
        pull_mode="manual",
        pull_retry_limit=3,
        start="2025-09-14T00:00:00Z",
        end="2025-10-14T00:00:00Z",
        reference_code="contract-12345",
        tags=[],
        tax_id="012.345.678-90",
        type="push"
    ),
])

for subscription in subscriptions:
    print(subscription)

Javascript

const starkbank = require('starkbank');

(async() => {
    let subscriptions = await starkbank.invoicePullSubscription.create([
        {
        amount: 0,
        amountMinLimit: 5000,
        data: {
            accountNumber: '9123900000',
            bankCode: '05097757',
            branchCode: '1126',
            taxId: '20.018.183/0001-80'
        },
        displayDescription: 'Dragon Travel Fare',
        externalId: 'e0ef6c02-f58e-44cd-b04d-e914d4df9405',
        interval: 'month',
        name: 'John Snow',
        pullMode: 'manual',
        pullRetryLimit: 3,
        start: '2025-09-14',
        end: '2025-10-14',
        referenceCode: 'contract-12345',
        tags: [],
        taxId: '012.345.678-90',
        type: 'push'
        }
    ]);

    for (let subscription of subscriptions) {
        console.log(subscription);
    }
})();

PHP

$subscriptions = StarkBankInvoicePullSubscription::create([
    new InvoicePullSubscription([
        "amount" => 0,
        "amountMinLimit" => 5000,
        "data" => [
            "accountNumber" => "9123900000",
            "bankCode" => "05097757",
            "branchCode" => "1126",
            "taxId" => "20.018.183/0001-80"
        ],
        "displayDescription" => "Dragon Travel Fare",
        "due" => '2025-10-27',
        "end" => '2025-10-27',
        "externalId" => "php-1553222241",
        "interval" => "month",
        "name" => "John Snow",
        "pullMode" => "manual",
        "pullRetryLimit" => 3,
        "referenceCode" => "contract-12345",
        "start" => '2025-09-22',
        "tags" => [],
        "taxId" => "012.345.678-90",
        "type" => "push",
    ])

foreach ($subscriptions as $subscription) {
    print_r($subscription);
}

Java

import com.starkbank.*;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;

List subscriptions = new ArrayList<>();

HashMap classData = new HashMap<>();
classData.put("start", "2025-09-30");
classData.put("interval", "month");
classData.put("pullMode", "manual");
classData.put("pullRetryLimit", 3L);
classData.put("type", "push");
classData.put("amount", 0L);
classData.put("amountMinLimit", 5000L);
classData.put("displayDescription", "Dragon Travel Fare");
classData.put("externalId", "a119bc87-68ac-4558-8a54-22196beebf67");
classData.put("referenceCode", "contract-12345");
classData.put("end", "2025-10-30");
classData.put("name", "John Snow");
classData.put("taxId", "012.345.678-90");
classData.put("tags", new String[]{});

HashMap data = new HashMap<>();
data.put("accountNumber", "9123900000");
data.put("bankCode", "05097757");
data.put("branchCode", "1126");
data.put("taxId", "20.018.183/0001-80");

classData.put("data", data);

subscriptions.add(new InvoicePullSubscription(classData));

subscriptions = InvoicePullSubscription.create(subscriptions);

for (InvoicePullSubscription subscription : subscriptions) {
    System.out.println(subscription);
}

Ruby

Not yet available. Please contact us if you need this SDK.

Elixir

Not yet available. Please contact us if you need this SDK.

C#

using System;
using System.Collections.Generic;

List<StarkBank.InvoicePullSubscription> subscriptions = StarkBank.InvoicePullSubscription.Create(
    new List<StarkBank.InvoicePullSubscription> {
        new InvoicePullSubscription(
            amount: 1000000,
            amountMinLimit: 5000,
            data: new Dictionary<string, object> {
            {"accountNumber", "9123900000"},
            {"bankCode", "05097757"},
            {"branchCode", "1126"},
            {"taxId", "20.018.183/0001-80"}
            },
            displayDescription: "Dragon Travel Fare",
            externalID: "f4a4c70b-bf5a-400d-8eae-685128691645",
            interval: "month",
            name: "John Snow",
            pullMode: "manual",
            pullRetryLimit: 3,
            start: new DateTime(2025, 9, 14, 0, 0, 0, DateTimeKind.Utc),
            end: new DateTime(2025, 10, 14, 0, 0, 0, DateTimeKind.Utc),
            referenceCode: "contract-12345",
            tags: new List<string>(),
            taxID: "012.345.678-90",
            type: "push"
        )
    }
);

foreach (StarkBank.InvoicePullSubscription subscription in subscriptions)
{
    Console.WriteLine(subscription);
}

Go

package main

import (
    "fmt"
    "time"
    "github.com/starkbank/sdk-go/starkbank/invoicepullsubscription"
)

func main() {

    start := time.Date(2025, 11, 3, 0, 0, 0, 0, time.UTC)
    end := time.Date(2025, 12, 3, 0, 0, 0, 0, time.UTC)
	due := time.Date(2025, 11, 3, 0, 0, 0, 0, time.UTC)
    data := map[string]interface{}{
			"amount":   400000,
			"due":      &due,
			"fine":     2.5,
			"interest": 1.3,
	}

    invoicePullSubscription, err := invoicepullsubscription.Create(
        []invoicepullsubscription.InvoicePullSubscription{
            {
              Amount:            1000000,
              AmountMinLimit:    5000,
              Data:              data,
              DisplayDescription: "Dragon Travel Fare",
              ExternalId:        fmt.Sprintf("my_external_id_xwewe"),
              Interval:          "month",
              Name:              "John Snow",
              PullMode:          "manual",
              PullRetryLimit:    3,
              Start:             &start,
              End:               &end,
              ReferenceCode:     "contract-12345",
              Tags:              []string{},
              TaxId:             "012.345.678-90",
              Type:              "paymentAndOrQrcode",
            },
        }, nil)

    if err.Errors != nil {
        for _, e := range err.Errors {
            fmt.Printf("code: %s, message: %s", e.Code, e.Message)
        }
    }

    subscription := invoicePullSubscription[0]
    fmt.Printf("%+v", subscription)
}

Clojure

Not yet available. Please contact us if you need this SDK.

Curl

curl --location --request POST '{{baseUrl}}/v2/invoice-pull-subscription' 
--header 'Access-Id: {{accessId}}' 
--header 'Access-Time: {{accessTime}}' 
--header 'Access-Signature: {{accessSignature}}' 
--header 'Content-Type: application/json' 
--data-raw '{
    "subscriptions": [
        {
        "amount": 0,
        "amountMinLimit": 5000,
        "data": {
            "accountNumber": "9123900000",
            "bankCode": "05097757",
            "branchCode": "1126",
            "taxId": "20.018.183/0001-80"
        },
        "displayDescription": "Dragon Travel Fare",
        "externalId": "b7e6a2c2-8e2b-4c1a-9e2a-123456789abc",
        "interval": "month",
        "name": "John Snow",
        "pullMode": "manual",
        "pullRetryLimit": 3,
        "start": "2025-09-14",
        "end": "2025-10-14",
        "referenceCode": "contract-12345",
        "tags": [],
        "taxId": "012.345.678-90",
        "type": "push"
        }
    ]
}'
RESPONSE

Python

InvoicePullSubscription(
    amount=0,
    amount_min_limit=5000,
    bacen_id=RR2001818320250904xDUK7RgCRT4,
    created=2025-09-04 20:57:33.833777,
    data={'accountNumber': '9123900000', 'bankCode': '05097757', 'branchCode': '1126', 'taxId': '20.018.183/0001-80'},
    display_description=Dragon Travel Fare,
    due=2025-09-14 00:00:00,
    end=2025-10-14 00:00:00,
    external_id=b7e6a2c2-8e2b-4c1a-9e2a-123456789abc,
    id=5656565656565656,
    interval=month,
    name=John Snow,
    pull_mode=manual,
    pull_retry_limit=3,
    reference_code=contract-12345,
    start=2025-09-14 00:00:00,
    status=active,
    tags=[],
    tax_id=012.345.678-90,
    type=push,
    updated=2025-09-14 00:00:00
)

Javascript

InvoicePullSubscription {
  id: '4656724615102464',
  start: '2025-09-14T03:00:00+00:00',
  interval: 'month',
  pullMode: 'manual',
  pullRetryLimit: 3,
  type: 'push',
  amount: 0,
  amountMinLimit: 5000,
  displayDescription: 'Dragon Travel Fare',
  due: '2025-09-11T21:42:35.878330+00:00',
  externalId: 'e0ef6c02-f58e-44cd-b04d-e914d4df9405',
  referenceCode: 'contract-12345',
  end: '2025-10-14T03:00:00+00:00',
  data: {
    accountNumber: '9123900000',
    bankCode: '05097757',
    branchCode: '1126',
    taxId: '20.018.183/0001-80'
  },
  name: 'John Snow',
  taxId: '012.345.678-90',
  tags: [],
  status: 'created',
  bacenId: 'RR2001818320250909WDW2JAoiyB2',
  installmentId: null,
  created: '2025-09-09T21:42:36.419070+00:00',
  updated: '2025-09-09T21:42:36.419078+00:00',
  brcode: ''
}

PHP

StarkBankInvoicePullSubscription Object
(
    [id] => 6673352286535680
    [start] => DateTime Object
        (
            [date] => 2025-09-22 03:00:00.000000
            [timezone_type] => 1
            [timezone] => +00:00
        )

    [interval] => month
    [pullMode] => manual
    [pullRetryLimit] => 3
    [type] => push
    [amount] => 0
    [amountMinLimit] => 5000
    [displayDescription] => Dragon Travel Fare
    [due] => DateTime Object
        (
            [date] => 2025-10-28 02:59:59.999999
            [timezone_type] => 1
            [timezone] => +00:00
        )

    [externalId] => php-1553222241
    [referenceCode] => contract-12345
    [end] => DateTime Object
        (
            [date] => 2025-10-27 03:00:00.000000
            [timezone_type] => 1
            [timezone] => +00:00
        )

    [data] => Array
        (
            [accountNumber] => 9123900000
            [bankCode] => 05097757
            [branchCode] => 1126
            [taxId] => 20.018.183/0001-80
        )

    [name] => John Snow
    [taxId] => 012.345.678-90
    [tags] => Array
        (
        )

    [status] => created
    [bacenId] => RR39908427202509220UfSNmHYqfy
    [installmentId] => 
    [created] => DateTime Object
        (
            [date] => 2025-09-22 23:44:35.599677
            [timezone_type] => 1
            [timezone] => +00:00
        )

    [updated] => DateTime Object
        (
            [date] => 2025-09-22 23:44:35.599685
            [timezone_type] => 1
            [timezone] => +00:00
        )

    [brcode] => 
)

Java

InvoicePullSubscription({
  "start": "2025-09-30T03:00:00+00:00",
  "interval": "month",
  "pullMode": "manual",
  "pullRetryLimit": 3,
  "type": "push",
  "amount": 0,
  "amountMinLimit": 5000,
  "displayDescription": "Dragon Travel Fare",
  "due": "2025-09-27T18:41:26.789072+00:00",
  "externalId": "a119bc87-68ac-4558-8a54-22196beebf67",
  "referenceCode": "contract-12345",
  "end": "2025-10-30T03:00:00+00:00",
  "data": {
    "accountNumber": "9123900000",
    "bankCode": "05097757",
    "branchCode": "1126",
    "taxId": "20.018.183/0001-80"
  },
  "name": "John Snow",
  "taxId": "012.345.678-90",
  "tags": [],
  "status": "created",
  "bacenId": "RR2001818320250925BxZi3SKFhs6",
  "brcode": "",
  "created": "2025-09-25T18:41:27.511033+00:00",
  "updated": "2025-09-25T18:41:27.511041+00:00",
  "id": "6673482343514112"
})

Ruby

Not yet available. Please contact us if you need this SDK.

Elixir

Not yet available. Please contact us if you need this SDK.

C#

InvoicePullSubscription(
  Start: 9/14/2025 12:00:00AM,
  Interval: month,
  PullMode: manual,
  PullRetryLimit: 3,
  Type: push,
  Amount: 1000000,
  AmountMinLimit: 5000,
  DisplayDescription: Dragon Travel Fare,
  Due: 9/11/2025 6:58:02PM,
  ExternalID: f4a4c70b-bf5a-400d-8eae-685128691645,
  ReferenceCode: contract-12345,
  End: 10/14/2025 12:00:00AM,
  Data: System.Collections.Generic.Dictionary`2[System.String,System.Object],
  Name: John Snow,
  TaxID: 012.345.678-90,
  Tags: {  },
  Status: created,
  BacenID: RR2001818320250909fxSoQw3VO04,
  Brcode: ,
  Created: 9/9/2025 6:58:03PM,
  Updated: 9/9/2025 6:58:03PM,
  ID: 4582433332658176
)

Go

{
    Id:6061255534051328
    Start:2025-11-03 03:00:00 +0000 +0000
    Interval:month
    PullMode:manual
    PullRetryLimit:3
    Type:paymentAndOrQrcode
    Amount:1000000
    AmountMinLimit:5000
    DisplayDescription:Dragon Travel Fare
    Due:2025-11-01 20:06:30.735371 +0000 +0000
    ExternalId:my_external_id_
    ReferenceCode:contract-12345
    End:2025-12-03 03:00:00 +0000 +0000
    Data:map[accountNumber: amount:400000 bankCode: branchCode: due:2025-11-03 00:00:00 +0000 UTC fine:2.5 interest:1.3 invoiceId:5474875019886592 taxId:]
    Name:John Snow
    TaxId:012.345.678-90
    Tags:[]
    Status:created
    BacenId:RR2001818320251030o9XZjuDVpfU Brcode:00020101021226940014br.gov.bcb.pix2572brcode-h.sandbox.starkinfra.com/v2/cobv/0aca55b5d74c4e4d9ca63ff5b9af7deb5204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***80930014br.gov.bcb.pix2571brcode-h.sandbox.starkinfra.com/v2/rec/0aca55b5d74c4e4d9ca63ff5b9af7deb6304CA86
    Created:2025-10-30 20:06:31.164797 +0000 +0000
    Updated:2025-10-30 20:06:31.164804 +0000 +0000
}

Clojure

Not yet available. Please contact us if you need this SDK.

Curl

{
    "message": "Subscriptions successfully created",
    "subscriptions": [
        {
            "amount": 0,
            "amountMinLimit": 5000,
            "bacenId": "RR20018183202509096amQtgYdMTf",
            "brcode": "",
            "created": "2025-09-09T21:34:55.854022+00:00",
            "updated": "2025-09-09T21:34:55.854028+00:00",
            "displayDescription": "Dragon Travel Fare",
            "referenceCode": "contract-12345",
            "due": "2025-09-11T21:34:55.157021+00:00",
            "externalId": "b7e6a2c2-8e2b-4c1a-9e2a-123456789abc",
            "id": "6633844090339328",
            "start": "2025-09-14T03:00:00+00:00",
            "end": "2025-10-14T03:00:00+00:00",
            "interval": "month",
            "data": {
                "accountNumber": "9123900000",
                "bankCode": "05097757",
                "branchCode": "1126",
                "taxId": "20.018.183/0001-80"
            },
            "pullMode": "manual",
            "pullRetryLimit": 3,
            "name": "John Snow",
            "taxId": "012.345.678-90",
            "status": "created",
            "tags": [],
            "type": "push"
        }
    ]
}

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.

RESPONSE

Python

{
   "event":{
      "id":"5054340314169344",
      "subscription":"invoice-subscription",
      "created":"2025-07-29T18:00:22.593217+00:00",
      "workspaceId":"6275127679385600",
      "isDelivered":true,
      "log":{
         "created":"2025-01-01T18:58:40.092412+00:00",
         "errors":[],
         "id":"5506769686102016",
         "subscriptions": {
            "amount": 0,
            "amountMinLimit": 5000,
            "bacenId": "RR20018183202509096amQtgYdMTf",
            "brcode": "",
            "created": "2025-09-09T21:34:55.854022+00:00",
            "updated": "2025-09-09T21:34:55.854028+00:00",
            "displayDescription": "Dragon Travel Fare",
            "referenceCode": "contract-12345",
            "due": "2025-09-11T21:34:55.157021+00:00",
            "externalId": "b7e6a2c2-8e2b-4c1a-9e2a-123456789abc",
            "id": "6633844090339328",
            "start": "2025-09-14T03:00:00+00:00",
            "end": "2025-10-14T03:00:00+00:00",
            "interval": "month",
            "data": {
                "accountNumber": "9123900000",
                "bankCode": "05097757",
                "branchCode": "1126",
                "taxId": "20.018.183/0001-80"
            },
            "pullMode": "manual",
            "pullRetryLimit": 3,
            "name": "John Snow",
            "taxId": "012.345.678-90",
            "status": "created",
            "tags": [
                "order/123",
                "customer/456"
            ],
            "type": "push"
         },
         "type":"confirmed"
      }
   }
}

Javascript

{
   "event":{
      "id":"5054340314169344",
      "subscription":"invoice-subscription",
      "created":"2025-07-29T18:00:22.593217+00:00",
      "workspaceId":"6275127679385600",
      "isDelivered":true,
      "log":{
         "created":"2025-01-01T18:58:40.092412+00:00",
         "errors":[],
         "id":"5506769686102016",
         "subscriptions": {
            "amount": 0,
            "amountMinLimit": 5000,
            "bacenId": "RR20018183202509096amQtgYdMTf",
            "brcode": "",
            "created": "2025-09-09T21:34:55.854022+00:00",
            "updated": "2025-09-09T21:34:55.854028+00:00",
            "displayDescription": "Dragon Travel Fare",
            "referenceCode": "contract-12345",
            "due": "2025-09-11T21:34:55.157021+00:00",
            "externalId": "b7e6a2c2-8e2b-4c1a-9e2a-123456789abc",
            "id": "6633844090339328",
            "start": "2025-09-14T03:00:00+00:00",
            "end": "2025-10-14T03:00:00+00:00",
            "interval": "month",
            "data": {
                "accountNumber": "9123900000",
                "bankCode": "05097757",
                "branchCode": "1126",
                "taxId": "20.018.183/0001-80"
            },
            "pullMode": "manual",
            "pullRetryLimit": 3,
            "name": "John Snow",
            "taxId": "012.345.678-90",
            "status": "created",
            "tags": [
                "order/123",
                "customer/456"
            ],
            "type": "push"
         },
         "type":"confirmed"
      }
   }
}

PHP

{
   "event":{
      "id":"5054340314169344",
      "subscription":"invoice-subscription",
      "created":"2025-07-29T18:00:22.593217+00:00",
      "workspaceId":"6275127679385600",
      "isDelivered":true,
      "log":{
         "created":"2025-01-01T18:58:40.092412+00:00",
         "errors":[],
         "id":"5506769686102016",
         "subscriptions": {
            "amount": 0,
            "amountMinLimit": 5000,
            "bacenId": "RR20018183202509096amQtgYdMTf",
            "brcode": "",
            "created": "2025-09-09T21:34:55.854022+00:00",
            "updated": "2025-09-09T21:34:55.854028+00:00",
            "displayDescription": "Dragon Travel Fare",
            "referenceCode": "contract-12345",
            "due": "2025-09-11T21:34:55.157021+00:00",
            "externalId": "b7e6a2c2-8e2b-4c1a-9e2a-123456789abc",
            "id": "6633844090339328",
            "start": "2025-09-14T03:00:00+00:00",
            "end": "2025-10-14T03:00:00+00:00",
            "interval": "month",
            "data": {
                "accountNumber": "9123900000",
                "bankCode": "05097757",
                "branchCode": "1126",
                "taxId": "20.018.183/0001-80"
            },
            "pullMode": "manual",
            "pullRetryLimit": 3,
            "name": "John Snow",
            "taxId": "012.345.678-90",
            "status": "created",
            "tags": [
                "order/123",
                "customer/456"
            ],
            "type": "push"
         },
         "type":"confirmed"
      }
   }
}

Java

{
   "event":{
      "id":"5054340314169344",
      "subscription":"invoice-subscription",
      "created":"2025-07-29T18:00:22.593217+00:00",
      "workspaceId":"6275127679385600",
      "isDelivered":true,
      "log":{
         "created":"2025-01-01T18:58:40.092412+00:00",
         "errors":[],
         "id":"5506769686102016",
         "subscriptions": {
            "amount": 0,
            "amountMinLimit": 5000,
            "bacenId": "RR20018183202509096amQtgYdMTf",
            "brcode": "",
            "created": "2025-09-09T21:34:55.854022+00:00",
            "updated": "2025-09-09T21:34:55.854028+00:00",
            "displayDescription": "Dragon Travel Fare",
            "referenceCode": "contract-12345",
            "due": "2025-09-11T21:34:55.157021+00:00",
            "externalId": "b7e6a2c2-8e2b-4c1a-9e2a-123456789abc",
            "id": "6633844090339328",
            "start": "2025-09-14T03:00:00+00:00",
            "end": "2025-10-14T03:00:00+00:00",
            "interval": "month",
            "data": {
                "accountNumber": "9123900000",
                "bankCode": "05097757",
                "branchCode": "1126",
                "taxId": "20.018.183/0001-80"
            },
            "pullMode": "manual",
            "pullRetryLimit": 3,
            "name": "John Snow",
            "taxId": "012.345.678-90",
            "status": "created",
            "tags": [
                "order/123",
                "customer/456"
            ],
            "type": "push"
         },
         "type":"confirmed"
      }
   }
}

Ruby

{
   "event":{
      "id":"5054340314169344",
      "subscription":"invoice-subscription",
      "created":"2025-07-29T18:00:22.593217+00:00",
      "workspaceId":"6275127679385600",
      "isDelivered":true,
      "log":{
         "created":"2025-01-01T18:58:40.092412+00:00",
         "errors":[],
         "id":"5506769686102016",
         "subscriptions": {
            "amount": 0,
            "amountMinLimit": 5000,
            "bacenId": "RR20018183202509096amQtgYdMTf",
            "brcode": "",
            "created": "2025-09-09T21:34:55.854022+00:00",
            "updated": "2025-09-09T21:34:55.854028+00:00",
            "displayDescription": "Dragon Travel Fare",
            "referenceCode": "contract-12345",
            "due": "2025-09-11T21:34:55.157021+00:00",
            "externalId": "b7e6a2c2-8e2b-4c1a-9e2a-123456789abc",
            "id": "6633844090339328",
            "start": "2025-09-14T03:00:00+00:00",
            "end": "2025-10-14T03:00:00+00:00",
            "interval": "month",
            "data": {
                "accountNumber": "9123900000",
                "bankCode": "05097757",
                "branchCode": "1126",
                "taxId": "20.018.183/0001-80"
            },
            "pullMode": "manual",
            "pullRetryLimit": 3,
            "name": "John Snow",
            "taxId": "012.345.678-90",
            "status": "created",
            "tags": [
                "order/123",
                "customer/456"
            ],
            "type": "push"
         },
         "type":"confirmed"
      }
   }
}

Elixir

{
   "event":{
      "id":"5054340314169344",
      "subscription":"invoice-subscription",
      "created":"2025-07-29T18:00:22.593217+00:00",
      "workspaceId":"6275127679385600",
      "isDelivered":true,
      "log":{
         "created":"2025-01-01T18:58:40.092412+00:00",
         "errors":[],
         "id":"5506769686102016",
         "subscriptions": {
            "amount": 0,
            "amountMinLimit": 5000,
            "bacenId": "RR20018183202509096amQtgYdMTf",
            "brcode": "",
            "created": "2025-09-09T21:34:55.854022+00:00",
            "updated": "2025-09-09T21:34:55.854028+00:00",
            "displayDescription": "Dragon Travel Fare",
            "referenceCode": "contract-12345",
            "due": "2025-09-11T21:34:55.157021+00:00",
            "externalId": "b7e6a2c2-8e2b-4c1a-9e2a-123456789abc",
            "id": "6633844090339328",
            "start": "2025-09-14T03:00:00+00:00",
            "end": "2025-10-14T03:00:00+00:00",
            "interval": "month",
            "data": {
                "accountNumber": "9123900000",
                "bankCode": "05097757",
                "branchCode": "1126",
                "taxId": "20.018.183/0001-80"
            },
            "pullMode": "manual",
            "pullRetryLimit": 3,
            "name": "John Snow",
            "taxId": "012.345.678-90",
            "status": "created",
            "tags": [
                "order/123",
                "customer/456"
            ],
            "type": "push"
         },
         "type":"confirmed"
      }
   }
}

C#

{
   "event":{
      "id":"5054340314169344",
      "subscription":"invoice-subscription",
      "created":"2025-07-29T18:00:22.593217+00:00",
      "workspaceId":"6275127679385600",
      "isDelivered":true,
      "log":{
         "created":"2025-01-01T18:58:40.092412+00:00",
         "errors":[],
         "id":"5506769686102016",
         "subscriptions": {
            "amount": 0,
            "amountMinLimit": 5000,
            "bacenId": "RR20018183202509096amQtgYdMTf",
            "brcode": "",
            "created": "2025-09-09T21:34:55.854022+00:00",
            "updated": "2025-09-09T21:34:55.854028+00:00",
            "displayDescription": "Dragon Travel Fare",
            "referenceCode": "contract-12345",
            "due": "2025-09-11T21:34:55.157021+00:00",
            "externalId": "b7e6a2c2-8e2b-4c1a-9e2a-123456789abc",
            "id": "6633844090339328",
            "start": "2025-09-14T03:00:00+00:00",
            "end": "2025-10-14T03:00:00+00:00",
            "interval": "month",
            "data": {
                "accountNumber": "9123900000",
                "bankCode": "05097757",
                "branchCode": "1126",
                "taxId": "20.018.183/0001-80"
            },
            "pullMode": "manual",
            "pullRetryLimit": 3,
            "name": "John Snow",
            "taxId": "012.345.678-90",
            "status": "created",
            "tags": [
                "order/123",
                "customer/456"
            ],
            "type": "push"
         },
         "type":"confirmed"
      }
   }
}

Go

{
   "event":{
      "id":"5054340314169344",
      "subscription":"invoice-subscription",
      "created":"2025-07-29T18:00:22.593217+00:00",
      "workspaceId":"6275127679385600",
      "isDelivered":true,
      "log":{
         "created":"2025-01-01T18:58:40.092412+00:00",
         "errors":[],
         "id":"5506769686102016",
         "subscriptions": {
            "amount": 0,
            "amountMinLimit": 5000,
            "bacenId": "RR20018183202509096amQtgYdMTf",
            "brcode": "",
            "created": "2025-09-09T21:34:55.854022+00:00",
            "updated": "2025-09-09T21:34:55.854028+00:00",
            "displayDescription": "Dragon Travel Fare",
            "referenceCode": "contract-12345",
            "due": "2025-09-11T21:34:55.157021+00:00",
            "externalId": "b7e6a2c2-8e2b-4c1a-9e2a-123456789abc",
            "id": "6633844090339328",
            "start": "2025-09-14T03:00:00+00:00",
            "end": "2025-10-14T03:00:00+00:00",
            "interval": "month",
            "data": {
                "accountNumber": "9123900000",
                "bankCode": "05097757",
                "branchCode": "1126",
                "taxId": "20.018.183/0001-80"
            },
            "pullMode": "manual",
            "pullRetryLimit": 3,
            "name": "John Snow",
            "taxId": "012.345.678-90",
            "status": "created",
            "tags": [
                "order/123",
                "customer/456"
            ],
            "type": "push"
         },
         "type":"confirmed"
      }
   }
}

Clojure

{
   "event":{
      "id":"5054340314169344",
      "subscription":"invoice-subscription",
      "created":"2025-07-29T18:00:22.593217+00:00",
      "workspaceId":"6275127679385600",
      "isDelivered":true,
      "log":{
         "created":"2025-01-01T18:58:40.092412+00:00",
         "errors":[],
         "id":"5506769686102016",
         "subscriptions": {
            "amount": 0,
            "amountMinLimit": 5000,
            "bacenId": "RR20018183202509096amQtgYdMTf",
            "brcode": "",
            "created": "2025-09-09T21:34:55.854022+00:00",
            "updated": "2025-09-09T21:34:55.854028+00:00",
            "displayDescription": "Dragon Travel Fare",
            "referenceCode": "contract-12345",
            "due": "2025-09-11T21:34:55.157021+00:00",
            "externalId": "b7e6a2c2-8e2b-4c1a-9e2a-123456789abc",
            "id": "6633844090339328",
            "start": "2025-09-14T03:00:00+00:00",
            "end": "2025-10-14T03:00:00+00:00",
            "interval": "month",
            "data": {
                "accountNumber": "9123900000",
                "bankCode": "05097757",
                "branchCode": "1126",
                "taxId": "20.018.183/0001-80"
            },
            "pullMode": "manual",
            "pullRetryLimit": 3,
            "name": "John Snow",
            "taxId": "012.345.678-90",
            "status": "created",
            "tags": [
                "order/123",
                "customer/456"
            ],
            "type": "push"
         },
         "type":"confirmed"
      }
   }
}

Curl

{
   "event":{
      "id":"5054340314169344",
      "subscription":"invoice-subscription",
      "created":"2025-07-29T18:00:22.593217+00:00",
      "workspaceId":"6275127679385600",
      "isDelivered":true,
      "log":{
         "created":"2025-01-01T18:58:40.092412+00:00",
         "errors":[],
         "id":"5506769686102016",
         "subscriptions": {
            "amount": 0,
            "amountMinLimit": 5000,
            "bacenId": "RR20018183202509096amQtgYdMTf",
            "brcode": "",
            "created": "2025-09-09T21:34:55.854022+00:00",
            "updated": "2025-09-09T21:34:55.854028+00:00",
            "displayDescription": "Dragon Travel Fare",
            "referenceCode": "contract-12345",
            "due": "2025-09-11T21:34:55.157021+00:00",
            "externalId": "b7e6a2c2-8e2b-4c1a-9e2a-123456789abc",
            "id": "6633844090339328",
            "start": "2025-09-14T03:00:00+00:00",
            "end": "2025-10-14T03:00:00+00:00",
            "interval": "month",
            "data": {
                "accountNumber": "9123900000",
                "bankCode": "05097757",
                "branchCode": "1126",
                "taxId": "20.018.183/0001-80"
            },
            "pullMode": "manual",
            "pullRetryLimit": 3,
            "name": "John Snow",
            "taxId": "012.345.678-90",
            "status": "created",
            "tags": [
                "order/123",
                "customer/456"
            ],
            "type": "push"
         },
         "type":"confirmed"
      }
   }
}

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.

ReasonDescription
accountClosedThe payer account is closed.
invalidSenderAccountNumberThe payer account number is not valid or was closed.
receiverOrganizationClosedThe receiver organization was closed.
senderDeceasedThe payer user passed away.
subscriptionRequestFailedThe payer bank had an internal error to accept the subscription.
fraudThe payer bank identified a fraud.
subscriptionRequestNotRespondedThe subscription was not answered by the payer bank.
subscriptionRequestAlreadyRespondedThe subscription request was already responded through another journey.
receiverUserRequestedThe cancelation was requested by the Stark Bank client.
senderUserRequestedThe payer requested the cancelation.
subscriptionRequestNotRespondedThe subscription request was not responded by the payer bank.
notRespondedBySenderThe subscription request expired.
userRejectedThe user denied the subscription (first journey).
duplicatedSubscriptionThe user already confirmed the subscription previously.
paymentNotFoundThe payment was not found to authorize the subscription (third journey).

Python

import starkbank

subscriptions = starkbank.invoicepullsubscription.cancel("4656724615102464")

print(subscription)

Javascript

const starkbank = require('starkbank');

(async() => {
    let subscription = await starkbank.invoicePullSubscription.cancel("4710331041447936");

    console.log(subscription);
})();

PHP

$subscription = StarkBankInvoicePullSubscription::cancel("4745120922468352");

print_r($subscription);

Java

import com.starkbank.*;

InvoicePullSubscription subscription = InvoicePullSubscription.cancel("4891450525351936");

System.out.println(subscription);

Ruby

Not yet available. Please contact us if you need this SDK.

Elixir

Not yet available. Please contact us if you need this SDK.

C#

using System;

InvoicePullSubscription subscription = InvoicePullSubscription.Cancel("5951120425877504");

Console.WriteLine(subscription);

Go

package main

import (
    "fmt"
    "github.com/starkbank/sdk-go/starkbank/invoicepullsubscription"
)

func main() {

    subscription, err := invoicepullsubscription.Cancel("5920644369743872", nil)
    if err.Errors != nil {
        for _, e := range err.Errors {
            fmt.Printf("code: %s, message: %s", e.Code, e.Message)
        }
    }
    fmt.Printf("%+v", subscription)
}

Clojure

Not yet available. Please contact us if you need this SDK.

Curl

curl --location --request DELETE '{{baseUrl}}/v2/invoice-pull-subscription/4582433332658176' 
--header 'Access-Id: {{accessId}}' 
--header 'Access-Time: {{accessTime}}' 
--header 'Access-Signature: {{accessSignature}}' 
--header 'Content-Type: application/json'
RESPONSE

Python

InvoicePullSubscription(
        amount=0,
        amount_min_limit=5000,
        bacen_id=RR2001818320250909WDW2JAoiyB2,
        created=2025-09-09 21:42:36.419070,
        data={'accountNumber': '9123900000', 'bankCode': '05097757', 'branchCode': '1126', 'taxId': '20.018.183/0001-80'},
        display_description=Dragon Travel Fare,
        due=2025-09-11 21:42:35.878330,
        end=2025-10-14 03:00:00,
        external_id=e0ef6c02-f58e-44cd-b04d-e914d4df9405,
        id=4656724615102464,
        interval=month,
        name=John Snow,
        pull_mode=manual,
        pull_retry_limit=3,
        reference_code=contract-12345,
        start=2025-09-14 03:00:00,
        status=active,
        tags=[],
        tax_id=012.345.678-90,
        type=push,
        updated=2025-09-09 21:42:43.694648
)

Javascript

InvoicePullSubscription {
  id: '4710331041447936',
  start: '2025-09-14T03:00:00+00:00',
  interval: 'month',
  pullMode: 'manual',
  pullRetryLimit: 3,
  type: 'push',
  amount: 1000000,
  amountMinLimit: 5000,
  displayDescription: 'Dragon Travel Fare',
  due: '2025-09-11T21:45:59.054486+00:00',
  externalId: '878abdf9-738f-4c54-a3a2-b6556939416f',
  referenceCode: 'contract-12345',
  end: '2025-10-14T03:00:00+00:00',
  data: {
    accountNumber: '9123900000',
    bankCode: '05097757',
    branchCode: '1126',
    taxId: '20.018.183/0001-80'
  },
  name: 'John Snow',
  taxId: '012.345.678-90',
  tags: [],
  status: 'active',
  bacenId: 'RR2001818320250909mHJ5ztngywk',
  installmentId: null,
  created: '2025-09-09T21:45:59.496556+00:00',
  updated: '2025-09-09T21:46:07.020712+00:00',
  brcode: ''
}

PHP

StarkBankInvoicePullSubscription Object
(
    [id] => 4745120922468352
    [start] => DateTime Object
        (
            [date] => 2025-09-22 03:00:00.000000
            [timezone_type] => 1
            [timezone] => +00:00
        )

    [interval] => month
    [pullMode] => manual
    [pullRetryLimit] => 3
    [type] => paymentAndOrQrcode
    [amount] => 0
    [amountMinLimit] => 5000
    [displayDescription] => Dragon Travel Fare
    [due] => DateTime Object
        (
            [date] => 2025-10-28 02:59:59.999999
            [timezone_type] => 1
            [timezone] => +00:00
        )

    [externalId] => php-321899546
    [referenceCode] => contract-12345
    [end] => DateTime Object
        (
            [date] => 2025-10-27 03:00:00.000000
            [timezone_type] => 1
            [timezone] => +00:00
        )

    [data] => Array
        (
            [accountNumber] => 
            [bankCode] => 
            [branchCode] => 
            [taxId] => 
            [invoiceId] => 5454444799983616
        )

    [name] => John Snow
    [taxId] => 012.345.678-90
    [tags] => Array
        (
        )

    [status] => created
    [bacenId] => RR3990842720250922sE0pvKkcjwQ
    [installmentId] => 
    [created] => DateTime Object
        (
            [date] => 2025-09-22 23:55:59.387197
            [timezone_type] => 1
            [timezone] => +00:00
        )

    [updated] => DateTime Object
        (
            [date] => 2025-09-22 23:56:00.743753
            [timezone_type] => 1
            [timezone] => +00:00
        )

    [brcode] => 00020101021226940014br.gov.bcb.pix2572brcode-h.sandbox.starkinfra.com/v2/cobv/de7659408ca446ae8bd1825b247c2ab05204000053039865802BR5925Stark Sociedade de Credit6009Sao Paulo62070503***80930014br.gov.bcb.pix2571brcode-h.sandbox.starkinfra.com/v2/rec/de7659408ca446ae8bd1825b247c2ab06304F3FD
)

Java

InvoicePullSubscription({
  "start": "2025-09-30T03:00:00+00:00",
  "interval": "month",
  "pullMode": "manual",
  "pullRetryLimit": 3,
  "type": "qrcodeAndPayment",
  "amount": 0,
  "amountMinLimit": 5000,
  "displayDescription": "Dragon Travel Fare",
  "due": "2025-09-27T19:16:43.425562+00:00",
  "externalId": "c3c1b1cf-d7ef-4f32-88fa-caa3a7741d11",
  "referenceCode": "contract-12345",
  "end": "2025-10-30T03:00:00+00:00",
  "data": {
    "accountNumber": "9935081231275232",
    "bankCode": "01609345",
    "branchCode": "8246",
    "taxId": "830.079.880-39",
    "invoiceId": "6533210687143936"
  },
  "name": "John Snow",
  "taxId": "012.345.678-90",
  "tags": [],
  "status": "active",
  "bacenId": "RR200181832025092503I3Q63WR3y",
  "brcode": "00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/48d155b0d0e54318bcb236ff8bbf4b8e5204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***80930014br.gov.bcb.pix2571brcode-h.sandbox.starkinfra.com/v2/rec/48d155b0d0e54318bcb236ff8bbf4b8e6304A469",
  "created": "2025-09-25T19:16:44.314460+00:00",
  "updated": "2025-09-25T19:25:12.404204+00:00",
  "id": "4891450525351936"
})

Ruby

Not yet available. Please contact us if you need this SDK.

Elixir

Not yet available. Please contact us if you need this SDK.

C#

InvoicePullSubscription(
  Start: 9/14/2025 12:00:00AM,
  Interval: month,
  PullMode: manual,
  PullRetryLimit: 3,
  Type: push,
  Amount: 1000000,
  AmountMinLimit: 5000,
  DisplayDescription: Dragon Travel Fare,
  Due: 9/11/2025 6:55:41PM,
  ExternalID: f4a4c70b-bf5a-400d-8eae-685128691645x,
  ReferenceCode: contract-12345,
  End: 10/14/2025 12:00:00AM,
  Data: System.Collections.Generic.Dictionary`2[System.String,System.Object],
  Name: John Snow,
  TaxID: 012.345.678-90,
  Tags: {  },
  Status: active,
  BacenID: RR2001818320250909bdvoEjRhCJ6,
  Brcode: ,
  Created: 9/9/2025 6:55:42PM,
  Updated: 9/9/2025 6:55:51PM,
  ID: 5951120425877504
)

Go

{
    Id:5920644369743872
    Start:2025-11-03 03:00:00 +0000 +0000
    Interval:month
    PullMode:manual
    PullRetryLimit:3
    Type:push
    Amount:1000000
    AmountMinLimit:5000
    DisplayDescription:Dragon Travel Fare
    Due:2025-10-31 18:40:22.174967 +0000 +0000
    ExternalId:my_external_id
    ReferenceCode:contract-12345
    End:2025-12-03 03:00:00 +0000 +0000
    Data:map[accountNumber:9123900000 bankCode:05097757 branchCode:1126 taxId:20.018.183/0001-80]
    Name:John Snow
    TaxId:012.345.678-90
    Tags:[]
    Status:active
    BacenId:RR2001818320251029Lh5Z1T6zApm
    Brcode:
    Created:2025-10-29 18:40:22.898234 +0000 +0000
    Updated:2025-10-29 18:40:32.820757 +0000 +0000
}

Clojure

Not yet available. Please contact us if you need this SDK.

Curl

{
    "message": "Subscription cancellation successfully requested",
    "subscription": {
        "amount": 1000000,
        "amountMinLimit": 5000,
        "bacenId": "RR2001818320250909fxSoQw3VO04",
        "brcode": "",
        "created": "2025-09-09T21:58:03.557191+00:00",
        "updated": "2025-09-09T21:58:11.518639+00:00",
        "displayDescription": "Dragon Travel Fare",
        "referenceCode": "contract-12345",
        "due": "2025-09-11T21:58:02.951121+00:00",
        "externalId": "f4a4c70b-bf5a-400d-8eae-685128691645z",
        "id": "4582433332658176",
        "start": "2025-09-14T03:00:00+00:00",
        "end": "2025-10-14T03:00:00+00:00",
        "interval": "month",
        "data": {
            "accountNumber": "9123900000",
            "bankCode": "05097757",
            "branchCode": "1126",
            "taxId": "20.018.183/0001-80"
        },
        "pullMode": "manual",
        "pullRetryLimit": 3,
        "name": "John Snow",
        "taxId": "012.345.678-90",
        "status": "active",
        "tags": [],
        "type": "push"
    }
}

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 Status

Invoice Pull Requests will have the following life cycle:

invoice-pull-request-status

StatusDescription
CreatedThe Invoice Pull Request was created in Stark Bank.
PendingThe Invoice Pull Request was sent by Stark Bank.
ScheduledThe Invoice Pull Request created the payment schedule in the payer's bank.
SuccessThe Invoice Pull Request created a successful settlement.
CanceledThe Invoice Pull Request was canceled.
FailedThe 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:

invoice-pull-request-log

Log typeStatusDescription
CreatedCreatedThe Invoice Pull Request was created in Stark Bank.
PendingPendingThe Invoice Pull Request was sent by Stark Bank.
ScheduledScheduledThe Invoice Pull Request created the payment schedule in the payer's bank.
SuccessSuccessThe Invoice Pull Request created a successful settlement.
CancellingScheduledThe Invoice Pull Request is in the process of cancellation.
CanceledCanceledThe Invoice Pull Request was canceled.
FailedFailedThe Invoice Pull Request was unsuccessful.

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

The Invoice Pull Request Object

Attributes

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

Creating Invoice Pull Requests

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

invoice-pull-request

Python

import starkbank

requests = starkbank.invoicepullrequest.create([
    starkbank.InvoicePullRequest(
        attempt_type="retry",
        due="2025-09-14",
        invoice_id="6649956664344576",
        subscription_id="4776669403414528",
        tags=[]
    )
])

for request in requests:
    print(request)

Javascript

const starkbank = require('starkbank');

(async() => {
    let requests = await starkbank.invoicePullRequest.create([{
        attemptType: 'default',
        due: '2025-09-14',
        invoiceId: '6649956664344576',
        subscriptionId: '4776669403414528',
        tags: []
    }]);

    for (let request of requests) {
        console.log(request);
    }
})();

PHP

$requests = InvoicePullRequest::create([new InvoicePullRequest([
    "attemptType" => "default",
    "due" => "2025-09-24",
    "invoiceId" => "4972480749895680",
    "subscriptionId" => "4799968485310464",
    "tags" => []
])]);

foreach ($requests as $request) {
    print_r($request);
}

Java

import com.starkbank.*;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;

List requests = new ArrayList<>();

HashMap data = new HashMap<>();
data.put("attemptType", "default");
data.put("due", "2025-09-30");
data.put("invoiceId", "6028180624244736");
data.put("subscriptionId", "6673482343514112");
data.put("tags", new String[]{});

requests.add(new InvoicePullRequest(data));

requests = InvoicePullRequest.create(requests);

for (InvoicePullRequest request : requests) {
    System.out.println(request);
}

Ruby

Not yet available. Please contact us if you need this SDK.

Elixir

Not yet available. Please contact us if you need this SDK.

C#

using System;
using System.Collections.Generic;

List<InvoicePullRequest> requests = InvoicePullRequest.Create(new List<InvoicePullRequest> { new InvoicePullRequest(
    attemptType: "default",
    due: new DateTime(2025, 9, 14, 0, 0, 0, DateTimeKind.Utc),
    invoiceId: "6649956664344576",
    subscriptionId: "4656724615102464",
    tags: new List<string> { }
) });

foreach (StarkBank.InvoicePullRequest request in requests)
{
    Console.WriteLine(request);
}

Go

package main

import (
    "fmt"
    "time"
    "github.com/starkbank/sdk-go/starkbank/invoicepullrequest"
)

func main() {

  due := time.Date(2025, 11, 8, 0, 0, 0, 0, time.UTC)

	invoicePullRequest, err := invoicepullrequest.Create(
      []invoicepullrequest.InvoicePullRequest{
      {
          AttemptType:        "default",
          DisplayDescription: "Your description",
          Due:                &due,
          InvoiceId:          "5093778276745216",
          SubscriptionId:     "6136166097092608",
          Tags:               nil,
			},
          }, nil)


	if err.Errors != nil {
      for _, e := range err.Errors {
          t.Errorf("code: %s, message: %s", e.Code, e.Message)
      }
	}
	request := invoicePullRequest[0]
	fmt.Printf("%+v
", request)
}

Clojure

Not yet available. Please contact us if you need this SDK.

Curl

curl --location --request POST '{{baseUrl}}/v2/invoice-pull-request' 
--header 'Access-Id: {{accessId}}' 
--header 'Access-Time: {{accessTime}}' 
--header 'Access-Signature: {{accessSignature}}' 
--header 'Content-Type: application/json' 
--data-raw '{
  "requests": [
    {
      "attemptType": "retry",
      "due": "2025-09-14",
      "invoiceId": "6649956664344576",
      "subscriptionId": "4776669403414528",
      "tags": []
    }
  ]
}'
RESPONSE

Python

InvoicePullRequest(
    attempt_type=retry,
    created=2025-09-10 18:21:46.579211,
    display_description=,
    due=2025-09-14 03:00:00,
    external_id=c3cb7f72c8d94069adbc52a3b65515a4,
    id=5649587104645120,
    installment_id=5187902950604800,
    invoice_id=6649956664344576,
    status=created,
    subscription_id=4776669403414528,
    tags=[],
    updated=2025-09-10 18:21:46.579216
)

Javascript

  InvoicePullRequest {
    id: '6604482620162048',
    subscriptionId: '4776669403414528',
    invoiceId: '6649956664344576',
    due: '2025-09-14T03:00:00+00:00',
    attemptType: 'default',
    tags: [],
    externalId: '33ae4ce29d4c461db23dfad8e7aebd7a',
    displayDescription: '',
    status: 'created',
    installmentId: '5187902950604800',
    created: '2025-09-10T18:10:55.772558+00:00',
    updated: '2025-09-10T18:10:55.772579+00:00'
  }

PHP

StarkBankInvoicePullRequest Object
(
    [id] => 5435095766794240
    [subscriptionId] => 4799968485310464
    [invoiceId] => 4972480749895680
    [due] => DateTime Object
        (
            [date] => 2025-09-24 03:00:00.000000
            [timezone_type] => 1
            [timezone] => +00:00
        )

    [attemptType] => default
    [tags] => Array
        (
        )

    [externalId] => 3daac091504545c084570293d28b68a6
    [displayDescription] => 
    [status] => created
    [bacenId] => 
    [installmentId] => 6475364738007040
    [created] => DateTime Object
        (
            [date] => 2025-09-23 00:04:33.991778
            [timezone_type] => 1
            [timezone] => +00:00
        )

    [updated] => DateTime Object
        (
            [date] => 2025-09-23 00:04:33.991783
            [timezone_type] => 1
            [timezone] => +00:00
        )

)

Java

InvoicePullRequest({
  "subscriptionId": "6673482343514112",
  "invoiceId": "6028180624244736",
  "due": "2025-09-30T03:00:00+00:00",
  "attemptType": "default",
  "tags": [],
  "externalId": "b333bae493584983b50d4a80d8ca63af",
  "displayDescription": "",
  "status": "created",
  "installmentId": "4639632834691072",
  "created": "2025-09-25T19:48:53.288222+00:00",
  "updated": "2025-09-25T19:48:53.288227+00:00",
  "id": "5044069638078464"
})

Ruby

Not yet available. Please contact us if you need this SDK.

Elixir

Not yet available. Please contact us if you need this SDK.

C#

InvoicePullRequest(
  SubscriptionID: 4656724615102464,
  InvoiceID: 6649956664344576,
  Due: 9/14/2025 12:00:00AM,
  AttemptType: default,
  Tags: {  },
  ExternalID: 37e3b27472184110948dd9df8bdb51c0,
  DisplayDescription: ,
  Status: created,
  InstallmentID: 4910532083580928,
  Created: 9/10/2025 3:26:37PM,
  Updated: 9/10/2025 3:26:37PM,
  ID: 5783254137307136
)

Go

{
    Id:4816160109363200
    SubscriptionId:6136166097092608
    InvoiceId:5093778276745216
    Due:2025-11-08 03:00:00 +0000 +0000
    AttemptType:default
    Tags:[]
    ExternalId:my_external_id
    DisplayDescription:Your description
    Status:created
    InstallmentId:6132781528645632
    Created:2025-10-30 19:58:50.973653 +0000 +0000
    Updated:2025-10-30 19:58:50.973658 +0000 +0000
}

Clojure

Not yet available. Please contact us if you need this SDK.

Curl

{
    "message": "Requests successfully created",
    "requests": [
        {
            "id": "6335888560750592",
            "subscriptionId": "4776669403414528",
            "installmentId": "5187902950604800",
            "invoiceId": "6649956664344576",
            "displayDescription": "",
            "attemptType": "retry",
            "due": "2025-09-14T03:00:00+00:00",
            "status": "created",
            "externalId": "36e2956f98324f8fbe1cc9bddf76374f",
            "tags": [],
            "created": "2025-09-10T18:15:58.731439+00:00",
            "updated": "2025-09-10T18:15:58.731450+00:00"
        }
    ]
}

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.

RESPONSE

Python

{
   "event":{
      "id":"5099262327128064",
      "subscription":"invoice-pull-request",
      "created":"2025-09-17T03:00:17.374158+00:00",
      "workspaceId":"6304733023174656",
      "isDelivered":true,
      "log":{
         "created":"2025-09-17T03:00:16.723864+00:00",
         "description":"",
         "errors":[],
         "id":"5717910345482240",
         "reason":"",
         "request":{
            "attemptType":"default",
            "created":"2025-09-17T03:00:07.317174+00:00",
            "displayDescription":"Dragon Travel Fare",
            "due":"2025-09-19T03:00:00+00:00",
            "externalId":"13f957b9d0fa4293929d10d399e450b3",
            "id":"4862458556579840",
            "installmentId":"4628991717670912",
            "invoiceId":"6461241144901632",
            "status":"pending",
            "subscriptionId":"5663929787219968",
            "tags":[
                "order/123",
                "customer/456"
            ],
            "updated":"2025-09-17T03:00:16.723879+00:00"
         },
         "type":"pending"
      }
   }
}

Javascript

{
   "event":{
      "id":"5099262327128064",
      "subscription":"invoice-pull-request",
      "created":"2025-09-17T03:00:17.374158+00:00",
      "workspaceId":"6304733023174656",
      "isDelivered":true,
      "log":{
         "created":"2025-09-17T03:00:16.723864+00:00",
         "description":"",
         "errors":[],
         "id":"5717910345482240",
         "reason":"",
         "request":{
            "attemptType":"default",
            "created":"2025-09-17T03:00:07.317174+00:00",
            "displayDescription":"Dragon Travel Fare",
            "due":"2025-09-19T03:00:00+00:00",
            "externalId":"13f957b9d0fa4293929d10d399e450b3",
            "id":"4862458556579840",
            "installmentId":"4628991717670912",
            "invoiceId":"6461241144901632",
            "status":"pending",
            "subscriptionId":"5663929787219968",
            "tags":[
                "order/123",
                "customer/456"
            ],
            "updated":"2025-09-17T03:00:16.723879+00:00"
         },
         "type":"pending"
      }
   }
}

PHP

{
   "event":{
      "id":"5099262327128064",
      "subscription":"invoice-pull-request",
      "created":"2025-09-17T03:00:17.374158+00:00",
      "workspaceId":"6304733023174656",
      "isDelivered":true,
      "log":{
         "created":"2025-09-17T03:00:16.723864+00:00",
         "description":"",
         "errors":[],
         "id":"5717910345482240",
         "reason":"",
         "request":{
            "attemptType":"default",
            "created":"2025-09-17T03:00:07.317174+00:00",
            "displayDescription":"Dragon Travel Fare",
            "due":"2025-09-19T03:00:00+00:00",
            "externalId":"13f957b9d0fa4293929d10d399e450b3",
            "id":"4862458556579840",
            "installmentId":"4628991717670912",
            "invoiceId":"6461241144901632",
            "status":"pending",
            "subscriptionId":"5663929787219968",
            "tags":[
                "order/123",
                "customer/456"
            ],
            "updated":"2025-09-17T03:00:16.723879+00:00"
         },
         "type":"pending"
      }
   }
}

Java

{
   "event":{
      "id":"5099262327128064",
      "subscription":"invoice-pull-request",
      "created":"2025-09-17T03:00:17.374158+00:00",
      "workspaceId":"6304733023174656",
      "isDelivered":true,
      "log":{
         "created":"2025-09-17T03:00:16.723864+00:00",
         "description":"",
         "errors":[],
         "id":"5717910345482240",
         "reason":"",
         "request":{
            "attemptType":"default",
            "created":"2025-09-17T03:00:07.317174+00:00",
            "displayDescription":"Dragon Travel Fare",
            "due":"2025-09-19T03:00:00+00:00",
            "externalId":"13f957b9d0fa4293929d10d399e450b3",
            "id":"4862458556579840",
            "installmentId":"4628991717670912",
            "invoiceId":"6461241144901632",
            "status":"pending",
            "subscriptionId":"5663929787219968",
            "tags":[
                "order/123",
                "customer/456"
            ],
            "updated":"2025-09-17T03:00:16.723879+00:00"
         },
         "type":"pending"
      }
   }
}

Ruby

{
   "event":{
      "id":"5099262327128064",
      "subscription":"invoice-pull-request",
      "created":"2025-09-17T03:00:17.374158+00:00",
      "workspaceId":"6304733023174656",
      "isDelivered":true,
      "log":{
         "created":"2025-09-17T03:00:16.723864+00:00",
         "description":"",
         "errors":[],
         "id":"5717910345482240",
         "reason":"",
         "request":{
            "attemptType":"default",
            "created":"2025-09-17T03:00:07.317174+00:00",
            "displayDescription":"Dragon Travel Fare",
            "due":"2025-09-19T03:00:00+00:00",
            "externalId":"13f957b9d0fa4293929d10d399e450b3",
            "id":"4862458556579840",
            "installmentId":"4628991717670912",
            "invoiceId":"6461241144901632",
            "status":"pending",
            "subscriptionId":"5663929787219968",
            "tags":[
                "order/123",
                "customer/456"
            ],
            "updated":"2025-09-17T03:00:16.723879+00:00"
         },
         "type":"pending"
      }
   }
}

Elixir

{
   "event":{
      "id":"5099262327128064",
      "subscription":"invoice-pull-request",
      "created":"2025-09-17T03:00:17.374158+00:00",
      "workspaceId":"6304733023174656",
      "isDelivered":true,
      "log":{
         "created":"2025-09-17T03:00:16.723864+00:00",
         "description":"",
         "errors":[],
         "id":"5717910345482240",
         "reason":"",
         "request":{
            "attemptType":"default",
            "created":"2025-09-17T03:00:07.317174+00:00",
            "displayDescription":"Dragon Travel Fare",
            "due":"2025-09-19T03:00:00+00:00",
            "externalId":"13f957b9d0fa4293929d10d399e450b3",
            "id":"4862458556579840",
            "installmentId":"4628991717670912",
            "invoiceId":"6461241144901632",
            "status":"pending",
            "subscriptionId":"5663929787219968",
            "tags":[
                "order/123",
                "customer/456"
            ],
            "updated":"2025-09-17T03:00:16.723879+00:00"
         },
         "type":"pending"
      }
   }
}

C#

{
   "event":{
      "id":"5099262327128064",
      "subscription":"invoice-pull-request",
      "created":"2025-09-17T03:00:17.374158+00:00",
      "workspaceId":"6304733023174656",
      "isDelivered":true,
      "log":{
         "created":"2025-09-17T03:00:16.723864+00:00",
         "description":"",
         "errors":[],
         "id":"5717910345482240",
         "reason":"",
         "request":{
            "attemptType":"default",
            "created":"2025-09-17T03:00:07.317174+00:00",
            "displayDescription":"Dragon Travel Fare",
            "due":"2025-09-19T03:00:00+00:00",
            "externalId":"13f957b9d0fa4293929d10d399e450b3",
            "id":"4862458556579840",
            "installmentId":"4628991717670912",
            "invoiceId":"6461241144901632",
            "status":"pending",
            "subscriptionId":"5663929787219968",
            "tags":[
                "order/123",
                "customer/456"
            ],
            "updated":"2025-09-17T03:00:16.723879+00:00"
         },
         "type":"pending"
      }
   }
}

Go

{
   "event":{
      "id":"5099262327128064",
      "subscription":"invoice-pull-request",
      "created":"2025-09-17T03:00:17.374158+00:00",
      "workspaceId":"6304733023174656",
      "isDelivered":true,
      "log":{
         "created":"2025-09-17T03:00:16.723864+00:00",
         "description":"",
         "errors":[],
         "id":"5717910345482240",
         "reason":"",
         "request":{
            "attemptType":"default",
            "created":"2025-09-17T03:00:07.317174+00:00",
            "displayDescription":"Dragon Travel Fare",
            "due":"2025-09-19T03:00:00+00:00",
            "externalId":"13f957b9d0fa4293929d10d399e450b3",
            "id":"4862458556579840",
            "installmentId":"4628991717670912",
            "invoiceId":"6461241144901632",
            "status":"pending",
            "subscriptionId":"5663929787219968",
            "tags":[
                "order/123",
                "customer/456"
            ],
            "updated":"2025-09-17T03:00:16.723879+00:00"
         },
         "type":"pending"
      }
   }
}

Clojure

{
   "event":{
      "id":"5099262327128064",
      "subscription":"invoice-pull-request",
      "created":"2025-09-17T03:00:17.374158+00:00",
      "workspaceId":"6304733023174656",
      "isDelivered":true,
      "log":{
         "created":"2025-09-17T03:00:16.723864+00:00",
         "description":"",
         "errors":[],
         "id":"5717910345482240",
         "reason":"",
         "request":{
            "attemptType":"default",
            "created":"2025-09-17T03:00:07.317174+00:00",
            "displayDescription":"Dragon Travel Fare",
            "due":"2025-09-19T03:00:00+00:00",
            "externalId":"13f957b9d0fa4293929d10d399e450b3",
            "id":"4862458556579840",
            "installmentId":"4628991717670912",
            "invoiceId":"6461241144901632",
            "status":"pending",
            "subscriptionId":"5663929787219968",
            "tags":[
                "order/123",
                "customer/456"
            ],
            "updated":"2025-09-17T03:00:16.723879+00:00"
         },
         "type":"pending"
      }
   }
}

Curl

{
   "event":{
      "id":"5099262327128064",
      "subscription":"invoice-pull-request",
      "created":"2025-09-17T03:00:17.374158+00:00",
      "workspaceId":"6304733023174656",
      "isDelivered":true,
      "log":{
         "created":"2025-09-17T03:00:16.723864+00:00",
         "description":"",
         "errors":[],
         "id":"5717910345482240",
         "reason":"",
         "request":{
            "attemptType":"default",
            "created":"2025-09-17T03:00:07.317174+00:00",
            "displayDescription":"Dragon Travel Fare",
            "due":"2025-09-19T03:00:00+00:00",
            "externalId":"13f957b9d0fa4293929d10d399e450b3",
            "id":"4862458556579840",
            "installmentId":"4628991717670912",
            "invoiceId":"6461241144901632",
            "status":"pending",
            "subscriptionId":"5663929787219968",
            "tags":[
                "order/123",
                "customer/456"
            ],
            "updated":"2025-09-17T03:00:16.723879+00:00"
         },
         "type":"pending"
      }
   }
}

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:

ReasonDescription
senderInternalErrorThe payer had an internal error to create the pull request.
senderAccountClosedThe payer account was closed.
senderAccountBlockedThe payer account is blocked.
internalSettlementNotAllowedCannot send requests or update an account within the same institution or participant.
amountNotAllowedThe request amount exceeds the max amount limit of the subscription.
wrongAmountThe amount on the request does not match the accepted amount on the subscription.
senderTaxIdMismatchThe payer tax ID does not match the tax ID of subscription.
participantNotActiveThe participant is not active on the SPI.
invalidDueDateThe due date of pull request is incoherent with subscription interval.
invalidRetryDateThe pull request retry was sent after the allowed date.
invalidTimePeriodThe pull request was sent out of the allowed time period.
retryNotAllowedThe subscription does not allow pull request retries.
invalidSubscriptionBacenIdThe subscription Bacen ID is invalid or not found.
invalidActionThe subscription is not confirmed.
repeatedPullRequestA pull request for the same subscription and interval is already scheduled.
pullRequestAlreadySettledA pull request for the same subscription and interval has already succeeded.
invalidAttemptTypeThe pull request retry does not correspond with a previously failed pull request.
retryLimitExceededThe number of allowed pull request retries has been exceeded.
invalidSenderBankCodeThe debtor bank code is invalid or missing.
invalidSenderFinalTaxIdThe debtor tax ID is invalid or not found.
accountClosedThe payer account was closed.
accountBlockedThe payer account is blocked.
NotSettledThe request was not settled.
subscriptionCanceledThe subscription was canceled.
pixRequestFailedThe payer bank had an internal error to settle the Pix.
otherThe payer bank did not define the specific reason.
receiverUserRequestedThe cancelation was requested by the Stark Bank client.
senderUserRequestedThe payer requested the cancelation.

Python

import starkbank

request = starkbank.invoicepullrequest.cancel("6281065945628672")

print(request)

Javascript

const starkbank = require('starkbank');

(async() => {
    let request = await starkbank.invoicePullRequest.cancel("4873691062075392");

    console.log(request);
})();

PHP

$request = StarkBankInvoicePullRequest::cancel("6604482620162048");

print_r($request);

Java

import com.starkbank.*;

InvoicePullRequest request = InvoicePullRequest.cancel("5044069638078464");

System.out.println(request);

Ruby

Not yet available. Please contact us if you need this SDK.

Elixir

Not yet available. Please contact us if you need this SDK.

C#

using System;

InvoicePullRequest request = InvoicePullRequest.Cancel("5436641015496704");

Console.WriteLine(request);

Go

package main

import (
    "fmt"
    "github.com/starkbank/sdk-go/starkbank/invoicepullrequest"
)

func main() {

    request, err := invoicepullrequest.Cancel("6307501536444416", nil)
    if err.Errors != nil {
        for _, e := range err.Errors {
            t.Errorf("code: %s, message: %s", e.Code, e.Message)
        }
    }
    fmt.Printf("%+v
", request)
}

Clojure

Not yet available. Please contact us if you need this SDK.

Curl

curl --location --request DELETE '{{baseUrl}}/v2/invoice-pull-request/5999590968918016' 
--header 'Access-Id: {{accessId}}' 
--header 'Access-Time: {{accessTime}}' 
--header 'Access-Signature: {{accessSignature}}' 
--header 'Content-Type: application/json'
RESPONSE

Python

InvoicePullRequest(
        attempt_type=default,
        created=2025-09-07 03:00:15.420295,
        display_description=Iron Bank S.A.,
        due=2025-09-09 03:00:00,
        external_id=35ce0f6775fc42f8942b6142aa9fd9b6,
        id=6281065945628672,
        installment_id=6401171258343424,
        invoice_id=4616495631958016,
        status=scheduled,
        subscription_id=5692449980678144,
        tags=[],
        updated=2025-09-07 03:00:57.777005
)

Javascript

InvoicePullRequest {
  id: '4873691062075392',
  subscriptionId: '4880338438324224',
  invoiceId: '5742395538800640',
  due: '2025-09-09T03:00:00+00:00',
  attemptType: 'default',
  tags: [],
  externalId: 'c538aee2ee034d6583f17e0372f4bc1a',
  displayDescription: 'Iron Bank S.A.',
  status: 'scheduled',
  installmentId: '6535889886904320',
  created: '2025-09-07T03:00:15.422343+00:00',
  updated: '2025-09-07T03:00:56.517168+00:00'
}

PHP

StarkBankInvoicePullRequest Object
(
    [id] => 6604482620162048
    [subscriptionId] => 4776669403414528
    [invoiceId] => 6649956664344576
    [due] => DateTime Object
        (
            [date] => 2025-09-14 03:00:00.000000
            [timezone_type] => 1
            [timezone] => +00:00
        )

    [attemptType] => default
    [tags] => Array
        (
        )

    [externalId] => 33ae4ce29d4c461db23dfad8e7aebd7a
    [displayDescription] => 
    [status] => created
    [bacenId] => 
    [installmentId] => 5187902950604800
    [created] => DateTime Object
        (
            [date] => 2025-09-10 18:10:55.772558
            [timezone_type] => 1
            [timezone] => +00:00
        )

    [updated] => DateTime Object
        (
            [date] => 2025-09-10 18:30:03.457811
            [timezone_type] => 1
            [timezone] => +00:00
        )

)

Java

InvoicePullRequest({
  "subscriptionId": "6673482343514112",
  "invoiceId": "6028180624244736",
  "due": "2025-09-30T03:00:00+00:00",
  "attemptType": "default",
  "tags": [],
  "externalId": "b333bae493584983b50d4a80d8ca63af",
  "displayDescription": "",
  "status": "scheduled",
  "installmentId": "4639632834691072",
  "created": "2025-09-25T19:48:53.288222+00:00",
  "updated": "2025-09-25T19:49:03.030985+00:00",
  "id": "5044069638078464"
})

Ruby

Not yet available. Please contact us if you need this SDK.

Elixir

Not yet available. Please contact us if you need this SDK.

C#

InvoicePullRequest(
  SubscriptionID: 4798170211024896,
  InvoiceID: 6305345492221952,
  Due: 9/9/2025 12:00:00AM,
  AttemptType: default,
  Tags: {  },
  ExternalID: 8be26ecd3ed94720bdf0a953dedfe31f,
  DisplayDescription: Iron Bank S.A.,
  Status: scheduled,
  InstallmentID: 6628395563614208,
  Created: 9/7/2025 12:00:15AM,
  Updated: 9/7/2025 12:00:58AM,
  ID: 5436641015496704
)

Go

{
    Id:6307501536444416
    SubscriptionId:5661633187676160
    InvoiceId:5995635400507392
    Due:2025-10-30 03:00:00 +0000 +0000
    AttemptType:retry
    Tags:[]
    ExternalId:my_external_id
    DisplayDescription:Your description
    Status:scheduled
    InstallmentId:4586921330212864
    Created:2025-10-30 00:00:08.252214 +0000 +0000
    Updated:2025-10-30 00:00:37.409075 +0000 +0000
}

Clojure

Not yet available. Please contact us if you need this SDK.

Curl

{
    "message": "Request cancellation successfully requested",
    "request": {
        "id": "5999590968918016",
        "subscriptionId": "4631044443602944",
        "installmentId": "6624169517121536",
        "invoiceId": "5179445585379328",
        "displayDescription": "Iron Bank S.A.",
        "attemptType": "default",
        "due": "2025-09-09T03:00:00+00:00",
        "status": "scheduled",
        "externalId": "a2103d1ca3d5454d926d745fac97e2d2",
        "tags": [],
        "created": "2025-09-07T03:00:15.424620+00:00",
        "updated": "2025-09-07T03:00:57.682596+00:00"
    }
}