openapi: 3.0.1
info:
  title: Overview
  description: >
    Our Banking as a Service (BaaS) platform is designed to help businesses
    manage money movement with ease. Whether you are paying a vendor or
    requesting funds from a partner, our APIs provide a secure and reliable way
    to handle your financial operations.


    **With these APIs, you can:**

    * **Manage Payees:** Securely save the details of people or businesses you
    work with, including their bank information for ACH, Wire, or Braid
    transfers.

    * **Move Money:** Create and send payment requests quickly by specifying the
    amount and the preferred payment method.

    * **Track Activity:** Search through your transaction history to monitor the
    status of your payments and keep your records up to date.    
  contact:
    name: API Support
    email: support@theropay.io
  version: null
servers:
  - url: https://devapi.theropay.co
    description: Sandbox Server
paths:
  /finance/v1/payee:
    post:
      tags:
        - Business
      summary: Creates a new counter party
      requestBody:
        description: >
          Registers a new **Counterparty** (payee) within the Theropay
          ecosystem. This is a required first step before initiating any
          financial transfers.Request object containing payee details.


          * Allows you to attach payment details for **ACH**, **Wire** network
          via the nested objects.
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/CreateCounterpartyAchRequest'
                - $ref: '#/components/schemas/CreateCounterpartyWireRequest'
          text/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/CreateCounterpartyAchRequest'
                - $ref: '#/components/schemas/CreateCounterpartyWireRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/CreateCounterpartyAchRequest'
      responses:
        '200':
          description: Counterparty created successfully
  /finance/v1/payment_request:
    post:
      tags:
        - Payment
      summary: Send payment request.
      description: >
        This endpoint allows you to create and send a payment request. A payment
        request represents a request for a customer or partner to pay a specific
        amount
      requestBody:
        description: The details of the payment you want to request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequestDto'
          text/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequestDto'
          application/*+json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequestDto'
      responses:
        '200':
          description: OK
  /finance/v1/search_transactions:
    post:
      tags:
        - Transaction
      summary: Get payment details.
      description: >
        This tool lets you search through your payment history to find specific
        transactions


        You can use it to check if a payment went through or to look up the
        details of a past transfer.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchBraidTransactionsRequestDTO'
          text/json:
            schema:
              $ref: '#/components/schemas/SearchBraidTransactionsRequestDTO'
          application/*+json:
            schema:
              $ref: '#/components/schemas/SearchBraidTransactionsRequestDTO'
      responses:
        '200':
          description: OK
components:
  schemas:
    AchRequest:
      required:
        - accountNumber
        - bankAccountType
        - routingNumber
      type: object
      properties:
        accountNumber:
          minLength: 1
          type: string
        address:
          $ref: '#/components/schemas/AddressRequest'
        bankAccountType:
          minLength: 1
          type: string
        bankName:
          type: string
          nullable: true
        gatewayRoutingNumber:
          type: string
          nullable: true
        rdfiNumberQualifier:
          type: string
          nullable: true
        routingNumber:
          minLength: 1
          type: string
      additionalProperties: false
    AddressRequest:
      type: object
      properties:
        city:
          type: string
          nullable: true
        countryCode:
          type: string
          nullable: true
        line1:
          type: string
          nullable: true
        line2:
          type: string
          nullable: true
        postalCode:
          type: string
          nullable: true
        state:
          type: string
          nullable: true
        type:
          type: string
          nullable: true
      additionalProperties: false
    BraidRequest:
      type: object
      properties:
        accountNumber:
          type: string
          nullable: true
      additionalProperties: false
    CancelTransactionRequest:
      type: object
      properties:
        achReturnCode:
          type: string
          nullable: true
        paymentId:
          type: string
          nullable: true
        reason:
          type: string
          nullable: true
      additionalProperties: false
    CreateCounterpartyAchRequest:
      required:
        - email
        - name
        - type
        - phone
      type: object
      properties:
        name:
          minLength: 1
          type: string
        phone:
          type: string
        email:
          type: string
          nullable: true
        businessId:
          type: integer
          format: int32
          nullable: true
        PaymentMethodType:
          type: string
          enum:
            - STANDARD
            - SAME_DAY
        type:
          type: string
          enum:
            - INDIVIDUAL
            - BUSINESS
        productId:
          type: integer
          format: int32
          nullable: true
        dateOfBirth:
          type: string
          format: date
          description: Optional for **BUSINESS** but `required` for **INDIVIDUAL**
        idNumber:
          type: string
          nullable: true
        idType:
          type: string
          nullable: true
        dbaName:
          type: string
          nullable: true
        jurisdictionState:
          type: string
          description: |
            `Optional` for **INDIVIDUAL** but `required` for **BUSINESS**
        jurisdictionCountry:
          type: string
          description: |
            `Required` only for US Jurisdiction country
        individualId:
          type: integer
          format: int32
          nullable: true
        ach:
          $ref: '#/components/schemas/AchRequest'
        braid:
          $ref: '#/components/schemas/BraidRequest'
        wire:
          $ref: '#/components/schemas/WireRequest'
      additionalProperties: false
    CreateCounterpartyWireRequest:
      required:
        - name
        - email
        - type
        - paymentMethodType
        - wire
      type: object
      properties:
        name:
          minLength: 1
          type: string
        phone:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        businessId:
          type: integer
          format: int32
          nullable: true
        PaymentMethodType:
          type: string
          enum:
            - DOMESTIC_WIRE
            - INTERNATIONAL_WIRE
        type:
          type: string
          enum:
            - INDIVIDUAL
            - BUSINESS
        dateOfBirth:
          type: string
          format: date
          description: Optional for **BUSINESS** but `required` for **INDIVIDUAL**
        dbaName:
          type: string
          nullable: true
        jurisdictionState:
          type: string
          description: |
            `Optional` for **INDIVIDUAL** but `required` for **BUSINESS**
        jurisdictionCountry:
          type: string
          description: |
            `Required` only for US Jurisdiction country
        wire:
          $ref: '#/components/schemas/WireRequest'
    CreatePaymentRequestDto:
      required:
        - amount
        - description
        - payeeId
        - paymentMethodType
        - partnerPaymentUniqueId
        - partnerId
      type: object
      properties:
        payeeId:
          type: integer
          format: int32
        merchantAccountNumber:
          maxLength: 100
          type: string
          nullable: true
        amount:
          maximum: 1000000
          minimum: 0.01
          type: number
          format: double
        currency:
          type: string
          nullable: true
          description: Currency code in ISO 4217 format (default:USD)
        paymentMethodType:
          minLength: 1
          type: string
          enum:
            - STANDARD
            - SAME_DAY
            - DOMESTIC_WIRE
            - INTERNATIONAL_WIRE
        description:
          maxLength: 500
          minLength: 1
          type: string
          description: Description of the payment (max 500 chars)
        externalId:
          type: string
          nullable: true
        internalNote:
          type: string
          nullable: true
        partnerId:
          type: integer
          format: int32
          nullable: true
          description: Partner ID assigned to your integration
        merchantId:
          type: integer
          format: int32
          description: Merchant ID under which this payment is initiated
        partnerPaymentUniqueId:
          type: string
          description: Partner payment identifier
      additionalProperties: false
    DomesticWireTransactionRequest:
      type: object
      properties:
        accountNumber:
          type: string
          nullable: true
        amount:
          type: number
          format: double
        counterpartyId:
          type: integer
          format: int32
        description:
          type: string
          nullable: true
        externalId:
          type: string
          nullable: true
        internalNote:
          type: string
          nullable: true
      additionalProperties: false
    InternationalWireTransactionRequest:
      type: object
      properties:
        accountNumber:
          type: string
          nullable: true
        amount:
          type: number
          format: double
        counterpartyId:
          type: integer
          format: int32
        description:
          type: string
          nullable: true
        externalId:
          type: string
          nullable: true
        internalNote:
          type: string
          nullable: true
      additionalProperties: false
    PartnerPaymentListRequestDTO:
      type: object
      properties:
        pageNumber:
          type: integer
          format: int32
        pageSize:
          type: integer
          format: int32
        route:
          type: string
          nullable: true
        sortProperty:
          type: string
          nullable: true
        isDescending:
          type: boolean
        partnerId:
          type: integer
          format: int32
        paymentId:
          type: integer
          format: int32
          nullable: true
        merchantId:
          type: integer
          format: int32
          nullable: true
      additionalProperties: false
    PerformAchPullRequest:
      type: object
      properties:
        accountNumber:
          type: string
          nullable: true
        addenda:
          type: string
          nullable: true
        amount:
          type: number
          format: double
        counterpartyId:
          type: integer
          format: int32
        description:
          type: string
          nullable: true
        internalNote:
          type: string
          nullable: true
        prenote:
          type: boolean
        secCode:
          type: string
          nullable: true
        service:
          type: string
          nullable: true
      additionalProperties: false
    PerformAchPushRequest:
      type: object
      properties:
        secCode:
          type: string
          nullable: true
        accountNumber:
          type: string
          nullable: true
        addenda:
          type: string
          nullable: true
        amount:
          type: number
          format: double
        counterpartyId:
          type: integer
          format: int32
        description:
          type: string
          nullable: true
        externalId:
          type: string
          nullable: true
        internalNote:
          type: string
          nullable: true
        prenote:
          type: boolean
        service:
          type: string
          nullable: true
      additionalProperties: false
    PerformWireInternalTransactionRequest:
      type: object
      properties:
        amount:
          type: number
          format: double
        description:
          type: string
          nullable: true
        externalId:
          type: string
          nullable: true
        internalNote:
          type: string
          nullable: true
        recipientAccountNumber:
          type: string
          nullable: true
        senderAccountNumber:
          type: string
          nullable: true
        idempotencyKey:
          type: string
          nullable: true
      additionalProperties: false
    SearchBraidTransactionsRequestDTO:
      type: object
      properties:
        pageNumber:
          type: integer
          format: int32
        pageSize:
          type: integer
          format: int32
        accountNumber:
          type: string
          nullable: true
        batchId:
          type: string
          nullable: true
        beginDate:
          type: string
          format: date-time
          nullable: true
        counterpartyId:
          type: integer
          format: int32
          nullable: true
        customerId:
          type: integer
          format: int32
          nullable: true
        direction:
          type: string
          nullable: true
        endDate:
          type: string
          format: date-time
          nullable: true
        excludeAch:
          type: boolean
          nullable: true
        excludeWire:
          type: boolean
          nullable: true
        externalId:
          type: string
          nullable: true
        isInbound:
          type: boolean
          nullable: true
        linkedPaymentId:
          type: string
          nullable: true
        loadedFromFile:
          type: string
          nullable: true
        maxAmount:
          type: number
          format: double
          nullable: true
        minAmount:
          type: number
          format: double
          nullable: true
        originalFileName:
          type: string
          nullable: true
        paymentId:
          type: string
          nullable: true
        postDateStart:
          type: string
          format: date-time
          nullable: true
        postDateEnd:
          type: string
          format: date-time
          nullable: true
        processingStatus:
          type: array
          items:
            type: string
          nullable: true
        productId:
          type: integer
          format: int32
          nullable: true
        reconStatuses:
          type: array
          items:
            type: string
          nullable: true
        requesterIpAddress:
          type: string
          nullable: true
        requesterUsername:
          type: string
          nullable: true
        settlementFileName:
          type: string
          nullable: true
        showAchNoc:
          type: boolean
          nullable: true
        transactionStatus:
          type: array
          items:
            type: string
          nullable: true
        transactionType:
          type: array
          items:
            type: string
          nullable: true
        updatedStart:
          type: string
          format: date-time
          nullable: true
        updatedEnd:
          type: string
          format: date-time
          nullable: true
        wireFileHandle:
          type: string
          nullable: true
      additionalProperties: false
    WireRequest:
      required:
        - beneficiaryAccountNumber
        - beneficiaryFIName
        - receiverRoutingNumber
        - type
      type: object
      properties:
        address:
          $ref: '#/components/schemas/AddressRequest'
        beneficiaryAccountNumber:
          minLength: 1
          type: string
        beneficiaryFIAddress:
          $ref: '#/components/schemas/AddressRequest'
        beneficiaryFIIdType:
          type: string
          nullable: true
        beneficiaryFIName:
          minLength: 1
          type: string
        beneficiaryIdNumber:
          type: string
          nullable: true
        intermediaryFIAddress:
          $ref: '#/components/schemas/AddressRequest'
        intermediaryFIIdNumber:
          type: string
          nullable: true
        intermediaryFIIdType:
          type: string
          nullable: true
        intermediaryFIName:
          type: string
          nullable: true
        receiverRoutingNumber:
          minLength: 1
          type: string
        receiverShortName:
          type: string
          nullable: true
        type:
          minLength: 1
          type: string
      additionalProperties: false
  securitySchemes:
    Bearer:
      type: http
      description: JWT Authorization header using the Bearer scheme.
      scheme: bearer
      bearerFormat: JWT
security:
  - Bearer: []
tags:
  - name: Business
    description: >-
      Manage your business partners and counterparties. Use these APIs to
      create  and store information about the people or companies you interact
      with,  including their bank details and identity verification.
  - name: Payment
    description: >-
      Initiate and handle money movement. This section allows you to create  new
      payment requests, set the transaction amount, and choose the  best payment
      method for your needs.
  - name: Transaction
    description: >-
      Track and monitor your financial activity. These tools allow you to
      search  through your payment history, check the status of specific
      transfers, and  get detailed information about any transaction.
