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.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/merchants:
    post:
      operationId: Create merchant
      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'
      security:
        - account-secret: []
      summary: ''
      tags:
        - Merchants
  /v1/merchants/{merchant_id}:
    get:
      operationId: Get merchant
      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'
      security:
        - account-secret: []
      summary: ''
      tags:
        - Merchants
    patch:
      operationId: Update merchant
      parameters:
        - name: merchant_id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MerchantDto'
      responses:
        '200':
          description: Update merchant lead data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMerchantResponseDto'
      security:
        - account-secret: []
      summary: ''
      tags:
        - Merchants
  /v1/onboarding_links:
    post:
      description: >-
        Creates a new onboarding link for a merchant. Important: Creating a new
        link will automatically expire all previous onboarding links for the
        same merchant.
      operationId: Create onboarding link
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOnboardingLinkRequestDto'
      responses:
        '201':
          description: >-
            Create an onboarding link for a merchant. Note: Creating a new link
            will expire all previous onboarding links for the same merchant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOnboardingLinkResponseDto'
      security:
        - account-secret: []
      summary: Create an onboarding link for a merchant
      tags:
        - Onboarding Links
  /v1/webhooks:
    post:
      operationId: Create webhook
      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'
      security:
        - account-secret: []
      summary: ''
      tags:
        - Webhooks
    get:
      operationId: Get webhook
      parameters: []
      responses:
        '200':
          description: Get webhooks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WebhookResponseDto'
      security:
        - account-secret: []
      summary: ''
      tags:
        - Webhooks
  /v1/webhooks/{webhook_id}:
    delete:
      operationId: Delete webhook
      parameters:
        - name: webhook_id
          required: true
          in: path
          schema:
            type: string
      responses:
        '204':
          description: Delete webhook
      security:
        - account-secret: []
      summary: ''
      tags:
        - Webhooks
  /v1/statements/{merchantId}:
    get:
      description: >-
        Retrieve a list of available monthly statements for the authenticated
        merchant
      operationId: Statements Get
      parameters:
        - name: merchantId
          required: true
          in: path
          description: The unique identifier of the merchant
          schema:
            example: merchant_2x4y6z8a0b1c2d3e4f5g6h7j8k
            type: string
      responses:
        '200':
          description: List of statements for the merchant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatementsListResponseDto'
        '400':
          description: Merchant not approved - no MID available
        '404':
          description: Merchant not found or no statements available
        '500':
          description: Internal server error while fetching statements
      security:
        - account-secret: []
      summary: Get merchant statements
      tags:
        - Statements
  /v1/statements/{merchantId}/download/{statementId}:
    get:
      description: Download a specific monthly statement PDF with ISV branding applied
      operationId: Statements Download
      parameters:
        - name: merchantId
          required: true
          in: path
          description: The unique identifier of the merchant
          schema:
            example: merchant_2x4y6z8a0b1c2d3e4f5g6h7j8k
            type: string
        - name: statementId
          required: true
          in: path
          description: The unique identifier of the statement to download
          schema:
            example: '859963'
            type: string
      responses:
        '200':
          description: PDF statement file successfully downloaded
        '400':
          description: Merchant not approved - no MID available
        '404':
          description: Statement not found or merchant not found
        '500':
          description: Internal server error while downloading the statement
      security:
        - account-secret: []
      summary: Download a statement PDF
      tags:
        - Statements
  /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: preq_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: preq_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/refunds:
    post:
      tags:
        - Refunds
      description: Create a Refund
      operationId: Create Refund
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundPaymentBody'
        required: true
      responses:
        '200':
          description: Refund created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
        '400':
          description: Bad request response - validation error
          content:
            '*/*':
              schema:
                type: string
                example:
                  status: 400
                  error: VALIDATION_EXCEPTION
                  message:
                    - charge_id must not be blank
                  request_id: d6da6dc6-cc76-4534-95fc-dccc842375d3
  /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: cust_02c7t70ef3ig396idugupsr99j
      responses:
        '200':
          description: Payment methods retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $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: cust_02c7t70ef3ig396idugupsr99j
      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
        '422':
          description: Payment method already exists
          content:
            '*/*':
              schema:
                type: string
                example:
                  status: 422
                  error: ENTITY_CREATE_EXCEPTION
                  message: Payment method already exists
                  request_id: 9bccf90d-38a3-4831-96f5-8a1e610252aa
      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: preq_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: ch_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/refunds/{refund_id}:
    get:
      tags:
        - Refunds
      description: Retrieve a Refund by its ID
      operationId: Get Refund
      parameters:
        - name: refund_id
          in: path
          description: Unique identifier for the refund
          required: true
          schema:
            type: String
            example: re_09jb6y6791fg2bt0drtfvajtnl
      responses:
        '200':
          description: Refund retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refund'
        '404':
          description: Refund not found
          content:
            '*/*':
              schema:
                type: string
                example:
                  status: 404
                  error: NOT_FOUND
                  message: Refund not found
                  request_id: d6da6dc6-cc76-4534-95fc-dccc842375d3
  /v1/merchants/{merchant_id}/customers/{customer_id}/payment_methods/{card_fingerprint}:
    get:
      tags:
        - Merchants
      description: Retrieve payment method for a given fingerprint
      operationId: Get Customer Payment Method By Fingerprint
      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: cust_02c7t70ef3ig396idugupsr99j
        - name: card_fingerprint
          in: path
          description: Unique identifier for the card fingerprint
          required: true
          schema:
            type: string
            example: 8411d8248f976bcr15fba0f495476i4098d06aa9318fda8f0e700a4ad83b7837
      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: []
  /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: cust_02c7t70ef3ig396idugupsr99j
        - 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:
    TwoTieredCapabilitiesDto:
      type: object
      properties: {}
    PassThroughIcCapabilitiesDto:
      type: object
      properties: {}
    FlatRateCapabilitiesDto:
      type: object
      properties: {}
    TieredCapabilitiesDto:
      type: object
      properties: {}
    CashDiscountCapabilitiesDto:
      type: object
      properties: {}
    AchCapabilitiesDto:
      type: object
      properties: {}
    DefaultCapabilityOptionsDto:
      type: object
      properties:
        two_tiered:
          $ref: '#/components/schemas/TwoTieredCapabilitiesDto'
        pass_through_ic:
          $ref: '#/components/schemas/PassThroughIcCapabilitiesDto'
        flat_rate:
          $ref: '#/components/schemas/FlatRateCapabilitiesDto'
        tiered:
          $ref: '#/components/schemas/TieredCapabilitiesDto'
        cash_discount:
          $ref: '#/components/schemas/CashDiscountCapabilitiesDto'
        ach:
          $ref: '#/components/schemas/AchCapabilitiesDto'
    DefaultCapabilitiesParams:
      type: object
      properties:
        types:
          type: array
          description: Array of capability types
          example:
            - two_tiered
            - ach
          items:
            type: string
            enum:
              - two_tiered
              - pass_through_ic
              - flat_rate
              - tiered
              - cash_discount
              - ach
        options:
          description: Capability options for each type
          example:
            two_tiered:
              vmd_cp_rate_percent: '2.00'
              vmd_cp_fee_fixed: '0.10'
              vmd_cnp_rate_percent: '2.50'
              vmd_cnp_fee_fixed: '0.15'
              amex_cp_rate_percent: '3.10'
              amex_cp_fee_fixed: '0.25'
              amex_cnp_rate_percent: '3.50'
              amex_cnp_fee_fixed: '0.30'
            ach:
              txn_fee_percent: '1.50'
              txn_fee_fixed: '0.25'
          allOf:
            - $ref: '#/components/schemas/DefaultCapabilityOptionsDto'
    TwoTieredCapabilitiesResponseDto:
      type: object
      properties:
        vmd_cp_rate_percent:
          type: string
          example: '2.00'
          description: Visa/Mastercard card present rate percent
        vmd_cp_fee_fixed:
          type: string
          example: '0.10'
          description: Visa/Mastercard card present fee fixed
        vmd_cnp_rate_percent:
          type: string
          example: '2.50'
          description: Visa/Mastercard card not present rate percent
        vmd_cnp_fee_fixed:
          type: string
          example: '0.15'
          description: Visa/Mastercard card not present fee fixed
        amex_cp_rate_percent:
          type: string
          example: '3.10'
          description: Amex card present rate percent
        amex_cp_fee_fixed:
          type: string
          example: '0.25'
          description: Amex card present fee fixed
        amex_cnp_rate_percent:
          type: string
          example: '3.50'
          description: Amex card not present rate percent
        amex_cnp_fee_fixed:
          type: string
          example: '0.30'
          description: Amex card not present fee fixed
      required:
        - vmd_cp_rate_percent
        - vmd_cp_fee_fixed
        - vmd_cnp_rate_percent
        - vmd_cnp_fee_fixed
        - amex_cp_rate_percent
        - amex_cp_fee_fixed
        - amex_cnp_rate_percent
        - amex_cnp_fee_fixed
    PassThroughIcCapabilitiesResponseDto:
      type: object
      properties:
        processor_markup_percent:
          type: string
          example: '0.10'
          description: Processor markup percent
        transaction_fee_fixed:
          type: string
          example: '0.10'
          description: Transaction fee fixed
        vmd_credit_discount_percent:
          type: string
          description: Visa/Mastercard credit discount percent
        vmd_credit_fee_fixed:
          type: string
          description: Visa/Mastercard credit fee fixed
        vmd_debit_discount_percent:
          type: string
          description: Visa/Mastercard debit discount percent
        vmd_debit_fee_fixed:
          type: string
          description: Visa/Mastercard debit fee fixed
        amex_discount_percent:
          type: string
          description: Amex discount percent
        amex_fee_fixed:
          type: string
          description: Amex fee fixed
      required:
        - processor_markup_percent
        - transaction_fee_fixed
        - vmd_credit_discount_percent
        - vmd_credit_fee_fixed
        - vmd_debit_discount_percent
        - vmd_debit_fee_fixed
        - amex_discount_percent
        - amex_fee_fixed
    FlatRateCapabilitiesResponseDto:
      type: object
      properties:
        rate_percent:
          type: string
          example: '2.90'
          description: Flat rate percent
        fee_fixed:
          type: string
          example: '0.30'
          description: Fee fixed
        vmd_credit_rate_percent:
          type: string
          description: Visa/Mastercard credit rate percent
        vmd_credit_fee_fixed:
          type: string
          description: Visa/Mastercard credit fee fixed
        vmd_debit_rate_percent:
          type: string
          description: Visa/Mastercard debit rate percent
        vmd_debit_fee_fixed:
          type: string
          description: Visa/Mastercard debit fee fixed
        amex_rate_percent:
          type: string
          description: Amex rate percent
        amex_fee_fixed:
          type: string
          description: Amex fee fixed
      required:
        - rate_percent
        - fee_fixed
        - vmd_credit_rate_percent
        - vmd_credit_fee_fixed
        - vmd_debit_rate_percent
        - vmd_debit_fee_fixed
        - amex_rate_percent
        - amex_fee_fixed
    TieredCapabilitiesResponseDto:
      type: object
      properties:
        vmd_qual_credit_rate_percent:
          type: string
          example: '1.79'
          description: Visa/Mastercard qualified credit rate percent
        vmd_midq_credit_rate_percent:
          type: string
          example: '2.19'
          description: Visa/Mastercard mid-qualified credit rate percent
        vmd_midq_credit_fee_fixed:
          type: string
          example: '0.15'
          description: Visa/Mastercard mid-qualified credit fee fixed
        vmd_nonq_credit_rate_percent:
          type: string
          example: '3.25'
          description: Visa/Mastercard non-qualified credit rate percent
        vmd_nonq_credit_fee_fixed:
          type: string
          example: '0.20'
          description: Visa/Mastercard non-qualified credit fee fixed
        vmd_qual_debit_rate_percent:
          type: string
          example: '1.50'
          description: Visa/Mastercard qualified debit rate percent
        vmd_midq_debit_rate_percent:
          type: string
          example: '1.90'
          description: Visa/Mastercard mid-qualified debit rate percent
        vmd_midq_debit_fee_fixed:
          type: string
          example: '0.12'
          description: Visa/Mastercard mid-qualified debit fee fixed
        vmd_nonq_debit_rate_percent:
          type: string
          example: '2.95'
          description: Visa/Mastercard non-qualified debit rate percent
        vmd_nonq_debit_fee_fixed:
          type: string
          example: '0.18'
          description: Visa/Mastercard non-qualified debit fee fixed
        amex_qual_credit_rate_percent:
          type: string
          example: '2.89'
          description: Amex qualified credit rate percent
        amex_midq_credit_rate_percent:
          type: string
          example: '3.29'
          description: Amex mid-qualified credit rate percent
        amex_midq_credit_fee_fixed:
          type: string
          example: '0.25'
          description: Amex mid-qualified credit fee fixed
        amex_nonq_credit_rate_percent:
          type: string
          example: '4.35'
          description: Amex non-qualified credit rate percent
        amex_nonq_credit_fee_fixed:
          type: string
          example: '0.30'
          description: Amex non-qualified credit fee fixed
        qualified_rate_percent:
          type: string
          example: '1.79'
          description: Qualified rate percent (legacy)
        qualified_fee_fixed:
          type: string
          example: '0.10'
          description: Qualified fee fixed (legacy)
        mid_qualified_rate_percent:
          type: string
          example: '2.19'
          description: Mid-qualified rate percent (legacy)
        mid_qualified_fee_fixed:
          type: string
          example: '0.15'
          description: Mid-qualified fee fixed (legacy)
        non_qualified_rate_percent:
          type: string
          example: '3.25'
          description: Non-qualified rate percent (legacy)
        non_qualified_fee_fixed:
          type: string
          example: '0.20'
          description: Non-qualified fee fixed (legacy)
      required:
        - vmd_qual_credit_rate_percent
        - vmd_midq_credit_rate_percent
        - vmd_midq_credit_fee_fixed
        - vmd_nonq_credit_rate_percent
        - vmd_nonq_credit_fee_fixed
        - vmd_qual_debit_rate_percent
        - vmd_midq_debit_rate_percent
        - vmd_midq_debit_fee_fixed
        - vmd_nonq_debit_rate_percent
        - vmd_nonq_debit_fee_fixed
        - amex_qual_credit_rate_percent
        - amex_midq_credit_rate_percent
        - amex_midq_credit_fee_fixed
        - amex_nonq_credit_rate_percent
        - amex_nonq_credit_fee_fixed
        - qualified_rate_percent
        - qualified_fee_fixed
        - mid_qualified_rate_percent
        - mid_qualified_fee_fixed
        - non_qualified_rate_percent
        - non_qualified_fee_fixed
    CashDiscountCapabilitiesResponseDto:
      type: object
      properties:
        enabled:
          type: boolean
          example: true
          description: Is cash discount enabled
      required:
        - enabled
    AchPaymentsCapabilitiesResponseDto:
      type: object
      properties:
        txn_fee_fixed:
          type: string
          example: '0.25'
          description: ACH transaction fixed fee
        txn_fee_percent:
          type: string
          example: '0.75'
          description: ACH transaction percentage fee
        return_fee_fixed:
          type: string
          example: '5.00'
          description: ACH return fixed fee
        chargeback_fee_fixed:
          type: string
          example: '10.00'
          description: ACH chargeback fixed fee
      required:
        - txn_fee_fixed
        - txn_fee_percent
        - return_fee_fixed
        - chargeback_fee_fixed
    DefaultCapabilityOptionsResponseDto:
      type: object
      properties:
        two_tiered:
          description: Two-tiered payment capabilities
          allOf:
            - $ref: '#/components/schemas/TwoTieredCapabilitiesResponseDto'
        pass_through_ic:
          description: Pass-through IC payment capabilities
          allOf:
            - $ref: '#/components/schemas/PassThroughIcCapabilitiesResponseDto'
        flat_rate:
          description: Flat rate payment capabilities
          allOf:
            - $ref: '#/components/schemas/FlatRateCapabilitiesResponseDto'
        tiered:
          description: Tiered payment capabilities
          allOf:
            - $ref: '#/components/schemas/TieredCapabilitiesResponseDto'
        cash_discount:
          description: Cash discount payment capabilities
          allOf:
            - $ref: '#/components/schemas/CashDiscountCapabilitiesResponseDto'
        ach:
          description: ACH payment capabilities
          allOf:
            - $ref: '#/components/schemas/AchPaymentsCapabilitiesResponseDto'
      required:
        - two_tiered
        - pass_through_ic
        - flat_rate
        - tiered
        - cash_discount
        - ach
    DefaultCapabilitiesResponseDto:
      type: object
      properties:
        types:
          type: array
          description: Capability types
          example:
            - two_tiered
            - ach
          items:
            type: string
            enum:
              - two_tiered
              - pass_through_ic
              - flat_rate
              - tiered
              - cash_discount
              - ach
        options:
          description: Capability options
          allOf:
            - $ref: '#/components/schemas/DefaultCapabilityOptionsResponseDto'
      required:
        - types
        - options
    OnboardingStatus:
      type: string
      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
    MerchantDto:
      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:
          allOf:
            - $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'
        bank_account_results:
          type: string
        capabilities:
          description: Capabilities settings
          allOf:
            - $ref: '#/components/schemas/DefaultCapabilitiesParams'
      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
    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
    MerchantDefaults:
      type: object
      properties:
        displayName:
          type: string
          example: My Store
          description: Display name for the merchant
        logo:
          type: string
          example: https://example.com/logo.png
          description: Logo URL for the merchant
        primaryColor:
          type: string
          example: '#FF5733'
          description: Primary color for merchant branding
        secondaryColor:
          type: string
          example: '#FF5733'
          description: Secondary color for merchant branding
        redirectUrl:
          type: string
          example: https://merchant-site.com/thank-you
          description: URL to redirect after completing a transaction
        customDomain:
          type: string
          example: https://apply.example.com
          description: Custom domain for merchant onboarding
      required:
        - displayName
        - logo
        - primaryColor
        - secondaryColor
    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
          description: Onboarding application ID
        lead_onboarding_status:
          description: Merchant onboarding status
          allOf:
            - $ref: '#/components/schemas/OnboardingStatus'
        merchant:
          description: Merchant onboarding information
          allOf:
            - $ref: '#/components/schemas/MerchantDto'
        payment:
          description: Merchant payment information
          allOf:
            - $ref: '#/components/schemas/MerchantPayment'
        defaults:
          description: Merchant default settings
          allOf:
            - $ref: '#/components/schemas/MerchantDefaults'
        default_capabilities:
          description: Account default capabilities
          allOf:
            - $ref: '#/components/schemas/DefaultCapabilitiesResponseDto'
      required:
        - id
        - phone
        - automatic_payouts
        - deactivated
        - created_at
        - lead_id
        - lead_onboarding_status
        - merchant
        - payment
        - defaults
        - default_capabilities
    CreateMerchantRequestDto:
      type: object
      properties:
        phone:
          type: string
        agent:
          type: number
        merchant:
          $ref: '#/components/schemas/MerchantDto'
      required:
        - phone
    OnboardingLinkType:
      type: string
      enum:
        - account_onboarding
    CreateOnboardingLinkRequestDto:
      type: object
      properties:
        merchant_id:
          type: string
        return_url:
          type: string
          description: URL to redirect after onboarding completion
          example: >-
            https://dashboard.example.com?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        type:
          default: account_onboarding
          allOf:
            - $ref: '#/components/schemas/OnboardingLinkType'
      required:
        - merchant_id
        - type
    CreateOnboardingLinkResponseDto:
      type: object
      properties:
        url:
          type: string
          description: The URL of the onboarding link with token
          example: >-
            https://dashboard.example.com?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        id:
          type: string
          description: The ID of the onboarding link
        expires_at:
          type: string
          description: The expiration date of the onboarding link
        merchant_id:
          type: string
          description: The merchant ID associated with this onboarding link
      required:
        - url
        - id
        - expires_at
        - merchant_id
    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
    WebhookResponseDto:
      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
            - REFUND
        id:
          type: string
          description: Unique identifier for the payment request
          example: preq_01h455vb4pex5vsknk084sn02q
        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
        - debit
        - isTaxValid
        - merchant_id
        - signature_required
        - tax
        - terminal_id
        - tip
      type: object
      properties:
        terminal_id:
          type: string
          description: Unique identifier for the terminal
          example: 234h2ev0i4726hij9o00
        signature_required:
          type: boolean
          description: Flag to indicate if a signature is required
          example: false
        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
        debit:
          type: boolean
          description: Flag to indicate if terminal should allow debit cards
          example: true
        isTaxValid:
          type: boolean
    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
        - isTaxValid
        - 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
        isTaxValid:
          type: boolean
        taxPercent:
          type: string
    Refund:
      required:
        - amount
        - charge_id
        - created_at
        - id
        - merchant_id
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the refund
          example: re_01j8emz8chfxbb2bqmtref8ch7
        charge_id:
          type: string
          description: Unique identifier for the charge
          example: ch_01j8emz8chfxbb2bqmtref8ch7
        merchant_id:
          type: string
          description: Unique identifier for the merchant
          example: merchant_02c7h71rf3eg396idngupsr66t
        amount:
          type: integer
          description: Amount of the refund
          format: int32
          example: 100
        notes:
          type: string
          description: Some notes
          example: My refund
        created_at:
          type: integer
          description: Timestamp in milliseconds when the refund was created
          format: int32
          example: 1727875117482
    RefundPaymentBody:
      required:
        - amount
        - charge_id
        - merchant_id
      type: object
      properties:
        charge_id:
          type: string
          description: Unique identifier for the charge
          example: ch_01j8emz8chfxbb2bqmtref8ch7
        merchant_id:
          type: string
          description: Unique identifier for the merchant
          example: merchant_02c7h71rf3eg396idngupsr66t
        amount:
          type: integer
          description: Amount of the refund
          format: int32
          example: 100
        notes:
          type: string
          description: Some notes
          example: My refund
    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: cust_02c7t70ef3ig396idugupsr99j
        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
        - created_at
        - customer_id
        - id
        - payment_method
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the created payment method
          example: payment_method_04c7h77rf3ig386ilngopty49z
        customer_id:
          type: string
          description: Unique identifier for the created customer
          example: cust_02c7t70ef3ig396idugupsr99j
        payment_method:
          type: string
          description: Details of the payment method
          enum:
            - CARD
        created_at:
          type: integer
          description: Timestamp when the charge was created
          format: int32
          example: 1727875117482
        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
        masked_number:
          type: string
          description: Masked card number
          example: 400934******1881
        expiration_date:
          type: string
          description: Expiration date of the card
          example: 01/27
      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: ch_01j8emz8chfxbb2bqmtref8ch7
        merchant:
          $ref: '#/components/schemas/Merchant'
        payment_type:
          type: string
          description: Type of payment for the charge
          example: MANUAL
        status:
          type: string
          description: status of the charge
          example: SETTLED
          enum:
            - AUTHORIZED
            - SETTLED
        requested_amount:
          type: integer
          description: Requested amount for the charge
          format: int32
          example: 100
        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
        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
        failure_reason:
          type: string
          description: Reason for the charge failure
          example: Card declined
    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
        - isTaxValid
        - 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
        isTaxValid:
          type: boolean
    InvoicePaymentBody:
      required:
        - amount
        - email_address
        - isTaxValid
        - items
        - merchant_id
        - sendVia
        - 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
        sendVia:
          type: string
          enum:
            - none
            - text
            - email
            - both
        isTaxValid:
          type: boolean
        taxPercent:
          type: string
    CustomerPaymentBody:
      required:
        - amount
        - customer_id
        - isTaxValid
        - merchant_id
        - payment_method_id
        - tax
        - tip
      type: object
      properties:
        customer_id:
          type: string
          description: Unique identifier for the customer
          example: cust_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
        isTaxValid:
          type: boolean
    StatementMetadataDto:
      type: object
      properties:
        statement_id:
          type: string
          example: stmt_2024_01_abc123
          description: Unique identifier for the statement
        merchant_id:
          type: string
          example: merchant_2x4y6z8a0b1c2d3e4f5g6h7j8k
          description: Merchant identifier
        statement_date:
          type: string
          example: '2024-01-31'
          description: Statement date in YYYY-MM-DD format
        period_start:
          type: string
          example: '2024-01-01'
          description: Period start date in YYYY-MM-DD format
        period_end:
          type: string
          example: '2024-01-31'
          description: Period end date in YYYY-MM-DD format
        total_amount:
          type: number
          example: 1250.75
          description: Total amount for the statement period
        currency:
          type: string
          example: USD
          description: Currency code
        status:
          type: string
          example: available
          description: Statement status
          enum:
            - available
            - processing
            - error
        download_url:
          type: string
          example: https://api.taluspay.com/v1/statements/download/stmt_2024_01_abc123
          description: Download URL for the statement
      required:
        - statement_id
        - merchant_id
        - statement_date
        - period_start
        - period_end
        - total_amount
        - currency
        - status
    StatementsListResponseDto:
      type: object
      properties:
        statements:
          description: List of available statements for the merchant
          type: array
          items:
            $ref: '#/components/schemas/StatementMetadataDto'
        total_count:
          type: number
          example: 5
          description: Total number of statements available
        merchant_id:
          type: string
          example: merchant_2x4y6z8a0b1c2d3e4f5g6h7j8k
          description: Merchant identifier
      required:
        - statements
        - total_count
        - merchant_id
