Stark Bank Transfer API

openapi: 3.1.0
info:
  title: Stark Bank Balance Transfer 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: Transfer
  description: 'Transfers are used to send money to any bank account in Brazil using the Ted or Pix systems.

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

    '
paths:
  /v2/transfer:
    post:
      summary: Create Transfers
      operationId: create-transfer
      tags:
      - Transfer
      description: 'This route is used to send your transfers to their receivers.

        You can create up to 100 transfers in a single request.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                accountNumber:
                  type: string
                  description: 'Receiver bank account number. Use "-" before the validation digit. Example: 876543-2.'
                amount:
                  type: integer
                  description: 'A positive integer that represents the amount in cents to be transferred. Example: 100 (R$1.00)'
                bankCode:
                  type: string
                  description: 'Besides informing the receiver bank, this parameter specifies whether this will be a Pix or a Ted transfer. If you wish to send a Pix, pass the bank ISPB (8 digits). Example: 20018183 = StarkBank. If you wish to send a Ted, pass the usual bank code (1 to 3 digits). Example: 665 = Stark'
                branchCode:
                  type: string
                  description: 'Receiver bank account branch. Use "-" in case there is a validation digit. Example: 1234-5'
                name:
                  type: string
                  description: 'Receiver full name. Example: "Joana da Silva"'
                taxId:
                  type: string
                  description: 'Receiver CPF (11 digits formatted or unformatted) or CNPJ (14 digits formatted or unformatted). Example: 012.345.678-90'
                accountType:
                  type: string
                  description: Receiver bank account type. Options are "checking", "payment", "savings" and "salary". "checking" is the default. This parameter only has effect on Pix Transfers.
                description:
                  type: string
                  description: 'Optional description to override default description to be shown in the bank statement. Example: "Payment for service #1234"'
                displayDescription:
                  type: string
                  description: 'Description to be shown in the receiver bank interface. ex: "Payment for service #1234"'
                externalId:
                  type: string
                  description: 'Unique ID to prevent duplicate transfers. Repeated externalIds should cause failures by duplication. By default, it blocks transfers to the same bank account with the same amount on the same day. Example: "my-internal-id-123456"'
                rules:
                  type: array
                  items:
                    type: string
                  description: 'List of rules for modifying transfer behavior. Example:

                    [{"key": "resendingLimit", "value": 5}]

                    '
                scheduled:
                  type: string
                  format: date-time
                  description: 'Schedule the transfer for a specific date. Today is the default. Ted Transfer''s schedules for today will be accepted until 16:00 (BRT) and will be pushed to the next business day afterwards. Pix Transfers are available 24/7 and can be scheduled for any date and time. Example: "2020-08-14T15:23:26+00:00" or "2020-08-14"'
                tags:
                  type: array
                  items:
                    type: string
                  description: Array of strings to tag the entity for future queries. All tags will be converted to lowercase.
              required:
              - accountNumber
              - amount
              - bankCode
              - branchCode
              - name
              - taxId
      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 Transfers
      operationId: list-transfer
      tags:
      - Transfer
      description: Here you can list and filter all transfers you have made. We return it paged.
      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: sort
        in: query
        description: 'Sort order considered in the response. Options are: "created", "-created", "updated" and "-updated". "-" means descending order. Default is "-created".'
        required: false
        schema:
          type: string
      - name: status
        in: query
        description: Filter transfers 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
      - name: taxId
        in: query
        description: Filter transfers sent to the specified tax ID.
        required: false
        schema:
          type: string
      - name: transactionIds
        in: query
        description: List of transaction IDs linked to the desired transfers.
        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/transfer/{id}:
    get:
      summary: Get a Transfer
      operationId: get-transfer-byId
      tags:
      - Transfer
      description: Get a single transfer by its id.
      parameters:
      - name: id
        in: path
        description: Id of the transfer 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: Cancel a scheduled Transfer
      operationId: delete-transfer-byId
      tags:
      - Transfer
      description: 'Cancel a scheduled transfer. You can only cancel transfers before they start being processed.

        NOTE:Canceled transfers will still appear in your queries.

        '
      parameters:
      - name: id
        in: path
        description: Id of the transfer 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/transfer/{id}/pdf:
    get:
      summary: Get a Transfer PDF
      operationId: get-transfer-byId-pdf
      tags:
      - Transfer
      description: Get a PDF from a single transfer by its id.
      parameters:
      - name: id
        in: path
        description: Id of the transfer entity.
        required: true
        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/transfer/log:
    get:
      summary: List Transfer Logs
      operationId: list-transfer-log
      tags:
      - Transfer
      description: Get a paged list of all transfer logs. A log tracks a change in the transfer 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: 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: transferIds
        in: query
        description: Array of transfer ids that are linked to the logs you desire.
        required: false
        schema:
          type: array
          items:
            type: string
      - 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/transfer/log/{id}:
    get:
      summary: Get a Transfer Log
      operationId: get-transfer-log-byId
      tags:
      - Transfer
      description: Get a single transfer log by its id.
      parameters:
      - name: id
        in: path
        description: Id of the transfer 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