> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a new Submerchant

> Creates a submerchant FastPay account linked to the MerchantMaster.



## OpenAPI

````yaml /api-reference/openapi.yaml post /v1/submerchants
openapi: 3.0.0
info:
  title: FastPay API
  version: 1.0.0
  description: >-
    API for creating and managing payment charges.


    ## Authentication


    This API uses **Basic Authentication** for direct API access, such as
    creating charges.

    Use your API key as the username and an empty string as password.

    The header should be formatted as:


    `Authorization: Basic {base64(apiKey:)}`.


    For example:


    ```

    Authorization: Basic YWxleG91dG9uOiIi

    ```


    ## Webhooks


    FastPay sends webhooks to notify your application about charge status
    changes in real-time.

    Webhooks are sent via HTTP POST requests to your configured webhook
    endpoints.


    ### Webhook Events


    The following webhook events are available for charges:


    - `charge.created` - Sent when a new charge is created

    - `charge.pending` - Sent when a charge is pending payment

    - `charge.paid` - Sent when a charge is successfully paid

    - `charge.updated` - Sent when a charge is updated


    ### Webhook Payload Structure


    All webhook payloads follow this structure:


    ```json

    {
      "id": "webhook_event_id",
      "event": "charge.paid",
      "data": {
        // Complete charge object
      }
    }

    ```


    ### Webhook Delivery


    - Webhooks are sent via HTTP POST requests

    - Content-Type: `application/json`

    - Retry logic is implemented for failed deliveries

    - Webhook events are stored in the database for audit purposes

    - Delivery logs are maintained for debugging and monitoring


    ### Webhook Security


    - Webhooks are sent to pre-configured endpoints

    - Endpoints can be enabled/disabled per merchant

    - Event filtering is supported (only receive specific events)

    - Failed deliveries are retried with exponential backoff
servers:
  - url: https://api-global.fastpaybrasil.com
    description: Produção e Sandbox (diferenciados pela API key)
security: []
paths:
  /v1/submerchants:
    post:
      tags:
        - FastConnect
      summary: Create a new Submerchant
      description: Creates a submerchant FastPay account linked to the MerchantMaster.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewSubMerchant'
      responses:
        '201':
          description: The charge has been successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedSubMerchant'
        '401':
          description: Unauthorized - invalid credentials
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 401
                  message:
                    type: string
                    example: Unauthorized
        '403':
          description: Forbidden - insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 403
                  message:
                    type: string
                    example: Forbidden
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 422
                  error:
                    type: string
                    example: Unprocessable Entity
                  message:
                    type: string
                    example: >-
                      The items list contains one of more items with invalid
                      type.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                    example: 500
                  message:
                    type: string
                    example: Internal server error
      security:
        - basic: []
