openapi: 3.0.1
info:
  title: Theropay APIs
  description: >-
    Theropay offers a set of powerful APIs that help merchants manage their
    payment processes. These APIs allow you to handle everything from managing
    payees and setting up payout accounts to tracking and initiating payments.
  version: null
servers:
  - url: https://api.theropay.com
    description: Production server
paths:
  /v1/payees:
    post:
      tags:
        - Payee
      summary: Creates a new payee.
      description: "Use this endpoint to create a new payee.  \r\n- Tax ID are `optional` for `individual` payee type.  \r\n- Tax ID are `required` for `business` payee type."
      requestBody:
        description: Payee creation request payload.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePayeeRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/CreatePayeeRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/CreatePayeeRequest'
      responses:
        '201':
          description: Payee created successfully.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/PayeeResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/PayeeResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/PayeeResponse'
        '400':
          description: Invalid request payload.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '500':
          description: Server error while creating payee.
          content:
            text/plain:
              schema: {}
            application/json:
              schema: {}
            text/json:
              schema: {}
  /v1/payees/{id}:
    get:
      tags:
        - Payee
      summary: Retrieves a payee by ID.
      parameters:
        - name: id
          in: path
          description: Unique identifier of the payee.
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Payee retrieved successfully.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/PayeeResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/PayeeResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/PayeeResponse'
        '404':
          description: Payee not found.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: Server error while retrieving payee.
    patch:
      tags:
        - Payee
      summary: Updates an existing payee.
      parameters:
        - name: id
          in: path
          description: Unique identifier of the payee to update.
          schema:
            type: string
      requestBody:
        description: Updated payee details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayeeRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/PayeeRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/PayeeRequest'
      responses:
        '200':
          description: Payee updated successfully.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/PayeeResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/PayeeResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/PayeeResponse'
        '400':
          description: Invalid request payload.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '404':
          description: Payee not found.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: Server error while updating payee.
          content:
            text/plain:
              schema: {}
            application/json:
              schema: {}
            text/json:
              schema: {}
  /v1/payees/list:
    post:
      tags:
        - Payee
      summary: Lists all payees.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayeeRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/PayeeRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/PayeeRequest'
      responses:
        '200':
          description: List of payees retrieved successfully.
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PayeeResponse'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PayeeResponse'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PayeeResponse'
  /v1/payees/{id}/accounts:
    post:
      tags:
        - Payee Accounts
      summary: Add a payout account to payee
      description: Add a payout account to the specified payee (matches user story).
      parameters:
        - name: id
          in: path
          description: Unique identifier of the payee to whom the account will be linked.
          required: true
          schema:
            type: integer
      requestBody:
        description: Payout account details as per user story.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayeeAccountRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/PayeeAccountRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/PayeeAccountRequest'
      responses:
        '201':
          description: PayeeAccountId
          content:
            application/json:
              schema:
                type: object
                properties:
                  PayeeAccountId:
                    type: string
                    example: '1234567890'
        '400':
          description: Invalid request payload. Ensure required fields are provided.
        '404':
          description: The specified payee was not found.
    get:
      tags:
        - Payee Accounts
      summary: List all payout accounts for a payee
      description: >-
        Returns a list of all payout accounts associated with the specified
        payee. Matches user story.
      parameters:
        - name: payeeAccountId
          in: path
          description: Unique identifier of the payee whose accounts are to be retrieved.
          schema:
            type: integer
      responses:
        '200':
          description: Payout accounts retrieved successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PayeeAccountResponse'
        '404':
          description: The specified payee was not found.
  /v1/payees/{id}/accounts/{account_id}:
    get:
      tags:
        - Payee Accounts
      summary: Retrieve specific payout account
      description: >-
        Returns complete details of a specific payout account for the given
        payee.
      parameters:
        - name: payeeAccountId
          in: path
          description: Unique identifier of the payee who owns the payout account.
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Payout account details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayeeAccountResponse'
        '404':
          description: Payee or payout account not found.
    patch:
      tags:
        - Payee Accounts
      summary: Update payout account
      description: Use this endpoint to modify payout account details (matches user story).
      parameters:
        - name: id
          in: path
          description: Unique identifier of the payee who owns the payout account.
          required: true
          schema:
            type: integer
        - name: account_id
          in: path
          description: Unique identifier of the payout account to update.
          required: true
          schema:
            type: string
      requestBody:
        description: Payload containing updated payout account information.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayeeAccountRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/PayeeAccountRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/PayeeAccountRequest'
      responses:
        '200':
          description: Payout account updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayeeAccountResponse'
        '400':
          description: Invalid update request. Check input fields.
        '404':
          description: Payee or payout account not found.
    delete:
      tags:
        - Payee Accounts
      summary: Disable payout account
      description: Disables a payout account (sets active flag to false) as per user story.
      parameters:
        - name: id
          in: path
          description: Unique identifier of the payee who owns the payout account.
          required: true
          schema:
            type: integer
        - name: account_id
          in: path
          description: Unique identifier of the payout account to disable.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Payout account disabled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisableAccountResponse'
        '400':
          description: Invalid request to disable account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: Server error while disabling account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /v1/payouts:
    post:
      tags:
        - Payouts
      summary: Initiates a payout to a payee.
      description: "The payout is processed asynchronously. Use `GET /v1/payouts/{id}` to check its status.  \r\nRequired fields: `PayeeId`, `Amount`, `Currency`.  \r\nOptional field: `Description`.\r\nMerchantId is automatically obtained from the authenticated user."
      requestBody:
        description: Details of the payout to be created.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePayoutRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/CreatePayoutRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/CreatePayoutRequest'
      responses:
        '201':
          description: Payout created successfully.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
        '400':
          description: Invalid request payload. Missing or invalid required fields.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Payee or payout account not found.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    get:
      tags:
        - Payouts
      summary: Retrieves a list of payouts for a specific payee.
      parameters:
        - name: payeeId
          in: query
          description: Payee ID to filter payouts.
          schema:
            type: string
      responses:
        '200':
          description: List of payouts retrieved successfully.
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PayoutResponse'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PayoutResponse'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PayoutResponse'
  /v1/payouts/{PayoutUniqueReference}:
    get:
      tags:
        - Payouts
      summary: Retrieves details of a specific payout by unique reference.
      parameters:
        - name: PayoutUniqueReference
          in: path
          description: Unique identifier of the payout.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Payout retrieved successfully.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
        '404':
          description: Payout not found.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /v1/payouts/{PayoutUniqueReference}/cancel:
    post:
      tags:
        - Payouts
      summary: Requests cancellation of a pending payout.
      description: "Only payouts not yet processed can be cancelled.  \r\nCompleted or failed payouts cannot be cancelled."
      parameters:
        - name: PayoutUniqueReference
          in: path
          description: Unique identifier of the payout to cancel.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Cancellation request accepted.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/CancelPayoutResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/CancelPayoutResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/CancelPayoutResponse'
        '400':
          description: Payout cannot be cancelled due to current status.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Payout not found.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /v1/webhooks:
    post:
      tags:
        - Webhook
      summary: Registers a new webhook to receive Payout.
      requestBody:
        description: Webhook registration details including URL, environment, and events.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
      responses:
        '201':
          description: Webhook created successfully.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/Webhook'
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
            text/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          description: Invalid URL provided.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
    get:
      tags:
        - Webhook
      summary: Retrieves all registered webhooks for the merchant.
      responses:
        '200':
          description: Webhooks retrieved successfully.
          content:
            text/plain:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Webhook'
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Webhook'
            text/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Webhook'
    delete:
      tags:
        - Webhook
      summary: Deletes a registered webhook by its unique ID.
      parameters:
        - name: id
          in: path
          description: The unique identifier of the webhook to delete.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Webhook deleted successfully.
        '404':
          description: Webhook not found with the specified ID.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            text/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    AddressRequest:
      required:
        - addressLine
        - city
        - country
        - postalCode
        - state
      type: object
      properties:
        addressLine:
          maxLength: 200
          minLength: 0
          type: string
        state:
          maxLength: 100
          minLength: 0
          type: string
        city:
          maxLength: 100
          minLength: 0
          type: string
        country:
          maxLength: 100
          minLength: 0
          type: string
        postalCode:
          maxLength: 20
          minLength: 0
          type: string
      additionalProperties: false
    AddressResponseDto:
      type: object
      properties:
        addressLine:
          type: string
          nullable: true
        state:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        postalCode:
          type: string
          nullable: true
      additionalProperties: false
    CancelPayoutResponse:
      type: object
      properties:
        payoutUniqueReference:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
      additionalProperties: false
    CreatePayeeRequest:
      required:
        - address
        - currency
        - EmailAddress
        - name
        - payeeType
      type: object
      properties:
        payeeType:
          minLength: 1
          pattern: (individual|business)
          type: string
          description: 'Payee type: "individual" or "business".'
        name:
          maxLength: 100
          minLength: 0
          type: string
          description: Full legal name of the payee.
        EmailAddress:
          minLength: 1
          type: string
          description: EmailAddress of the payee.
        phoneNumber:
          type: string
          description: >-
            Phone number (optional for individual, required for business
            payees).
          nullable: true
        taxId:
          maxLength: 50
          minLength: 0
          type: string
          description: >-
            Tax identifier (optional for individual, required for business
            payees).
          nullable: true
        idType:
          maxLength: 50
          minLength: 0
          type: string
          description: Type of government-issued ID.
          nullable: true
        address:
          $ref: '#/components/schemas/AddressRequest'
        dateOfBirth:
          type: string(optional)
          format: format-date
      additionalProperties: false
      description: "Request model for creating a new payee.\r\nContains validation attributes and model-level conditional validation."
    CreatePaymentRequest:
      required:
        - amount
        - creditor
        - creditor_Account
        - currency_Code
        - debtor
        - debtor_Account
        - end_To_End_Id
        - ultimate_Debtor
      type: object
      properties:
        amount:
          minLength: 1
          type: string
        business_Unit:
          type: string
          nullable: true
        currency_Code:
          minLength: 1
          type: string
        currency_Of_Transfer:
          type: string
          nullable: true
        end_To_End_Id:
          minLength: 1
          type: string
        local_Instrument:
          type: string
          nullable: true
        purpose_Code:
          type: string
          nullable: true
        remittance_Description:
          type: string
          nullable: true
        requested_Execution_Date:
          type: string
          nullable: true
        creditor:
          $ref: '#/components/schemas/Creditor'
        creditor_Account:
          $ref: '#/components/schemas/CreditorAccountBase'
        debtor:
          $ref: '#/components/schemas/Debtor'
        debtor_Account:
          $ref: '#/components/schemas/DebtorAccount'
        ultimate_Debtor:
          $ref: '#/components/schemas/UltimateDebtor'
      additionalProperties: false
    CreatePayoutRequest:
      required:
        - amount
        - currencyCode
        - payeeId
        - payoutAccountId
      type: object
      properties:
        payeeId:
          minLength: 1
          type: string
        payoutAccountId:
          minLength: 1
          type: string
        amount:
          type: number
        currencyCode:
          minLength: 1
          type: string
        description:
          type: string
          nullable: true
      additionalProperties: false
    CreateWebhookRequest:
      required:
        - url
      type: object
      properties:
        url:
          type: string
          nullable: true
      additionalProperties: false
    Creditor:
      type: object
      properties:
        address_Lines:
          type: string
          nullable: true
        birthdate:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        country_Code:
          type: string
          nullable: true
        country_Of_Birth_Code:
          type: string
          nullable: true
        EmailAddress:
          type: string
          nullable: true
        id_Number:
          type: string
          nullable: true
        id_Type:
          type: string
          nullable: true
        mobile_Number:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        postcode:
          type: string
          nullable: true
        state:
          type: string
          nullable: true
        street_Name:
          type: string
          nullable: true
        type:
          type: string
          nullable: true
      additionalProperties: false
    CreditorAccountBase:
      type: object
      properties:
        country_Code:
          type: string
          nullable: true
      additionalProperties: false
    Debtor:
      type: object
      properties:
        name:
          type: string
          nullable: true
      additionalProperties: false
    DebtorAccount:
      type: object
      properties:
        id:
          type: string
          nullable: true
        scheme_Name:
          type: string
          nullable: true
      additionalProperties: false
    DisableAccountResponse:
      type: object
      properties:
        accountId:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
      additionalProperties: false
    JToken:
      type: array
      items:
        $ref: '#/components/schemas/JToken'
    PayeeAccountRequest:
      type: object
      required:
        - type
        - accountHolderName
      properties:
        type:
          type: string
          enum:
            - BANK_ACCOUNT
            - IBAN
          nullable: true
        accountHolderName:
          type: string
          nullable: true
          description: Required if type is BANK_ACCOUNT
        bankName:
          type: string
          nullable: true
          description: Required if type is BANK_ACCOUNT
        routingNumber:
          type: string
          nullable: true
          description: Required if type is BANK_ACCOUNT
        accountNumber:
          type: string
          nullable: true
          description: Required if type is BANK_ACCOUNT
        bankClearingSystemCode:
          type: string
        branchTransitNumber:
          type: string
          nullable: true
        IBAN:
          type: string
          nullable: true
          description: Required if type is IBAN
        Currency:
          type: string
          nullable: true
        accountType:
          type: string
          enum:
            - CHECKINGS
            - SAVINGS
          description: Required if type is BANK_ACCOUNT
      additionalProperties: false
    PayeeAccountResponse:
      type: object
      properties:
        payeeId:
          type: string
          nullable: true
        payeeAccountId:
          type: string
          nullable: true
        type:
          type: string
          nullable: true
          enum:
            - BANK_ACCOUNT
            - IBAN
        accountHolderName:
          type: string
          nullable: true
        bankName:
          type: string
          nullable: true
        routingNumber:
          type: string
          nullable: true
        accountNumber:
          type: string
          nullable: true
          description: Token - Last 4 Digits (responses return last 4 digits only)
        branchTransitNumber:
          type: string
          nullable: true
        IBAN:
          type: string
          nullable: true
        Currency:
          type: string
          nullable: true
        accountType:
          type: string
          enum:
            - CHECKINGS
            - SAVINGS
        accountTypeId:
          type: integer
        createdOn:
          type: string
          format: date
      additionalProperties: false
    PayeeRequest:
      type: object
      required:
        - currency
        - address
      properties:
        payeeType:
          type: string
          enum:
            - individual
            - business
        name:
          type: string
        EmailAddress:
          type: string
        phoneNumber:
          type: string
        taxId:
          type: >-
            string  (Optional in case of individual and required in case of
            business type)
          format: uuid
        idType:
          type: string
        address:
          $ref: '#/components/schemas/AddressRequest'
        dateOfBirth:
          type: string
          format: date
    PayeeResponse:
      type: object
      properties:
        payeeType:
          type: individual or business
        name:
          type: string
          nullable: true
        EmailAddress:
          type: string
          nullable: true
        phoneNumber:
          type: string
          nullable: true
        taxId:
          type: string
          nullable: true
        idType:
          type: string
          nullable: true
        address:
          $ref: '#/components/schemas/AddressResponseDto'
        dateOfBirth:
          type: string
          format: date
      additionalProperties: false
    PaymentHistoryRequest:
      type: object
      properties:
        pageNumber:
          type: integer
        pageSize:
          type: integer
        route:
          type: string
          nullable: true
        sortProperty:
          type: string
          nullable: true
        isDescending:
          type: boolean
        userId:
          type: integer
          nullable: true
        amount:
          type: integer
        statusId:
          type: integer
          nullable: true
        createdAt:
          type: string
          format: date
          nullable: true
      additionalProperties: false
    PaymentRequest:
      required:
        - accountHolderName
        - accountNumber
        - address
        - amount
        - city
        - country
        - dateOfBirth
        - destinationCurrency
        - EmailAddress
        - fileId
        - invoiceId
        - originatingCurrency
        - stateProvince
        - status
        - swiftBic
        - zip
      type: object
      properties:
        fileId:
          type: integer
        accountHolderName:
          maxLength: 100
          minLength: 0
          type: string
        dateOfBirth:
          type: string
          format: date
        EmailAddress:
          minLength: 1
          type: string
        originatingCurrency:
          maxLength: 3
          minLength: 3
          type: string
        destinationCurrency:
          maxLength: 3
          minLength: 3
          type: string
        amount:
          minimum: 1
          type: integer
        swiftBic:
          minLength: 1
          type: string
        iban:
          type: string
          nullable: true
        routingNumber:
          type: string
          nullable: true
        accountNumber:
          minLength: 1
          type: string
        address:
          maxLength: 500
          minLength: 0
          type: string
        city:
          minLength: 1
          type: string
        stateProvince:
          minLength: 1
          type: string
        zip:
          minLength: 1
          type: string
        country:
          minLength: 1
          type: string
        invoiceId:
          minLength: 1
          type: string
        note:
          type: string
          nullable: true
        status:
          type: boolean
      additionalProperties: false
    PayoutAccountResponse:
      type: object
      properties:
        accountNumber:
          type: string
          nullable: true
        bankName:
          type: string
          nullable: true
      additionalProperties: false
    PayoutResponse:
      type: object
      properties:
        state:
          type: string
          nullable: true
        payoutId:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the payout was created
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    UltimateDebtor:
      type: object
      properties:
        address_Lines:
          type: string
          nullable: true
        birthdate:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        country_Code:
          type: string
          nullable: true
        country_Of_Birth_Code:
          type: string
          nullable: true
        country_Of_Residence_Code:
          type: string
          nullable: true
        EmailAddress:
          type: string
          nullable: true
        id_Issuing_Date:
          type: string
          nullable: true
        id_Number:
          type: string
          nullable: true
        id_Type:
          type: string
          nullable: true
        mobile_Number:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        postcode:
          type: string
          nullable: true
        state:
          type: string
          nullable: true
        street_Name:
          type: string
          nullable: true
        type:
          type: string
          nullable: true
      additionalProperties: false
    ValidationProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          nullable: true
      additionalProperties: {}
    Webhook:
      type: object
      description: >
        Webhooks are real-time notifications sent to your system when specific
        events occur.  For Payout Events, they notify about payout status
        changes like created, processing, sent, completed, failed, or
        cancelled.  For RFI (Request for Information) Events, they notify when
        additional information is requested, submitted, or reopened by
        compliance.
      properties:
        id:
          type: string
          format: uuid
        url:
          type: string
          nullable: true
      additionalProperties: false
    AccountTypeResponse:
      type: object
      properties:
        accountTypes:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                example: 1
              name:
                type: string
                example: Checking
  securitySchemes:
    Bearer:
      type: http
      description: JWT Authorization header using the Bearer scheme.
      scheme: bearer
      bearerFormat: JWT
