openapi: 3.1.0
info:
  title: TalusPay API
  description: >-
    The Talus Pay API is organized into two main areas: Merchant Onboarding and
    Payments. The Merchant Onboarding endpoints are designed to facilitate the
    registration, verification, and configuration of new merchants within the
    platform. This includes creating merchant accounts, submitting necessary
    documentation, and managing compliance checks.


    On the other hand, the Payments endpoints focus on transaction processing,
    allowing merchants to accept payments, initiate refunds, and handle
    transaction statuses. This section is structured to manage payment methods,
    securely process card transactions, and retrieve transaction histories,
    ensuring a smooth flow of payment operations for merchants. Together, these
    two areas provide comprehensive support for managing both the setup and
    ongoing financial activities of merchants.


    The TalusPay status page provides real-time updates on the operational
    status of API services, including onboarding and payments, as well as
    historical uptime data. You can check the current service status at [Status
    page](https://status.taluspay.com)
  version: v1
  contact:
    name: TalusPay
    url: https://docs.taluspay-sandbox.com
    email: engineering@taluspay.com
  x-logo:
    url: https://apply.taluspay.com/assets/company-logo.svg
    href: https://taluspay.com
servers:
  - url: https://api.taluspay.com
    description: Production environment onboarding
  - url: https://api.taluspay-sandbox.com
    description: Sandbox environment onboarding
tags: []
paths:
  /v1/onboarding/register_number:
    post:
      operationId: Send OTP Code
      summary: ''
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterNumberRequestDto'
      responses:
        '200':
          description: Send otp code to mobile number.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterNumberResponseDto'
      tags:
        - Onboarding
  /v1/onboarding/verify_number:
    post:
      operationId: Verify number
      summary: ''
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyOtpCodeRequestDto'
      responses:
        '200':
          description: >-
            Verification code with mobile number. If everything works we create
            merchant and return JWT token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JwtToken'
      tags:
        - Onboarding
  /v1/onboarding/application/{application_id}:
    get:
      operationId: Get onboarding application
      summary: ''
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: number
      responses:
        '200':
          description: Get lead
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicLeadDto'
      tags:
        - Onboarding
    put:
      operationId: Update onboarding application
      summary: ''
      parameters:
        - name: application_id
          required: true
          in: path
          schema:
            type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicLeadDto'
      responses:
        '200':
          description: Update application
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicLeadDto'
      tags:
        - Onboarding
  /v1/onboarding/application:
    post:
      operationId: Create onboarding application
      summary: ''
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckDuplicateLeadDto'
      responses:
        '200':
          description: Create application
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateLeadResponseDto'
      tags:
        - Onboarding
  /v1/onboarding/application/{application_id}/signature:
    post:
      operationId: Create onboarding application signature
      summary: ''
      parameters:
        - name: application_id
          required: true
          in: path
          schema:
            type: number
      responses:
        '200':
          description: >-
            Create onboarding application signature, which is required to sign
            in web by first owner
      tags:
        - Onboarding
  /v1/onboarding/application/{application_id}/signed:
    get:
      operationId: Application onboarding signed status
      summary: ''
      deprecated: true
      parameters:
        - name: application_id
          required: true
          in: path
          schema:
            type: number
      responses:
        '200':
          description: Check if application was signed by anyone - temporary endpoint
      tags:
        - Onboarding
  /v1/onboarding/status:
    get:
      operationId: Get onboarding application status
      summary: ''
      parameters: []
      responses:
        '200':
          description: Get merchant object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMerchantResponseDto'
      tags:
        - Onboarding
      security:
        - account-merchant-session-token: []
  /v1/merchants:
    post:
      operationId: Create merchant
      summary: ''
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMerchantRequestDto'
      responses:
        '201':
          description: >-
            Create merchant, it merchant exists for given phone number it will
            return the same merchant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMerchantResponseDto'
      tags:
        - Merchants
      security:
        - account-secret: []
  /v1/merchants/{merchant_id}/session-token:
    post:
      operationId: Create merchant session token
      summary: ''
      parameters:
        - name: merchant_id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Create merchant session token to enable onboarding calls
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JwtToken'
      tags:
        - Merchants
      security:
        - account-secret: []
  /v1/merchants/{merchant_id}:
    get:
      operationId: Get merchant
      summary: ''
      parameters:
        - name: merchant_id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Get merchant object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMerchantResponseDto'
      tags:
        - Merchants
      security:
        - account-secret: []
  /v1/webhooks:
    post:
      operationId: Create webhook
      summary: ''
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterWebhookRequestDto'
      responses:
        '200':
          description: Create webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterWebhookResponseDto'
      tags:
        - Webhooks
      security:
        - account-secret: []
  /v1/webhooks/{webhook_id}:
    delete:
      operationId: Delete webhook
      summary: ''
      parameters:
        - name: webhook_id
          required: true
          in: path
          schema:
            type: string
      responses:
        '204':
          description: Delete webhook
      tags:
        - Webhooks
      security:
        - account-secret: []
  /v1/terminal:
    post:
      tags:
        - Payments
      description: Create a terminal payment
      operationId: Create Terminal Payment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TerminalPaymentBody'
        required: true
      responses:
        '200':
          description: Invoice payment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequest'
              examples:
                Terminal Payment:
                  description: Terminal Payment
                  value:
                    payment_type: TERMINAL
                    id: terminal_01h455vb4pex5vsknk084sn02q
                    email_address: test@test.ai
                    phone_number: '1234567890'
                    amount: 100
                    tip: 20
                    tax: 14340
                    status: CREATED
        '400':
          description: Bad request response - validation error
          content:
            '*/*':
              schema:
                type: string
                example:
                  status: 400
                  error: VALIDATION_EXCEPTION
                  message:
                    - merchant_id must not be blank
                  request_id: d6da6dc6-cc76-4534-95fc-dccc842375d3
        '500':
          description: An issue occurred with creating payments in upstream servers
          content:
            '*/*':
              schema:
                type: string
                example:
                  status: 500
                  error: INTERNAL_SERVER_ERROR
                  message: >-
                    An upstream server encountered an error. Please reach out to
                    us with the given request ID, and we'll help you out
                  request_id: 0ce46ced-b6bb-4be2-8db8-4ee16b306f97
  /v1/scan_to_pay:
    post:
      tags:
        - Payments
      description: Create a scan-to-pay payment
      operationId: Create Scan To Pay Payment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScanToPayPaymentBody'
            examples:
              With Items:
                description: With Items
                value:
                  merchant_id: merchant_02c7h71rf3eg396idngupsr66t
                  tip: 20
                  items:
                    - name: Item 1
                      quantity: 1
                      unit_price: 100
                  tax: 14340
              Without Items:
                description: Without Items
                value:
                  merchant_id: merchant_02c7h71rf3eg396idngupsr66t
                  tip: 20
                  tax: 14340
                  amount: 100
        required: true
      responses:
        '200':
          description: Invoice payment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequest'
              examples:
                Scan To Pay Payment:
                  description: Scan To Pay Payment
                  value:
                    payment_type: SCAN_TO_PAY
                    id: scan_to_pay_01h455vb4pex5vsknk084sn02q
                    payment_asset_url: >-
                      https://url.com/invoice/71f34949-eef4-4dcc-a899-6038634760c3
                    email_address: test@test.ai
                    phone_number: '1234567890'
                    amount: 100
                    tip: 20
                    tax: 14340
                    status: CREATED
        '400':
          description: Bad request response - validation error
          content:
            '*/*':
              schema:
                type: string
                example:
                  status: 400
                  error: VALIDATION_EXCEPTION
                  message:
                    - merchant_id must not be blank
                  request_id: d6da6dc6-cc76-4534-95fc-dccc842375d3
        '500':
          description: An issue occurred with creating payments in upstream servers
          content:
            '*/*':
              schema:
                type: string
                example:
                  status: 500
                  error: INTERNAL_SERVER_ERROR
                  message: >-
                    An upstream server encountered an error. Please reach out to
                    us with the given request ID, and we'll help you out
                  request_id: 0ce46ced-b6bb-4be2-8db8-4ee16b306f97
  /v1/merchants/{merchant_id}/customers:
    post:
      tags:
        - Merchants
      description: Create a customer for a given merchant
      operationId: Create Customer
      parameters:
        - name: merchant_id
          in: path
          description: Unique identifier for the merchant
          required: true
          schema:
            type: string
            example: merchant_01j8emz8chfxbb2bqmtref8ch7
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerRequestBody'
        required: true
      responses:
        '200':
          description: Customer created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '404':
          description: Merchant not found
          content:
            '*/*':
              schema:
                type: string
                example:
                  status: 404
                  error: NOT_FOUND
                  message: Merchant not found
                  request_id: d6da6dc6-cc76-4534-95fc-dccc842375d3
      security:
        - account-secret: []
  /v1/merchants/{merchant_id}/customers/{customer_id}/payment_methods:
    get:
      tags:
        - Merchants
      description: Retrieve payment methods for a given customer
      operationId: Get Customer Payment Methods
      parameters:
        - name: merchant_id
          in: path
          description: Unique identifier for the merchant
          required: true
          schema:
            type: string
            example: merchant_01j8emz8chfxbb2bqmtref8ch7
        - name: customer_id
          in: path
          description: Unique identifier for the customer
          required: true
          schema:
            type: string
            example: fxbb2bqmtref8ch7
      responses:
        '200':
          description: Payment methods retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethod'
        '404':
          description: Customer not found
          content:
            '*/*':
              schema:
                type: string
                example:
                  status: 404
                  error: NOT_FOUND
                  message: Customer not found
                  request_id: d6da6dc6-cc76-4534-95fc-dccc842375d3
      security:
        - account-secret: []
    post:
      tags:
        - Merchants
      description: Create a payment method for a given customer
      operationId: Create Customer Payment Method
      parameters:
        - name: merchant_id
          in: path
          description: Unique identifier for the merchant
          required: true
          schema:
            type: string
            example: merchant_01j8emz8chfxbb2bqmtref8ch7
        - name: customer_id
          in: path
          description: Unique identifier for the customer
          required: true
          schema:
            type: string
            example: fxbb2bqmtref8ch7
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentMethodRequestBody'
        required: true
      responses:
        '200':
          description: Payment method created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethod'
        '404':
          description: Customer not found
          content:
            '*/*':
              schema:
                type: string
                example:
                  status: 404
                  error: NOT_FOUND
                  message: Customer not found
                  request_id: d6da6dc6-cc76-4534-95fc-dccc842375d3
      security:
        - account-secret: []
  /v1/manual:
    post:
      tags:
        - Payments
      description: Create a manual payment
      operationId: Create Manual Payment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ManualPaymentBody'
        required: true
      responses:
        '200':
          description: Manual payment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Charge'
        '400':
          description: Bad request response - validation error
          content:
            '*/*':
              schema:
                type: string
                example:
                  status: 400
                  error: VALIDATION_EXCEPTION
                  message:
                    - merchant_id must not be blank
                  request_id: d6da6dc6-cc76-4534-95fc-dccc842375d3
        '500':
          description: An issue occurred with creating payments in upstream servers
          content:
            '*/*':
              schema:
                type: string
                example:
                  status: 500
                  error: INTERNAL_SERVER_ERROR
                  message: >-
                    An upstream server encountered an error. Please reach out to
                    us with the given request ID, and we'll help you out
                  request_id: 0ce46ced-b6bb-4be2-8db8-4ee16b306f97
  /v1/invoice:
    post:
      tags:
        - Payments
      description: Create an invoice payment
      operationId: Create Invoice Payment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InvoicePaymentBody'
            examples:
              With Items:
                description: With Items
                value:
                  merchant_id: merchant_02c7h71rf3eg396idngupsr66t
                  tip: 20
                  items:
                    - name: Item 1
                      quantity: 1
                      unit_price: 100
                  tax: 14340
              Without Items:
                description: Without Items
                value:
                  merchant_id: merchant_02c7h71rf3eg396idngupsr66t
                  tip: 20
                  tax: 14340
                  amount: 100
        required: true
      responses:
        '200':
          description: Invoice payment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequest'
              examples:
                Invoice Payment:
                  description: Invoice Payment
                  value:
                    payment_type: INVOICE
                    id: invoice_01h455vb4pex5vsknk084sn02q
                    payment_asset_url: >-
                      https://url.com/invoice/71f34949-eef4-4dcc-a899-6038634760c3
                    email_address: test@test.ai
                    phone_number: '1234567890'
                    amount: 100
                    tip: 20
                    tax: 14340
                    status: CREATED
        '400':
          description: Bad request response - validation error
          content:
            '*/*':
              schema:
                type: string
                example:
                  status: 400
                  error: VALIDATION_EXCEPTION
                  message:
                    - merchant_id must not be blank
                  request_id: d6da6dc6-cc76-4534-95fc-dccc842375d3
        '500':
          description: An issue occurred with creating payments in upstream servers
          content:
            '*/*':
              schema:
                type: string
                example:
                  status: 500
                  error: INTERNAL_SERVER_ERROR
                  message: >-
                    An upstream server encountered an error. Please reach out to
                    us with the given request ID, and we'll help you out
                  request_id: 0ce46ced-b6bb-4be2-8db8-4ee16b306f97
  /v1/customer_charge:
    post:
      tags:
        - Payments
      description: Create a customer payment
      operationId: Create Customer Payment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerPaymentBody'
        required: true
      responses:
        '200':
          description: Customer payment created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Charge'
              examples:
                Customer Payment:
                  description: Customer Payment
                  value:
                    id: charge_01j8emz8chfxbb2bqmtref8ch7
                    merchant:
                      id: merchant_02c7h71rf3eg396idngupsr66t
                    payment_type: CUSTOMER
                    amount_authorized: 100
                    amount_captured: 100
                    requested_amount: 100
                    tip: 1
                    tax: 10
                    card_last_4: '1234'
                    card_brand: VISA
                    created_at: 1727875117482
                    card_entry_method: MANUAL
                    billing_address:
                      company: Acme Corp
                      phone: '+1234567890'
                      email: example@domain.com
                      firstName: John
                      lastName: Doe
                      addressLine1: 123 Main St
                      addressLine2: Apt 4B
                      city: New York
                      state: NY
                      postalCode: '10001'
                      country: USA
                      fax: '+1234567890'
                    card_expiration_date: 01/27
                    card_type: debit
                    status: PENDING_SETTLEMENT
        '400':
          description: Bad request response - validation error
          content:
            '*/*':
              schema:
                type: string
                example:
                  status: 400
                  error: VALIDATION_EXCEPTION
                  message:
                    - merchant_id must not be blank
                  request_id: d6da6dc6-cc76-4534-95fc-dccc842375d3
        '500':
          description: An issue occurred with creating payments in upstream servers
          content:
            '*/*':
              schema:
                type: string
                example:
                  status: 500
                  error: INTERNAL_SERVER_ERROR
                  message: >-
                    An upstream server encountered an error. Please reach out to
                    us with the given request ID, and we'll help you out
                  request_id: 0ce46ced-b6bb-4be2-8db8-4ee16b306f97
  /v1/charges/{charge_id}:
    get:
      tags:
        - Charges
      description: Retrieve a charge by its ID
      operationId: Get Charge
      parameters:
        - name: charge_id
          in: path
          description: Unique identifier for the charge
          required: true
          schema:
            type: String
            example: charge_09jb6y6791fg2bt0drtfvajtnl
      responses:
        '200':
          description: Charge retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Charge'
        '404':
          description: Charge not found
          content:
            '*/*':
              schema:
                type: string
                example:
                  status: 404
                  error: NOT_FOUND
                  message: Charge not found
                  request_id: d6da6dc6-cc76-4534-95fc-dccc842375d3
  /v1/merchants/{merchant_id}/customers/{customer_id}/payment_methods/{payment_method_id}:
    delete:
      tags:
        - Merchants
      description: Delete a payment method for a given customer
      operationId: Delete Customer Payment Method
      parameters:
        - name: merchant_id
          in: path
          description: Unique identifier for the merchant
          required: true
          schema:
            type: string
            example: merchant_01j8emz8chfxbb2bqmtref8ch7
        - name: customer_id
          in: path
          description: Unique identifier for the customer
          required: true
          schema:
            type: string
            example: fxbb2bqmtref8ch7
        - name: payment_method_id
          in: path
          description: Unique identifier for the payment method
          required: true
          schema:
            type: string
            example: fxbb2bqmtref8ch7
      responses:
        '200':
          description: Payment method deleted successfully
        '404':
          description: Customer or payment method not found
          content:
            '*/*':
              schema:
                type: string
                example:
                  status: 404
                  error: NOT_FOUND
                  message: Customer or payment method not found
                  request_id: d6da6dc6-cc76-4534-95fc-dccc842375d3
      security:
        - account-secret: []
components:
  securitySchemes:
    account-merchant-session-token:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: Current accounts merchant auth session token - using JWT
    account-secret:
      type: http
      scheme: basic
      description: Combination of base64 encode of account_sid:account_secret_key
  schemas:
    RegisterNumberRequestDto:
      type: object
      properties:
        phone:
          type: string
      required:
        - phone
    RegisterNumberResponseDto:
      type: object
      properties:
        message:
          type: string
      required:
        - message
    VerifyOtpCodeRequestDto:
      type: object
      properties:
        phone:
          type: string
        publishable_key:
          type: string
        code:
          type: string
        agent:
          type: number
      required:
        - phone
        - publishable_key
        - code
    JwtToken:
      type: object
      properties:
        id:
          type: string
        token:
          type: string
        phone:
          type: string
        created_at:
          type: string
        publishable_key:
          type: string
      required:
        - id
        - token
        - phone
        - created_at
        - publishable_key
    CreateLeadResponseDto:
      type: object
      properties:
        lead_id:
          type: number
        message:
          type: string
      required:
        - lead_id
        - message
    OnboardingStatus:
      type: string
      description: Merchant onboarding status
      enum:
        - NOT_STARTED
        - IN_PROGRESS
        - COMPLETED
        - APPROVED
        - FAILED
    BankAccount:
      type: object
      properties:
        bank_name:
          type: string
        routing_number:
          type: string
        account_holder_name:
          type: string
        account_number:
          type: string
        account_number_confirm:
          type: string
      required:
        - bank_name
        - routing_number
        - account_holder_name
        - account_number
        - account_number_confirm
    TinType:
      type: string
      enum:
        - EIN
        - SSN
        - ITIN
    Address:
      type: object
      properties:
        address:
          type: string
        city:
          type: string
        state:
          type: string
        zip:
          type: string
      required:
        - address
        - city
        - state
        - zip
    Owner:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        middle_name:
          type: string
        job_title:
          type: string
        ownership_percentage:
          type: string
        email:
          type: string
        date_of_birth:
          type: string
        home_address:
          $ref: '#/components/schemas/Address'
        ssn:
          type: string
      required:
        - first_name
        - last_name
        - job_title
        - ownership_percentage
        - email
        - date_of_birth
        - home_address
        - ssn
    Product:
      type: object
      properties:
        description:
          type: string
        category:
          type: string
        subcategory:
          type: string
        website:
          type: string
      required:
        - description
        - category
        - subcategory
        - website
    MainContactPerson:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
      required:
        - name
        - email
    SalesPercentage:
      type: object
      properties:
        card_swipe_percentage:
          type: string
        moto_percentage:
          type: string
        online_percentage:
          type: string
        keyed_percentage:
          type: string
      required:
        - card_swipe_percentage
        - moto_percentage
        - online_percentage
        - keyed_percentage
    Sales:
      type: object
      properties:
        average_monthly_in_credit_card:
          type: string
        average_ticket_value:
          type: string
        highest_amount_to_date:
          type: string
        sales_percentage:
          $ref: '#/components/schemas/SalesPercentage'
        average_amex_monthly_sales:
          type: string
        average_amex_ticket_value:
          type: string
      required:
        - average_monthly_in_credit_card
        - average_ticket_value
        - highest_amount_to_date
        - sales_percentage
        - average_amex_monthly_sales
        - average_amex_ticket_value
    PublicLeadDto:
      type: object
      properties:
        legal_business_name:
          type: string
        legal_phone:
          type: string
        business_phone:
          type: string
        business_type:
          type: string
        bank_account:
          $ref: '#/components/schemas/BankAccount'
        tin:
          type: string
        tin_type:
          $ref: '#/components/schemas/TinType'
        doing_business_as:
          type: string
        business_established_date:
          type: string
        legal_business_address:
          $ref: '#/components/schemas/Address'
        dba_address:
          $ref: '#/components/schemas/Address'
        owner_one:
          $ref: '#/components/schemas/Owner'
        owner_two:
          $ref: '#/components/schemas/Owner'
        owner_three:
          $ref: '#/components/schemas/Owner'
        owner_four:
          $ref: '#/components/schemas/Owner'
        main_product:
          $ref: '#/components/schemas/Product'
        main_contact_person:
          $ref: '#/components/schemas/MainContactPerson'
        current_sales:
          $ref: '#/components/schemas/Sales'
      required:
        - legal_business_name
        - legal_phone
        - business_type
        - bank_account
        - tin
        - tin_type
        - business_established_date
        - legal_business_address
        - owner_one
        - main_product
        - main_contact_person
        - current_sales
    OwnerLeadDto:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
      required:
        - first_name
        - last_name
        - email
    CheckDuplicateLeadDto:
      type: object
      properties:
        legal_business_name:
          type: string
        legal_phone:
          type: string
        doing_business_as:
          type: string
          description: Doing business as
        dba_address:
          description: Business address
          allOf:
            - $ref: '#/components/schemas/Address'
        owner:
          $ref: '#/components/schemas/OwnerLeadDto'
      required:
        - legal_business_name
        - legal_phone
        - doing_business_as
        - dba_address
        - owner
    MerchantPayment:
      type: object
      properties:
        tokenizer_publishable_key:
          type: string
          example: pub_XXXXXXXXXXXXXX
          description: Public key used for tokenizer
        terminal_id:
          type: string
          example: Cx78a65ada9
          description: Terminal ID
      required:
        - tokenizer_publishable_key
        - terminal_id
    GetMerchantResponseDto:
      type: object
      properties:
        id:
          type: string
          example: merchant_2x4y6z8a0b1c2d3e4f5g6h7j8k
        phone:
          type: string
          example: '12819374192'
        automatic_payouts:
          type: boolean
          description: Merchant payouts status
        deactivated:
          type: boolean
          description: Merchant deactivation flag
        created_at:
          format: date-time
          type: string
        lead_id:
          type: number
          nullable: true
          description: Onboarding application ID
        lead_onboarding_status:
          nullable: true
          $ref: '#/components/schemas/OnboardingStatus'
        merchant:
          nullable: true
          description: Merchant onboarding information
          allOf:
            - $ref: '#/components/schemas/PublicLeadDto'
        payment:
          nullable: true
          description: Merchant payment information
          allOf:
            - $ref: '#/components/schemas/MerchantPayment'
      required:
        - id
        - phone
        - automatic_payouts
        - deactivated
        - created_at
        - lead_id
        - lead_onboarding_status
        - merchant
        - payment
    CreateMerchantRequestDto:
      type: object
      properties:
        phone:
          type: string
        agent:
          type: number
        merchant:
          $ref: '#/components/schemas/PublicLeadDto'
      required:
        - phone
    RegisterWebhookRequestDto:
      type: object
      properties:
        url:
          type: string
        label:
          type: string
        scope:
          type: array
          items:
            type: string
            enum:
              - merchant
              - charge
              - payouts
      required:
        - url
        - label
        - scope
    RegisterWebhookResponseDto:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
        label:
          type: string
        secret:
          type: string
        created_at:
          format: date-time
          type: string
        events:
          type: object
      required:
        - id
        - url
        - label
        - secret
        - created_at
        - events
    PaymentRequest:
      required:
        - amount
        - email_address
        - id
        - payment_asset_url
        - payment_type
        - status
        - tax
        - tip
      type: object
      properties:
        payment_type:
          type: string
          description: Type of payment
          enum:
            - MANUAL
            - INVOICE
            - TERMINAL
            - SCAN_TO_PAY
            - CUSTOMER
        id:
          type: string
          description: Unique identifier for the payment request
        payment_asset_url:
          type: string
          description: URL of the payment asset
        email_address:
          type: string
          description: Email address of the customer
          example: test@test.ai
        phone_number:
          type: string
          description: Phone number of the customer
        amount:
          type: integer
          description: Amount of the payment
          format: int32
        tip:
          type: integer
          description: Tip amount
          format: int32
        tax:
          type: integer
          description: Tax amount
          format: int32
        status:
          type: string
          description: Status of the payment request
    TerminalPaymentBody:
      required:
        - amount
        - merchant_id
        - tax
        - terminal_id
        - tip
      type: object
      properties:
        terminal_id:
          type: string
          description: Unique identifier for the terminal
          example: 234h2ev0i4726hij9o00
        merchant_id:
          type: string
          description: Unique identifier for the merchant
          example: merchant_02c7h71rf3eg396idngupsr66t
        amount:
          type: integer
          description: Amount of the payment
          format: int32
          example: 100
        tip:
          type: integer
          description: Tip amount
          format: int32
          example: 1
        tax:
          type: integer
          description: Tax amount
          format: int32
          example: 10
    ItemBody:
      required:
        - name
        - quantity
        - unit_price
      type: object
      properties:
        name:
          type: string
          description: Name of the item
          example: Door Lockout service
        quantity:
          type: integer
          description: Quantity of the item
          format: int32
          example: 1
        unit_price:
          type: integer
          description: Unit price of the item
          format: int32
          example: 47800
      description: List of items
    ScanToPayPaymentBody:
      required:
        - amount
        - items
        - merchant_id
        - tax
        - taxPercent
        - tip
      type: object
      properties:
        merchant_id:
          type: string
          description: Unique identifier for the merchant
          example: merchant_02c7h71rf3eg396idngupsr66t
        tip:
          type: integer
          description: Tip amount
          format: int32
          example: 1
        items:
          type: array
          description: List of items
          items:
            $ref: '#/components/schemas/ItemBody'
        tax:
          type: integer
          description: Tax amount
          format: int32
          example: 10
        amount:
          type: integer
          description: >-
            Amount of the payment. If items are provided, amount should not be
            specified.
          format: int32
          example: 100
        taxPercent:
          type: string
    Merchant:
      required:
        - id
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the merchant
          example: merchant_02c7h71rf3eg396idngupsr66t
    Customer:
      required:
        - id
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the created customer
          example: customer_02c6h71gf3ea3786iyngbpjr38p
        description:
          type: string
          description: Some description
          example: My customer
    CustomerRequestBody:
      required:
        - description
      type: object
      properties:
        description:
          maxLength: 255
          minLength: 0
          type: string
          description: Description of the customer
          example: Test merchant customer
    PaymentMethod:
      required:
        - card
        - id
        - payment_method
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the created payment method
          example: payment_method_04c7h77rf3ig386ilngopty49z
        payment_method:
          type: string
          description: Details of the payment method
          enum:
            - CARD
        card:
          $ref: '#/components/schemas/PaymentMethodCard'
    PaymentMethodCard:
      type: object
      properties:
        card_type:
          type: string
          description: Details of the card used for the payment method
          example: VISA
        card_fingerprint:
          type: string
          description: Details of the card's fingerprint
          example: 8411d8248f977bce15fba0f495474e4099j15bb9318fda8f0e700a4ad83b7836
        card_funding:
          type: string
          description: Details of the card's funding
          example: debit
      description: Details of the card used for the payment method
    PaymentMethodRequestBody:
      required:
        - description
        - token
      type: object
      properties:
        description:
          maxLength: 255
          minLength: 0
          type: string
          description: Description of the payment method
          example: Test customer
        token:
          type: string
          description: Token for the payment method
          example: fxbb2bqmtref8ch7
    Charge:
      required:
        - amount_authorized
        - amount_captured
        - card_entry_method
        - created_at
        - merchant
        - payment_type
        - requested_amount
        - status
        - tax
        - tip
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the charge
          example: charge_01j8emz8chfxbb2bqmtref8ch7
        merchant:
          $ref: '#/components/schemas/Merchant'
        payment_type:
          type: string
          description: Type of payment for the charge
          example: MANUAL
        amount_authorized:
          type: integer
          description: Amount authorized for the charge
          format: int32
          example: 100
        amount_captured:
          type: integer
          description: Amount captured for the charge
          format: int32
          example: 100
        requested_amount:
          type: integer
          description: Requested amount for the charge
          format: int32
          example: 100
        tip:
          type: integer
          description: Tip amount for the charge
          format: int32
          example: 1
        tax:
          type: integer
          description: Tax amount for the charge
          format: int32
          example: 10
        card_last_4:
          type: string
          description: Last 4 digits of the card used for the charge
          example: '1234'
        card_brand:
          type: string
          description: Brand of the card used for the charge
          example: VISA
        created_at:
          type: integer
          description: Timestamp when the charge was created
          format: int32
          example: 1727875117482
        card_entry_method:
          type: string
          description: Method used for card entry
          example: MANUAL
          enum:
            - SWIPE
            - CHIP
            - MANUAL
        billing_address:
          $ref: '#/components/schemas/PaymentBillingAddress'
        card_expiration_date:
          type: string
          description: Expiration date of the card
          example: 01/27
        card_type:
          type: string
          description: Type of the card
          example: debit
        status:
          type: string
          description: status of the charge
          example: PENDING_SETTLEMENT
    PaymentBillingAddress:
      required:
        - email
        - phone
      type: object
      properties:
        company:
          type: string
          description: Company name associated with the address
          example: Acme Corp
        phone:
          type: string
          description: Phone number associated with the address
          example: '+1234567890'
        email:
          type: string
          description: Email address associated with the address
          example: example@domain.com
        first_name:
          type: string
          description: First name of the person associated with the address
          example: John
        last_name:
          type: string
          description: Last name of the person associated with the address
          example: Doe
        address_line_1:
          type: string
          description: First line of the address
          example: 123 Main St
        address_line_2:
          type: string
          description: Second line of the address
          example: Apt 4B
        city:
          type: string
          description: City of the address
          example: New York
        state:
          type: string
          description: State of the address
          example: NY
        postal_code:
          type: string
          description: Postal code of the address
          example: '10001'
        country:
          type: string
          description: Country of the address
          example: USA
        fax:
          type: string
          description: Fax number associated with the address
          example: '+1234567890'
      description: Billing address details
    ManualPaymentBody:
      required:
        - amount
        - merchant_id
        - tax
        - tip
        - token
      type: object
      properties:
        token:
          type: string
          description: Payment token
          example: 16RgvZ9XBTz4IUEIM0mD31f3808okqN2
        merchant_id:
          type: string
          description: Unique identifier for the merchant
          example: merchant_02c7h71rf3eg396idngupsr66t
        amount:
          type: integer
          description: Payment amount
          format: int32
          example: 100
        tip:
          type: integer
          description: Tip amount
          format: int32
          example: 1
        tax:
          type: integer
          description: Tax amount
          format: int32
          example: 10
    InvoicePaymentBody:
      required:
        - amount
        - email_address
        - items
        - merchant_id
        - sendViaDTO
        - send_email
        - send_sms
        - tax
        - taxPercent
        - tip
      type: object
      properties:
        merchant_id:
          type: string
          description: Unique identifier for the merchant
          example: merchant_02c7h71rf3eg396idngupsr66t
        email_address:
          type: string
          description: Email address of the customer
          example: test@test.com
        send_sms:
          type: boolean
          description: Send invoice to the customer using SMS
          example: true
        send_email:
          type: boolean
          description: Send invoice to the customer using email
          example: true
        phone_number:
          type: string
          description: Phone number of the customer
          example: '4695809533'
        tip:
          type: integer
          description: Tip amount
          format: int32
          example: 20
        items:
          type: array
          description: List of items
          items:
            $ref: '#/components/schemas/ItemBody'
        tax:
          type: integer
          description: Tax amount
          format: int32
          example: 10
        amount:
          type: integer
          description: >-
            Amount of the payment. If items are provided, amount should not be
            specified.
          format: int32
          example: 100
        sendViaDTO:
          type: string
          enum:
            - none
            - text
            - email
            - both
        taxPercent:
          type: string
    CustomerPaymentBody:
      required:
        - amount
        - customer_id
        - merchant_id
        - payment_method_id
        - tax
        - tip
      type: object
      properties:
        customer_id:
          type: string
          description: Unique identifier for the customer
          example: customer_02c7t70ef3ig396idugupsr99j
        merchant_id:
          type: string
          description: Unique identifier for the merchant
          example: merchant_02c7h71rf3eg396idngupsr66t
        payment_method_id:
          type: string
          description: Unique identifier for the payment method
          example: payment_method_04c7h77rf3ig386ilngopty49z
        amount:
          type: integer
          description: Amount of the payment
          format: int32
          example: 100
        tip:
          type: integer
          description: Tip amount
          format: int32
          example: 1
        tax:
          type: integer
          description: Tax amount
          format: int32
          example: 10
