openapi: 3.0.1
info:
  title: Theropay BaaS API
  description: >
    Theropay Banking-as-a-Service (BaaS) API provides a full suite of banking
    services for merchants and customers, enabling secure, scalable, and
    programmable banking operations. 


    The API allows seamless integration of banking functionality into your
    applications, including: Customer onboarding and management, Account
    creation, retrieval and updates,Internal and external fund transfers.
  contact:
    name: API Support
    email: support@theropay.io
  version: null
servers:
  - url: https://api.theropay.io
    description: Production server
paths:
  /finance/api/v1/business:
    post:
      tags:
        - Business
      summary: Creates a new business.
      requestBody:
        description: Request object containing details of the business to create.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBusinessRequest'
      responses:
        '200':
          description: OK
  /finance/api/v1/business/{id}:
    get:
      tags:
        - Business
      summary: Retrieves business details for a specific business ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: OK
  /finance/api/v1/identity-verification:
    post:
      tags:
        - Business
      summary: Creates an identity verification request for a customer.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdentityVerificationRequest'
      responses:
        '200':
          description: OK
  /finance/api/v1/account/{businessId}:
    post:
      tags:
        - Accounts
      summary: Creates a new account for a business.
      parameters:
        - name: businessId
          in: path
          required: true
          schema:
            type: integer
            format: int32
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAccountRequest'
      responses:
        '200':
          description: OK
  /finance/api/v1/account/{accountId}/balance:
    get:
      tags:
        - Accounts
      summary: Retrieves the current balance of a specific account.
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
  /finance/api/v1/counterparty:
    post:
      tags:
        - Business
      summary: Creates a new counterparty.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCounterpartyRequest'
      responses:
        '200':
          description: OK
        '201':
          description: Created
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /finance/api/v1/transaction/ach/pull:
    post:
      tags:
        - Transactions
      summary: Performs an ACH pull transaction.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PerformAchPullRequest'
      responses:
        '200':
          description: OK
        '201':
          description: Created
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /finance/api/v1/transaction/ach/push:
    post:
      tags:
        - Transactions
      summary: Performs an ACH push transaction.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PerformAchPushRequest'
      responses:
        '200':
          description: OK
        '201':
          description: Created
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /finance/api/v1/transaction/wire/international:
    post:
      tags:
        - Transactions
      summary: Perform an international wire outbound transaction.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InternationalWireTransactionRequest'
      responses:
        '200':
          description: OK
        '201':
          description: Created
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /finance/api/v1/transaction/wire/domestic:
    post:
      tags:
        - Transactions
      summary: Performs a Domestic wire outbound transaction.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomesticWireTransactionRequest'
      responses:
        '200':
          description: OK
        '201':
          description: Created
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /finance/api/v1/transaction/internal/transfer:
    post:
      tags:
        - Transactions
      summary: Performs an Internal wire transfer.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PerformWireInternalTransactionRequest'
      responses:
        '200':
          description: OK
        '201':
          description: Created
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
components:
  schemas:
    AchDetailsRequest:
      type: object
      properties:
        accountNumber:
          type: string
          nullable: true
        address:
          $ref: '#/components/schemas/AddressRequest'
        bankAccountType:
          type: string
          nullable: true
        bankName:
          type: string
          nullable: true
        gatewayRoutingNumber:
          type: string
          nullable: true
        rdfiNumberQualifier:
          type: string
          nullable: true
        routingNumber:
          type: string
          nullable: true
      additionalProperties: false
    AchRequest:
      type: object
      required:
        - accountNumber
        - bankAccountType
        - routingNumber
      properties:
        accountNumber:
          type: string
          description: The account number
        address:
          $ref: '#/components/schemas/AddressRequest'
        bankAccountType:
          type: string
          description: The type of the bank account
          enum:
            - SAVINGS
            - CHECKING
        bankName:
          type: string
        gatewayRoutingNumber:
          type: string
          description: Required only if used for IAT ACH transaction
        rdfiNumberQualifier:
          type: string
          description: Required only if used for IAT ACH transaction
          enum:
            - NATIONAL_CLEARING_SYSTEM
            - BIC
            - IBAN
        routingNumber:
          type: string
          description: The routing number of the bank
      additionalProperties: false
    AddressRequest:
      type: object
      properties:
        city:
          type: string
        countryCode:
          type: string
          description: Country code, required only for [Business] and [Individual]
        line1:
          type: string
          description: Address line 1
        line2:
          type: string
          description: Address line 2
        postalCode:
          type: string
          description: Postal Code
        state:
          type: string
        type:
          type: string
          enum:
            - MAILING
            - RESIDENCE
            - BUSINESS
            - OTHER
      additionalProperties: false
    BraidRequest:
      type: object
      required:
        - accountNumber
      properties:
        accountNumber:
          type: string
          description: Braid account number if the counterparty has an account on Braid
      additionalProperties: false
    CancelTransactionRequest:
      type: object
      properties:
        achReturnCode:
          type: string
          nullable: true
        paymentId:
          type: string
          nullable: true
        reason:
          type: string
          nullable: true
      additionalProperties: false
    CreateAccountRequest:
      type: object
      properties:
        accountName:
          type: string
          nullable: true
        accountType:
          type: string
          nullable: true
        fundingAccountNumber:
          type: string
          nullable: true
        presetAccountNumber:
          type: string
          nullable: true
      additionalProperties: false
    CreateBusinessRequest:
      type: object
      properties:
        ach:
          $ref: '#/components/schemas/AchDetailsRequest'
        achCompanyId:
          type: string
          nullable: true
        achCompanyName:
          type: string
          nullable: true
        address:
          $ref: '#/components/schemas/AddressRequest'
        businessEntityType:
          type: string
          nullable: true
        businessIdType:
          type: string
          nullable: true
        dba:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        formationDate:
          type: string
          nullable: true
        idNumber:
          type: string
          nullable: true
        incorporationState:
          type: string
          nullable: true
        mcc:
          type: string
          nullable: true
        mobilePhone:
          type: string
          nullable: true
        naics:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        productId:
          type: integer
          format: int32
        submittedBy:
          $ref: '#/components/schemas/SubmittedByRequest'
        website:
          type: string
          nullable: true
      additionalProperties: false
    CreateCounterpartyRequest:
      required:
        - bankAccountType
        - routingNumber
        - name
        - address
        - beneficiaryFIIdType
        - beneficiaryFIName
        - receiverRoutingNumber
      type: object
      properties:
        accountNumber:
          type: string
        ach:
          $ref: '#/components/schemas/AchRequest'
        braid:
          $ref: '#/components/schemas/BraidRequest'
        businessId:
          type: int32
          description: The businessId the counterparty is associated with.
        dateOfBirth:
          type: date
        email:
          type: string
          description: Email of the counterparty
        idNumber:
          type: string
          description: ID number of the counterparty
        individualId:
          type: int32
          description: The individualId the counterparty is associated with.
        name:
          type: string
          required: true
          description: Name of the counterparty
        phone:
          type: string
          description: Phone number of the counterparty
        idType:
          type: string
          description: ID Type of the counterparty
          enum:
            - EIN
            - SSN
            - TIN
            - DRIVING_LICENSE
            - NATIONAL_ID_CARD
            - ITIN
            - PASSPORT
            - OTHER_ID
        productId:
          type: int32
          description: The productId the counterparty is associated with
        bankAccountType:
          type: string
          enum:
            - SAVINGS
            - CHECKINGS
        type:
          type: string
          description: Type of the counterparty
          enum:
            - BUSINESS
            - INDIVIDUAL
        wire:
          $ref: '#/components/schemas/WireRequest'
      additionalProperties: false
    DocumentRequest:
      type: object
      properties:
        content:
          type: string
          nullable: true
        documentType:
          type: string
          nullable: true
        extension:
          type: string
          nullable: true
      additionalProperties: false
    DomesticWireTransactionRequest:
      type: object
      required:
        - accountNumber
        - amount
        - counterpartyId
        - description
      properties:
        accountNumber:
          type: string
        amount:
          type: number
          description: >-
            Explicit decimal point and trailing zeros are truncated.
            Example:1234.56.
        counterpartyId:
          type: integer
        description:
          type: string
          description: >-
            The first 10 character of the description will be used as Company
            Entry Description in the Nacha file. (For ACH endpoints). Originator
            to receiver message (For wire endpoints).
        externalId:
          type: string
          description: External reference ID
        internalNote:
          type: string
          description: Transaction Internal Note
      additionalProperties: false
    IdentityVerificationRequest:
      type: object
      properties:
        customerId:
          type: integer
          format: int32
        docs:
          type: array
          items:
            $ref: '#/components/schemas/DocumentRequest'
          nullable: true
        isDeveloperInitiated:
          type: boolean
        provider:
          type: array
          items:
            type: string
          nullable: true
        result:
          type: string
          nullable: true
        verificationResult:
          type: string
          nullable: true
      additionalProperties: false
    InternationalWireTransactionRequest:
      type: object
      required:
        - accountNumber
        - amount
        - counterpartyId
        - description
      properties:
        accountNumber:
          type: string
        amount:
          type: number
          description: >-
            Explicit decimal point and trailing zeros are truncated.
            Example:1234.56.
        counterpartyId:
          type: integer
        description:
          type: string
          description: >-
            The first 10 character of the description will be used as Company
            Entry Description in the Nacha file. (For ACH endpoints). Originator
            to receiver message (For wire endpoints).
        externalId:
          type: string
          description: External reference ID
        internalNote:
          type: string
          description: Transaction Internal Note
      additionalProperties: false
    PerformAchPullRequest:
      type: object
      required:
        - accountNumber
        - amount
        - counterpartyId
        - description
        - secCode
      properties:
        accountNumber:
          type: string
        addenda:
          type: string
          description: >-
            Optional text filed in the Nacha file for payment information. May
            or may not be displayed to the recipient. Max length 80
        amount:
          type: number
          description: >-
            Explicit decimal point and trailing zeros are truncated.
            Example:1234.56.
        counterpartyId:
          type: integer
          format: int32
          description: counterparty ID of the recipient
        description:
          type: string
          description: >-
            The first 10 character of the description will be used as Company
            Entry Description in the Nacha file. (For ACH endpoints). Originator
            to receiver message (For wire endpoints).
        effectiveEntryDate:
          type: date
          description: >-
            Effective entry date for the transaction in the Nacha file. Needs to
            be an eligible date for Effective Entry Date if present.
        externalId:
          type: string
          description: Optional external ID to track the transaction
        internalNote:
          type: string
          description: Transaction Internal Note
        prenote:
          type: boolean
          description: Amount must be 0 if true
        secCode:
          type: string
          description: SEC Code per Nacha standard
          enum:
            - CCD
            - CIE
            - PPD
            - TEL
            - WEB
            - IAT
        service:
          type: string
          description: >-
            SAME_DAY to request a Same Day ACH. STANDARD to request Next Day
            ACH. The final process date depends on the Financial Institution’s
            processing window.
          enum:
            - STANDARD
            - SAME_DAY
      additionalProperties: false
    PerformAchPushRequest:
      type: object
      required:
        - accountNumber
        - amount
        - counterpartyId
        - description
        - secCode
      properties:
        accountNumber:
          type: string
        addenda:
          type: string
          description: >-
            Optional text filed in the Nacha file for payment information. May
            or may not be displayed to the recipient. Max length 80.
        amount:
          type: number
          description: >-
            Explicit decimal point and trailing zeros are truncated.
            Example:1234.56
        counterpartyId:
          type: integer
          description: counterparty ID of the recipient
        description:
          type: string
          description: >-
            The first 10 character of the description will be used as Company
            Entry Description in the Nacha file. (For ACH endpoints). Originator
            to receiver message (For wire endpoints)
        effectiveEntryDate:
          type: date
          description: >-
            Effective entry date for the transaction in the Nacha file. Needs to
            be an eligible date for Effective Entry Date if present.
        externalId:
          type: string
          description: Optional external ID to track the transaction
        internalNote:
          type: string
          description: Transaction Internal Note
        prenote:
          type: boolean
          description: Amount must be 0 if true
        secCode:
          type: string
          enum:
            - CCD
            - CIE
            - PPD
            - TEL
            - WEB
            - IAT
        service:
          type: string
          description: >-
            SAME_DAY to request a Same Day ACH. STANDARD to request Next Day
            ACH. The final process date depends on the Financial Institution’s
            processing window.
          enum:
            - STANDARD
            - SAME_DAY
      additionalProperties: false
    PerformWireInternalTransactionRequest:
      type: object
      required:
        - amount
        - description
        - recipientAccountNumber
        - senderAccountNumber
      properties:
        amount:
          type: number
          format: double
          description: >-
            Explicit decimal point and trailing zeros are truncated.
            Example:1234.56.
        description:
          type: string
          description: >-
            The first 10 character of the description will be used as Company
            Entry Description in the Nacha file. (For ACH endpoints). Originator
            to receiver message (For wire endpoints)
        externalId:
          type: string
          description: External reference ID
        internalNote:
          type: string
          description: Transaction Internal Note
        recipientAccountNumber:
          type: string
          description: Recipient account number
        senderAccountNumber:
          type: string
          description: Sender account number
      additionalProperties: false
    SubmittedByRequest:
      type: object
      properties:
        contactPersonEmail:
          type: string
          nullable: true
        contactPersonFirstName:
          type: string
          nullable: true
        contactPersonLastName:
          type: string
          nullable: true
        contactPersonPhone:
          type: string
          nullable: true
      additionalProperties: false
    UpdateUpdatablePropertiesOfAnAccountRequest:
      type: object
      properties:
        accountName:
          type: string
          nullable: true
        canAcceptSweep:
          type: boolean
        fundingAccountNumber:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
        sweepAccountNumber:
          type: string
          nullable: true
      additionalProperties: false
    WireRequest:
      type: object
      required:
        - address
        - beneficiaryAccountNumber
        - beneficiaryFIAddress
        - beneficiaryFIIdType
        - beneficiaryFIName
        - receiverRoutingNumber
        - type
      properties:
        address:
          $ref: '#/components/schemas/AddressRequest'
        beneficiaryAccountNumber:
          type: string
          description: Account number of the counterparty as beneficiary
        beneficiaryFIAddress:
          $ref: '#/components/schemas/AddressRequest'
        beneficiaryFIIdType:
          type: string
          description: Type of identifier for the beneficiary's financial institution
          enum:
            - ABA
            - BIC
        beneficiaryFIName:
          type: string
          description: Name of the beneficiary's financial institution
        beneficiaryIdNumber:
          type: string
          description: Beneficiary financial institution's identifier
        intermediaryFIAddress:
          $ref: '#/components/schemas/AddressRequest'
        intermediaryFIIdNumber:
          type: string
          description: Intermediary financial institution ID number
        intermediaryFIIdType:
          type: string
          description: Type of identifier for the intermediary financial institution
          enum:
            - ABA
            - BIC
        intermediaryFIName:
          type: string
          description: Name of the intermediary financial institution
        receiverRoutingNumber:
          type: string
          description: Receiver financial institution's routing number
        receiverShortName:
          type: string
          description: Receiver financial institution's short name
        type:
          type: string
          description: Type of wire transaction
          enum:
            - DOMESTIC
            - INTERNATIONAL
      additionalProperties: false
tags:
  - name: Business
    description: >
      APIs for managing businesses within the Theropay Banking-as-a-Service
      (BaaS) platform. 

      These endpoints allow you to create and retrieve business entities, manage
      accounts, 

      perform identity verification, and handle counterparties. Designed for
      seamless 

      integration, the Business APIs enable secure and efficient operations for
      merchants and customers.
  - name: Accounts
    description: >
      APIs for managing accounts within the Theropay Banking-as-a-Service (BaaS)
      platform. 

      These endpoints allow you to create new accounts, retrieve account
      details, and check 

      account balances. Designed to help merchants and customers manage their
      funds easily 

      and securely.
  - name: Transactions
    description: >
      APIs for performing financial transactions within the Theropay BaaS
      platform. 

      These endpoints include ACH pull and push operations, as well as internal
      transfers 

      between accounts. They enable secure movement of funds and make
      transaction handling 

      simple for both merchants and customers.