security:
  - Bearer: []
tags:
  - name: Payee
    description: >-
      The Payees API allows you to manage your payees easily. 

      You can create new payees, update their information, list all 

      payees, or deactivate them when needed. Each payee can be an 

      individual or a business. This API helps keep track of all your 

      payees in one place.

      Think of it as your digital address book for payments. 

      It ensures that every transaction is sent to the correct and verified
      recipient, 

      simplifying the payout process for your application. 
  - name: Payee Accounts
    description: >-
      The Payee Accounts API allows merchants to manage the bank or payout
      accounts linked to their payees.

      It enables creating, updating, and retrieving payout account details
      securely. 

      Each payee can have one or more accounts associated for receiving funds.

      Use these endpoints to validate account information and ensure smooth
      disbursements.

      This API acts as the secure layer between your system and the banks,
      handling sensitive financial data.
  - name: Payouts
    description: >-
      The Payouts API allows merchants to send money to their payees securely
      and efficiently. 

      You can create new payouts, check their status, and cancel them if needed
      before processing. 

      Each payout is linked to a registered payee and a payout account. 

      The API supports listing all payouts with optional filters like status. 

      Responses include detailed information about the payout, such as amount,
      currency, and current status. 

      Use this API to manage your outgoing payments in a reliable and
      predictable way.
  - name: Webhook
    description: >+
      # About Webhooks


      > Webhooks are automatic messages sent from our system to your server
      whenever something important happens with a payout.  

      > Think of them like **notifications** — they instantly let you know when
      the status of a payout changes.

      > 

      > Your server must be able to accept **HTTPS POST requests** and respond
      with standard HTTP status codes.  

      > Each webhook payload is delivered in **JSON** format.


      ---

      ## When Are Webhooks Sent?


      We send a webhook every time a payout moves to a new stage in its
      lifecycle.  

      Here are the possible events:


      - `payout.created` – A new payout has been created and recorded in the
      system.  

      - `payout.processing` – The payout is currently being processed.    

      - `payout.sent` – The payout has been sent to the bank or payment
      provider.  

      - `payout.completed` – The payout was successfully delivered.  

      - `payout.failed` – The payout could not be completed due to an error.  

      - `payout.cancelled` – The payout was cancelled before completion.


      These webhook notifications help you **track every stage** of a payout in
      real time.


      ---


      ## Webhook Payload Schemas


      Below are example payloads for each webhook event.  

      All payloads share a similar structure, with the main difference being the
      `state` value and any additional fields such as `reasons`.


      ---


      ###  `payout.created`


      ```json

      {
        "payout_request_id": "PR123456789",
        "amount": "100.00",
        "currency": "EUR",
        "timestamp": "2025-01-09T10:24:15Z",
        "state": "created"
      }

      ```


      ---


      ###  `payout.processing`


      ```json

      {
        "payout_request_id": "PR123456789",
        "amount": "100.00",
        "currency": "EUR",
        "timestamp": "2025-01-09T10:25:30Z",
        "state": "processing"
      }

      ```

      ---


      ###  `payout.sent`


      ```json

      {
        "payout_request_id": "PR123456789",
        "amount": "100.00",
        "currency": "EUR",
        "timestamp": "2025-01-09T10:35:00Z",
        "state": "sent"
      }

      ```


      ---


      ###  `payout.completed`


      ```json

      {
        "payout_request_id": "PR123456789",
        "amount": "100.00",
        "currency": "EUR",
        "timestamp": "2025-01-09T10:40:00Z",
        "state": "completed"
      }

      ```

      ---


      ###  `payout.failed`


      ```json

      {
        "payout_request_id": "PR123456789",
        "amount": "100.00",
        "currency": "EUR",
        "timestamp": "2025-01-09T10:45:00Z",
        "state": "failed"
      }

      ```


      ---


      ###  `payout.cancelled`


      ```json

      {
        "payout_request_id": "PR123456789",
        "amount": "100.00",
        "currency": "EUR",
        "timestamp": "2025-01-09T10:50:00Z",
        "state": "cancelled"
      }

      ```


      ---


      ## Handling Webhooks


      When Theropay sends your system a **webhook**, it’s sending a message to
      let you know that something happened — for example, a payout was
      completed.


      Here’s what you need to do step by step:


      1. **Read the webhook message (payload)**  
         - The webhook contains data in **JSON format**.  
         - This data includes details such as the payout ID, amount, and current status.  
         - Theropay **does not include a signature** with the webhook, so you don’t need to verify one.

      2. **Update your system**  
         - Use the information from the webhook to update your records.  
         - For example, if the webhook says a payout is complete, mark that payout as “completed” in your system.  
         - Make sure to handle the webhook data carefully — since Theropay only sends it **once**, your system should be ready to process it correctly the first time.

      3. **Send a response back to Theropay**  
         - After you’ve successfully received and processed the webhook, send back an **`HTTP 200 OK`** response.  
         - This confirms to Theropay that your system got the message.  
         - Since Theropay **only sends the webhook once**, if your system fails to respond or process it correctly, you won’t receive it again.

      ---


      ### Example Response


      ```http

      HTTP/1.1 200 OK

      Content-Type: application/json


      {
        "status": "received"
      }

      ```


      ---


      > 💡 **Tip:**  

      > Always log incoming webhook events for debugging and verification
      purposes.


      ### Creating a Webhook


      You can create a webhook to receive payout events for your system. 

      This involves registering your server endpoint with our API.

      Instead of your system constantly checking for updates, we “push” the
      information to you in real time.


      1. Copy your server URL where you want to receive webhooks.

      2. Go to the **Webhooks API endpoint** in this documentation.

      3. Click **Try it out**.

      4. Paste your URL, select the events you want, and choose **sandbox** or
      **production**.

      5. Click **Execute** to register the webhook.

      6. Check your server or test endpoint to see the webhook payloads in real
      time.


      **Note :  Test in Sandbox First**

      > Always start by creating the webhook in the sandbox environment.

      > This allows you to test your endpoint without affecting real payouts.

      > Once everything works, you can register the webhook in production for
      live notifications.