components:
  schemas:
    NewSubMerchant:
      type: object
      required:
        - legalName
        - tradeName
        - companyTaxId
        - website
        - averageMonthlyRevenue
        - averageOrderValue
        - productType
        - legalRepresentative
        - contactEmail
        - productDescription
        - address
        - phones
        - bankAccount
        - canAccessDashboard
      properties:
        legalName:
          type: string
          description: The legal name of the merchant.
          example: ACME Corp
        tradeName:
          type: string
          description: The trade name of the merchant.
          example: ACME
        companyTaxId:
          type: string
          description: The tax identification number of the merchant.
          example: 12.345.678/0001-99
        website:
          type: string
          format: uri
          description: The website URL of the merchant.
          example: https://google.com
        averageMonthlyRevenue:
          type: number
          description: The average monthly revenue of the merchant.
          example: 5000
        averageOrderValue:
          type: number
          description: The average order value of the merchant.
          example: 100
        productType:
          type: string
          enum:
            - digital
            - physical
            - both
          description: The type of products sold by the merchant.
          example: digital
        legalRepresentative:
          type: object
          required:
            - fullName
            - idNumber
            - dateOfBirth
            - nationality
            - email
            - motherName
            - gender
            - phones
          properties:
            fullName:
              type: string
              description: The full name of the legal representative.
              example: John Doe
            dateOfBirth:
              type: string
              format: date
              description: The birth date of the legal representative.
              example: '1980-01-01'
            nationality:
              type: string
              description: The nationality of the legal representative.
              example: United State
            idNumber:
              type: string
              description: The identification number of the legal representative.
              example: '1234567890'
            idType:
              type: string
              description: The type of identification document.
              example: passport
            issuingCountry:
              type: string
              description: The country that issued the identification document.
              example: USA
            email:
              type: string
              description: The email address of the legal representative.
              example: john.doe@example.com
            motherName:
              type: string
              description: The mother's name of the legal representative.
              example: Jane Doe
            gender:
              type: string
              enum:
                - M
                - F
              description: The gender of the legal representative.
              example: M
            address:
              type: object
              description: >-
                Endereço do representante (opcional). Quando enviado, é aplicado
                ao representante; quando omitido, o representante herda o
                endereço da empresa (comportamento anterior).
              required:
                - addressLine1
                - neighborhood
                - city
                - state
                - country
                - postalCode
              properties:
                addressLine1:
                  type: string
                  description: The street name of the address.
                  example: 123 Main St
                addressLine2:
                  type: string
                  description: The street number of the address.
                  example: Apt 1
                neighborhood:
                  type: string
                  description: The neighborhood of the address.
                  example: Downtown
                city:
                  type: string
                  description: The city of the address.
                  example: New York
                state:
                  type: string
                  description: The state of the address.
                  example: CA
                country:
                  type: string
                  description: The country of the address.
                  example: USA
                postalCode:
                  type: string
                  description: The postal code of the address.
                  example: '12345'
            phones:
              type: array
              description: List of phone numbers for the legal representative.
              items:
                type: object
                required:
                  - type
                  - number
                properties:
                  type:
                    type: string
                    description: The type of the phone number.
                    example: mobile
                  number:
                    type: string
                    description: The phone number.
                    example: '5551234'
        additionalRepresentatives:
          type: array
          description: >-
            Sócios adicionais da empresa (opcional). Cada item tem o **mesmo
            formato**

            do objeto `legalRepresentative`. O `legalRepresentative` continua
            obrigatório

            e é sempre o **representante legal** da subconta; os adicionais são

            cadastrados como sócios não-representantes.


            Os **documentos** dos sócios não vão neste corpo — após a criação,
            use os

            `id` retornados em `legalRepresentatives` (resposta) para vincular o
            upload

            de documentos de cada sócio via token de upload.
          items:
            $ref: '#/components/schemas/NewSubMerchantRepresentative'
        contactEmail:
          type: string
          description: The contact email of the merchant.
          example: contact@merchant.com
        productDescription:
          type: string
          description: >-
            A brief description of the products or services offered by the
            merchant.
          example: We sell electronic gadgets and accessories.
        softDescriptor:
          type: string
          maxLength: 40
          description: >-
            The soft descriptor that will appear on customers' credit card
            statements.
          example: ACME*GADGETS
        address:
          type: object
          description: The address of the merchant.
          required:
            - addressLine1
            - neighborhood
            - city
            - state
            - country
            - postalCode
          properties:
            addressLine1:
              type: string
              description: The street name of the address.
              example: 123 Main St
            addressLine2:
              type: string
              description: The street number of the address.
              example: Apt 1
            neighborhood:
              type: string
              description: The neighborhood of the address.
              example: Downtown
            city:
              type: string
              description: The city of the address.
              example: New York
            state:
              type: string
              description: The state of the address.
              example: CA
            country:
              type: string
              description: The country of the address.
              example: USA
            postalCode:
              type: string
              description: The postal code of the address.
              example: '12345'
        phones:
          type: array
          description: List of phone numbers for the merchant.
          items:
            type: object
            required:
              - type
              - number
            properties:
              type:
                type: string
                description: The type of the phone number.
                example: mobile
              number:
                type: string
                description: The phone number.
                example: '5551234'
        postbackUrl:
          type: string
          format: uri
          description: >-
            Optional URL to receive a webhook notification when the merchant
            approval status changes.
          example: https://merchant.com/webhooks/merchant-status
        canAccessDashboard:
          type: boolean
          description: Defines if the merchant can access the dashboard.
          example: true
        user:
          type: object
          description: Required when canAccessDashboard is true.
          required:
            - fullName
            - email
            - phone
          properties:
            fullName:
              type: string
              description: The name of the user.
              example: John Doe
            email:
              type: string
              description: The email address of the user.
              example: john.doe@example.com
            phone:
              type: string
              description: >-
                The phone number of the user in strict international format
                (E.164), e.g. +5511999999999.
              example: '+5511999999999'
        bankAccount:
          type: object
          required:
            - bankCode
            - agencyCode
            - accountNumber
            - accountDigit
            - accountType
            - bankName
            - recipientName
            - recipientDocument
          properties:
            bankCode:
              type: string
              description: The bank code of the bank account.
              example: '001'
            agencyCode:
              type: string
              description: The agency code of the bank account.
              example: '1234'
            accountNumber:
              type: string
              description: The account number of the bank account.
              example: '567890'
            accountDigit:
              type: string
              description: The account digit of the bank account.
              example: '0'
            accountType:
              type: string
              enum:
                - checking
                - savings
              description: The account type of the bank account.
              example: checking
            bankName:
              type: string
              description: The name of the bank.
              example: Bank of America
            recipientName:
              type: string
              description: The name of the bank account recipient.
              example: John Doe
            recipientDocument:
              type: string
              description: >-
                CPF or CNPJ of the bank account recipient (validated with check
                digits).
              example: '12345678900'
            routingNumber:
              type: string
              description: >-
                The routing number of the bank account (for US accounts).
                Optional.
              example: '021000021'
    CreatedSubMerchant:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: The unique identifier of the created submerchant
          example: 2vorkDcXyvzifL63YX09S9VqcnI
        legalRepresentatives:
          type: array
          description: >-
            Representantes criados — o **principal primeiro** (`isPrimary:
            true`) e

            depois os sócios adicionais na ordem enviada. Use os `id` dos itens
            com

            `isPrimary: false` para vincular o upload de documentos de cada
            sócio.
          items:
            type: object
            properties:
              id:
                type: string
                description: Identificador do representante/sócio
                example: 2vorkEaaaBbbCccDddEeeFffGgg
              fullName:
                type: string
                description: Nome completo
                example: Ana Principal
              isPrimary:
                type: boolean
                description: '`true` apenas no representante legal da empresa'
                example: true
      example:
        id: 2vorkDcXyvzifL63YX09S9VqcnI
        legalRepresentatives:
          - id: 2vorkEaaaBbbCccDddEeeFffGgg
            fullName: Ana Principal
            isPrimary: true
          - id: 2vorkEbbbCccDddEeeFffGggHhh
            fullName: Bruno Sócio
            isPrimary: false
    NewSubMerchantRepresentative:
      type: object
      description: Sócio adicional — mesmo formato do objeto `legalRepresentative`.
      required:
        - fullName
        - idNumber
        - dateOfBirth
        - nationality
        - email
        - motherName
        - gender
        - phones
      properties:
        fullName:
          type: string
          description: The full name of the representative.
          example: Bruno Sócio
        dateOfBirth:
          type: string
          format: date
          description: The birth date of the representative.
          example: '1985-05-10'
        nationality:
          type: string
          description: The nationality of the representative.
          example: Brazilian
        idNumber:
          type: string
          description: >-
            The identification number of the representative (CPF for BR,
            validated with check digits).
          example: '98765432100'
        idType:
          type: string
          description: The type of identification document.
          example: cpf
        issuingCountry:
          type: string
          description: The country that issued the identification document.
          example: BR
        email:
          type: string
          description: The email address of the representative.
          example: bruno.socio@example.com
        motherName:
          type: string
          description: The mother's name of the representative.
          example: Maria Sócio
        gender:
          type: string
          enum:
            - M
            - F
          description: The gender of the representative.
          example: M
        address:
          type: object
          description: >-
            Endereço do sócio (opcional). Quando omitido, herda o endereço da
            empresa.
          required:
            - addressLine1
            - neighborhood
            - city
            - state
            - country
            - postalCode
          properties:
            addressLine1:
              type: string
              example: 123 Main St
            addressLine2:
              type: string
              example: Apt 1
            neighborhood:
              type: string
              example: Downtown
            city:
              type: string
              example: São Paulo
            state:
              type: string
              example: SP
            country:
              type: string
              example: BR
            postalCode:
              type: string
              example: 01310-100
        phones:
          type: array
          description: List of phone numbers for the representative.
          items:
            type: object
            required:
              - type
              - number
            properties:
              type:
                type: string
                example: mobile
              number:
                type: string
                example: '5551234'
  securitySchemes:
    basic:
      type: http
      scheme: basic
      description: |-
        HTTP Basic authentication. Use your secret key as the
        username and an empty string as password. The API key
        should be base64 encoded in the format 'username:' when
        sending the Authorization header.

````