Stark Bank Boleto API

openapi: 3.1.0
info:
  title: Stark Bank Balance Boleto API
  version: v2
  description: 'This is our second API version. It is another small step towards launching the product we want to create for you, but it''s a giant leap for the brazilian financial market. We created the first banking API in Brazil and we are proud of it.

    Our API is RESTFul. This means we use predictable, resource-oriented URLs to do banking operations. The API itself speaks exclusively in JSON, including errors, but our SDK libraries convert responses to appropriate language-specific objects.

    Want to check our OpenAPI 3.1 specification? You can download our yaml file right here.

    You can also try our Postman collection. Download it here.

    '
  contact:
    name: Stark Bank Developers
    email: help@starkbank.com
    url: https://starkbank.com
  license:
    name: Stark Bank License
servers:
- url: https://api.starkbank.com
  description: Production
- url: https://sandbox.api.starkbank.com
  description: Sandbox
security:
- digitalSignature: []
tags:
- name: Boleto
  description: 'A boleto is a method you can use to charge your customers or load your Stark Bank account. Here we will teach you how to create and manage boletos.

    You can also split a Boleto between different receivers, you need to create a Split Receiver, and add the receiver into the Splits array.

    '
paths:
  /v2/boleto:
    post:
      summary: Create Boletos
      operationId: create-boleto
      tags:
      - Boleto
      description: This is how you create a new list of boletos. You can create up to 100 boletos per request. In case a boleto is paid after its due date and there is fine or interest, its amount will be updated with the paid amount. The same is valid if the boleto is paid with a discount.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: integer
                  description: 'A positive integer that represents the amount in cents to be charged. Example: 100 (R$1.00).'
                city:
                  type: string
                  description: 'Customer city name. Example: "São Paulo".'
                district:
                  type: string
                  description: 'Customer district name. Example: "Itaim Bibi".'
                name:
                  type: string
                  description: 'Customer full name. Example: "Anthony Edward Stark".'
                stateCode:
                  type: string
                  description: 'Customer state code. Example: "SP".'
                streetLine1:
                  type: string
                  description: 'Customer street address. Example: "Av. Faria Lima, 1844".'
                streetLine2:
                  type: string
                  description: 'Customer street address complement. Example: "CJ 13".'
                taxId:
                  type: string
                  description: 'Customer CPF (11 digits formatted or unformatted) or CNPJ (14 digits formatted or unformatted). Example: 012.345.678-90.'
                zipCode:
                  type: string
                  description: 'Customer zip code. Example: 01500-000.'
                descriptions:
                  type: array
                  items:
                    type: object
                  description: 'List of up to 15 descriptions containing information to help the customer understand why he is being charged. You can add text and amount to create a table or you can just add text. When generating PDFs, if the ''booklet'' layout is selected, only the text field of the first description will be considered and it will be used to fill the installment cell in the PDF. Example:

                    [{"text": "Explaining first part of the value", "amount": 20000}, {"text": "More text to explaining something to the customer"}]

                    '
                discounts:
                  type: array
                  items:
                    type: object
                  description: 'List of up to 2 discounts specifying the discount percentage and the limit date up to when the discount is valid. Example:

                    [{"percentage": 5, "date": "2020-04-01"}, {"percentage": 3.5, "date": "2020-04-02"}]

                    '
                due:
                  type: string
                  format: date-time
                  description: 'Due date of the boleto. Example: 2020-06-27. The default value is set to two days after creation date.'
                fine:
                  type: number
                  format: float
                  description: Percentage of the boleto amount charged if customer pays after the due date. Default value = 2.00 (2%).
                interest:
                  type: number
                  format: float
                  description: Monthly interest, in percentage, charged if customer pays after the due date. Default value = 1.00 (1%).
                overdueLimit:
                  type: string
                  description: Number of days after due date after which the boleto will no longer be payable. 0<=overdueLimit<=59. Default value=59.
                receiverName:
                  type: string
                  description: Name of the credit receiver (Sacador Avalista). If none is informed, workspace owner name will be used. If informed, receiverTaxId must also be informed.
                receiverTaxId:
                  type: string
                  description: Tax ID (CPF/CNPJ) of the credit receiver (Sacador Avalista). If none is informed, workspace owner tax ID will be used. If informed, receiverName must also be informed.
                splits:
                  type: array
                  items:
                    type: object
                  description: 'Array of Split objects to indicate payment receivers. Example:

                    [{"receiverId": "5742447426535424", "amount": 100}, {"receiverId": "5743243941642240", "amount": 200}]

                    '
                tags:
                  type: array
                  items:
                    type: string
                  description: Filter entities that contain the specified tags.
              required:
              - amount
              - city
              - district
              - name
              - stateCode
              - streetLine1
              - streetLine2
              - taxId
              - zipCode
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Client error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    get:
      summary: List Boletos
      operationId: list-boleto
      tags:
      - Boleto
      description: Get a list of non-deleted boletos in chunks of at most 100. If you need smaller chunks, use the limit parameter.
      parameters:
      - name: after
        in: query
        description: Filter entities created after this date.
        required: false
        schema:
          type: string
          format: date
      - name: before
        in: query
        description: Filter entities created before this date.
        required: false
        schema:
          type: string
          format: date
      - name: cursor
        in: query
        description: String used to get the next batch of results. Our SDKs handle this for you.
        required: false
        schema:
          type: string
      - name: fields
        in: query
        description: List of strings to filter response JSON keys. Not available in the SDKs.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: ids
        in: query
        description: List of strings to get specific entities by ids.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: limit
        in: query
        description: Number of results per cursor. Max = 100.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - name: status
        in: query
        description: Filter boletos by the specified status.
        required: false
        schema:
          type: string
      - name: tags
        in: query
        description: Filter entities that contain the specified tags.
        required: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Client error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /v2/boleto/{id}:
    get:
      summary: Get a Boleto
      operationId: get-boleto-byId
      tags:
      - Boleto
      description: Get a single boleto by its id.
      parameters:
      - name: id
        in: path
        description: Id of the boleto entity.
        required: true
        schema:
          type: string
      - name: fields
        in: query
        description: List of strings to filter response JSON keys. Not available in the SDKs.
        required: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Client error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    delete:
      summary: Delete a Boleto
      operationId: delete-boleto-byId
      tags:
      - Boleto
      description: 'Delete a single boleto. We will send a request to CIP to cancel the boleto registration. After the boleto registration is canceled, it won''t be possible to pay it anymore.

        NOTE: This action cannot be undone.

        '
      parameters:
      - name: id
        in: path
        description: Id of the boleto entity.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successfully deleted
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Client error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /v2/boleto/{id}/pdf:
    get:
      summary: Get a Boleto PDF
      operationId: get-boleto-byId-pdf
      tags:
      - Boleto
      description: Get a downloadable boleto PDF file. This route is public and does not require the usual authentication headers. However, if you request an invalid boleto ID too many times, your IP will be blocked for this specific route.
      parameters:
      - name: id
        in: path
        description: Id of the boleto entity
        required: true
        schema:
          type: string
      - name: hiddenFields
        in: query
        description: 'List of fields to be hidden in Boleto pdf. Example: ["customerAddress"].'
        required: false
        schema:
          type: array
          items:
            type: string
      - name: layout
        in: query
        description: PDF layout. Available options are "default" (full page) and "booklet" ("carnê").
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Client error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /v2/boleto/log:
    get:
      summary: List Boleto logs
      operationId: list-boleto-log
      tags:
      - Boleto
      description: Get a paged list of boleto logs. A log tracks a change in the boleto entity according to its life cycle.
      parameters:
      - name: after
        in: query
        description: Filter entities created after this date.
        required: false
        schema:
          type: string
          format: date
      - name: before
        in: query
        description: Filter entities created before this date.
        required: false
        schema:
          type: string
          format: date
      - name: boletoIds
        in: query
        description: Array of boleto ids that are linked to the logs you desire.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: cursor
        in: query
        description: String used to get the next batch of results. Our SDKs handle this for you.
        required: false
        schema:
          type: string
      - name: fields
        in: query
        description: List of strings to filter response JSON keys. Not available in the SDKs.
        required: false
        schema:
          type: array
          items:
            type: string
      - name: limit
        in: query
        description: Number of results per cursor. Max = 100.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - name: types
        in: query
        description: Filters logs by log types.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Client error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /v2/boleto/log/{id}:
    get:
      summary: Get a Boleto Log
      operationId: get-boleto-log-byId
      tags:
      - Boleto
      description: Get a single boleto log by its id.
      parameters:
      - name: id
        in: path
        description: Id of the log entity
        required: true
        schema:
          type: string
      - name: fields
        in: query
        description: List of strings to filter response JSON keys. Not available in the SDKs.
        required: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Client error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
components:
  schemas:
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code string
        message:
          type: string
          description: Human-readable error message
  securitySchemes:
    digitalSignature:
      type: apiKey
      name: Digital-Signature
      in: header
      description: ECDSA digital signature for request authentication
externalDocs:
  url: https://docs.starkbank.com/api
  description: Stark Bank API documentation
x-tagGroups:
- name: Business Account
  tags:
  - Workspace
  - Balance
  - Transaction
- name: Cash Receivables
  tags:
  - Invoice
  - Dynamic Brcode
  - Deposit
  - Boleto
  - Boleto Holmes
  - Split
  - Split Receiver
  - Split Profile
- name: Cash Subscription
  tags:
  - Invoice Pull Subscription
  - Invoice Pull Request
- name: Card Receivables
  tags:
  - Merchant Session
  - Merchant Purchase
  - Merchant Card
  - Merchant Installment
- name: Bill Payments
  tags:
  - Transfer
  - Brcode Payment
  - Boleto Payment
  - Utility Payment
  - Tax Payment
  - Darf Payment
  - Payment Preview
  - Payment Request
- name: Others
  tags:
  - Webhook
  - Event
  - Event Attempt
  - Pix Key
  - Institutions
  - Public Key