Stark Bank Merchant Session API

openapi: 3.1.0
info:
  title: Stark Bank Balance Merchant Session 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: Merchant Session
  description: 'The Merchant Session resource can be created by a merchant and used by the card holder in order to collect their card data without having to handle it on the merchant''s side.

    The card data can be sent directly from a browser or app to Stark Bank''s API using the Merchant Session Purchase route.

    '
paths:
  /v2/merchant-session:
    post:
      summary: Create Merchant Sessions
      operationId: create-merchantSession
      tags:
      - Merchant Session
      description: 'This route allows the merchant to create a session that can be used by the card holder''s application to create a new purchase.

        The UUID parameter returned by the session should be used to create a Merchant Session Purchase.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                allowedFundingTypes:
                  type: string
                  description: The types of funding that are allowed to be used for the purchase. Options are "credit" and "debit".
                allowedInstallments:
                  type: string
                  description: 'The amount and number of installments allowed for the purchase. A non-negative integer that represents the amount in cents to be received and the number of installments. E.g: 100 (R$1.00).'
                expiration:
                  type: integer
                  description: 'Time in seconds counted from the creation datetime until the session expires. After expiration, a purchase cannot be created using the session anymore. E.g.: 3600 (1 hour).'
                allowedIps:
                  type: string
                  description: The IP addresses that are allowed to create a purchase using the session.
                challengeMode:
                  type: string
                  description: 'Defines whether or not a holder verification (3DS) will be used when authorizing the purchase. 3DS is a protocol designed to enhance security for e-commerce purchases. When enabled, the issuer provides a link for the card holder to complete a verification challenge. Options are "enabled" and "disabled". Default: "enabled"'
                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:
              - allowedFundingTypes
              - allowedInstallments
              - expiration
      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 Merchant Sessions
      operationId: list-merchantSession
      tags:
      - Merchant Session
      description: Get a list of merchant sessions 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 sessions by the specified status, such as: active, expired, success.'
        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/merchant-session/{uuid}/purchase:
    post:
      summary: Create Merchant Session Purchase
      operationId: create-merchantSession-byUuid-purchase
      tags:
      - Merchant Session
      description: 'This route can be used to create a Merchant Purchase directly from the payer''s client application.

        The UUID of a Merchant Session that was previously created by the merchant is necessary to access this route.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: integer
                  description: 'A non-negative integer that represents the amount in cents to be received. E.g: 100 (R$1.00)'
                cardExpiration:
                  type: string
                  description: A string in the format YYYY-MM representing the expiration of the card to be used for the purchase.
                cardNumber:
                  type: string
                  description: A string representing the number of the card to be used for the purchase.
                cardSecurityCode:
                  type: string
                  description: A string representing the security code of the card to be used for the purchase.
                fundingType:
                  type: string
                  description: The type of funding to be used for the purchase. Options are "credit" and "debit".
                holderName:
                  type: string
                  description: The name of the card holder as it appears on the card.
                billingCity:
                  type: string
                  description: The billing city associated with the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise.
                billingCountryCode:
                  type: string
                  description: The billing country code associated with the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise.
                billingStateCode:
                  type: string
                  description: The billing state code associated with the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise.
                billingStreetLine1:
                  type: string
                  description: The billing street address associated with the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise.
                billingStreetLine2:
                  type: string
                  description: The billing street address complement associated with the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise.
                billingZipCode:
                  type: string
                  description: The billing zip code associated with the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise.
                holderEmail:
                  type: string
                  description: The email associated with the holder of the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise.
                holderPhone:
                  type: string
                  description: The phone number associated with the holder of the card used for the purchase. Required if challengeMode is "enabled" and optional otherwise.
                installmentCount:
                  type: string
                  description: 'A non-negative integer that represents the number of purchase installments. Default: 1'
                metadata:
                  type: string
                  description: 'An object containing additional data related to the purchase. If 3DS is enabled, the following fields related to the payer''s device are required: userAgent, timezoneOffset, userIp, language.'
              required:
              - amount
              - cardExpiration
              - cardNumber
              - cardSecurityCode
              - fundingType
              - holderName
              - billingCity
              - billingCountryCode
              - billingStateCode
              - billingStreetLine1
              - billingStreetLine2
              - billingZipCode
              - holderEmail
              - holderPhone
              - metadata
      parameters:
      - name: uuid
        in: path
        description: The UUID of the Merchant Session created by the merchant to process the purchase.
        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/merchant-session/{id}:
    get:
      summary: Get a Merchant Session
      operationId: get-merchantSession-byId
      tags:
      - Merchant Session
      description: Retrieve detailed information about a specific session by its id.
      parameters:
      - name: id
        in: path
        description: The unique identifier for the merchant session that needs to be retrieved.
        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'
  /v2/merchant-session/log:
    get:
      summary: List Merchant Session Logs
      operationId: list-merchantSession-log
      tags:
      - Merchant Session
      description: 'Get a paged list of merchant session logs.

        A log tracks a change in the session 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: sessionIds
        in: query
        description: Filter the merchant session ids to only include its corresponding logs
        required: false
        schema:
          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/merchant-session/log/{id}:
    get:
      summary: Get a Merchant Session Log
      operationId: get-merchantSession-log-byId
      tags:
      - Merchant Session
      description: Get a single merchant session log by its id.
      parameters:
      - name: id
        in: path
        description: The unique identifier for the merchant session that needs to be retrieved.
        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