openapi: 3.0.3
info:
  title: Helix-Pay API
  description: API documentation for the Helix-Pay API
  version: 1.0.0
servers:
  - url: https://api.helix-pay.net/v1
    description: Production server
tags:
  - name: Payments
    description: Operations related to payments
  - name: Consumers
    description: >-
      Operations related to consumers. Consumers are mostly used in
      marketplace-type applications where they can deposit money in their
      account to pay for other goods or services or payout to their bank
      accounts.
  - name: Wallets
    description: >-
      Operations related to wallets. Wallets are used to store funds for
      consumers.
  - name: Banks
    description: >-
      Operations related to bank accounts. Bank accounts are used to withdraw
      funds from wallets.
  - name: Payouts
    description: >-
      Operations related to payouts. Payouts are used to withdraw funds from
      wallets to bank accounts.
  - name: Integrations
    description: >-
      Operations related to integrations. Integrations are used to connect Helix
      Pay with external systems (e.g. WIX).
  - name: Customers
    description: >-
      Operations related to customers. Customers are the end-users who make
      payments. Not to be confused with consumers.
  - name: Balances
    description: Operations related to account balances.
  - name: Sub-Merchants
    description: >-
      Operations related to sub-merchants management. Allows parent merchants to
      manage their sub-merchants and create payments on their behalf, while also
      viewing volume analytics and current balances.
paths:
  /health:
    get:
      summary: Health check endpoint
      security:
        - ApiKeyAuth: []
      description: A simple endpoint to check the health of the API
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/HealthcheckSchema'
        '401':
          description: Unauthorized
        '500':
          description: Server error
  /balance:
    get:
      tags:
        - Balances
      summary: Get balance
      security:
        - ApiKeyAuth: []
      description: >-
        Get the balance of the account identified by the API key in all enabled
        currencies
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    currency:
                      type: string
                      description: The currency code
                    balance:
                      type: number
                      description: The balance in the currency
        '401':
          description: Unauthorized
        '500':
          description: Server error
  /payments:
    get:
      tags:
        - Payments
      summary: List payments
      description: Get a paginated list of all payments made by consumers
      security:
        - ApiKeyAuth: []
      parameters:
        - name: limit
          in: query
          description: The maximum number of payments to return
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: offset
          in: query
          description: The number of payments to skip
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: status
          in: query
          description: Filter payments by status
          schema:
            type: string
            enum:
              - pending
              - completed
              - failed
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentSchema'
                  metadata:
                    type: object
                    properties:
                      total:
                        type: integer
                      limit:
                        type: integer
                      offset:
                        type: integer
        '401':
          description: Unauthorized
        '500':
          description: Server error
    post:
      tags:
        - Payments
      summary: Create a new payment
      security:
        - ApiKeyAuth: []
      description: Creates a new payment request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentSchema'
            examples:
              CardPaymentRequest:
                $ref: '#/components/examples/CardPaymentRequest'
      responses:
        '201':
          description: Payment request created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentSchema'
              examples:
                PaymentExample:
                  $ref: '#/components/examples/PaymentExample'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorSchema'
              examples:
                AmountNotSet:
                  $ref: '#/components/examples/AmountNotSetPayloadExample'
                UnsupportedCurrency:
                  $ref: '#/components/examples/UnsupportedCurrencyPayloadExample'
                CurrencyNotEnabledForEnvironment:
                  $ref: >-
                    #/components/examples/CurrencyNotEnabledForEnvironmentPayloadExample
        '401':
          description: Unauthorized
        '500':
          description: Server error
  /payments/{payment_id}:
    get:
      tags:
        - Payments
      summary: Get payment details
      security:
        - ApiKeyAuth: []
      description: Get details for a specific payment
      parameters:
        - name: payment_id
          in: path
          required: true
          description: The unique identifier for the payment
          schema:
            type: string
          example: pay_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentSchema'
              examples:
                PaymentExample:
                  $ref: '#/components/examples/PaymentExample'
        '401':
          description: Unauthorized
        '404':
          description: Payment not found
        '500':
          description: Server error
    patch:
      tags:
        - Payments
      summary: Update payment status
      security:
        - ApiKeyAuth: []
      description: Update the details of a specific payment
      parameters:
        - name: payment_id
          in: path
          required: true
          description: The unique identifier for the payment
          schema:
            type: string
          example: pay_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePaymentSchema'
      responses:
        '200':
          description: Payment updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentSchema'
              examples:
                PaymentExample:
                  $ref: '#/components/examples/PaymentExample'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorSchema'
        '401':
          description: Unauthorized
        '404':
          description: Payment not found
        '500':
          description: Server error
  /payments/{payment_id}/refund:
    post:
      tags:
        - Payments
      summary: Refund a payment
      security:
        - ApiKeyAuth: []
      description: Request a refund for a specific payment
      parameters:
        - name: payment_id
          in: path
          required: true
          description: The unique identifier for the payment
          schema:
            type: string
          example: pay_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundPaymentSchema'
      responses:
        '201':
          description: Refund request created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentSchema'
        '401':
          description: Unauthorized
        '404':
          description: Payment not found
        '412':
          description: Payment is not in a valid state to refund
        '500':
          description: Server error
  /payments/{payment_id}/cancel:
    post:
      tags:
        - Payments
      summary: Cancel a payment
      security:
        - ApiKeyAuth: []
      description: >-
        Cancel a specific payment. You can only cancel payments that are in the
        `CREATED` status.
      parameters:
        - name: payment_id
          in: path
          required: true
          description: The unique identifier for the payment
          schema:
            type: string
          example: pay_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelPaymentSchema'
      responses:
        '200':
          description: Payment cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentSchema'
        '401':
          description: Unauthorized
        '404':
          description: Payment not found
        '412':
          description: Payment is not in a valid state to cancel
        '500':
          description: Server error
  /integrations:
    post:
      summary: Create a new integration
      tags:
        - Integrations
      security:
        - ApiKeyAuth: []
      description: Creates a new integration with an external system (e.g. Wix)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIntegrationSchema'
      responses:
        '201':
          description: Integration created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationSchema'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '500':
          description: Server error
  /integrations/{integration_id}:
    get:
      tags:
        - Integrations
      summary: Get integration details
      description: Get details for a specific integration
      security:
        - ApiKeyAuth: []
      parameters:
        - name: integration_id
          in: path
          required: true
          schema:
            type: string
          example: int_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationSchema'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Integration not found
        '500':
          description: Server error
  /consumers:
    post:
      tags:
        - Consumers
      summary: Create a new consumer
      security:
        - ApiKeyAuth: []
      description: Creates a new consumer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConsumerSchema'
      responses:
        '201':
          description: Consumer created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsumerSchema'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorSchema'
        '401':
          description: Unauthorized
        '500':
          description: Server error
  /consumers/{consumer_id}:
    get:
      tags:
        - Consumers
      summary: Get consumer details
      security:
        - ApiKeyAuth: []
      description: Get details for a specific consumer
      parameters:
        - name: consumer_id
          in: path
          required: true
          description: The unique identifier for the consumer
          schema:
            type: string
          example: csm_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsumerSchema'
        '401':
          description: Unauthorized
        '404':
          description: Consumer not found
        '500':
          description: Server error
  /consumers/{consumer_id}/banks:
    post:
      tags:
        - Banks
      summary: Create a new bank account
      security:
        - ApiKeyAuth: []
      description: Creates a new bank account
      parameters:
        - name: consumer_id
          in: path
          required: true
          description: The unique identifier for the consumer
          schema:
            type: string
          example: csm_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBankSchema'
      responses:
        '201':
          description: Bank created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankSchema'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorSchema'
        '401':
          description: Unauthorized
        '500':
          description: Server error
  /consumers/{consumer_id}/banks/{bank_id}:
    get:
      tags:
        - Banks
      summary: Get bank account details
      security:
        - ApiKeyAuth: []
      description: Get details for a specific bank account
      parameters:
        - name: consumer_id
          in: path
          required: true
          description: The unique identifier for the consumer
          schema:
            type: string
          example: csm_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
        - name: bank_id
          in: path
          required: true
          description: The unique identifier for the bank account
          schema:
            type: string
          example: ba_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankSchema'
        '401':
          description: Unauthorized
        '404':
          description: Bank account not found
        '500':
          description: Server error
  /payouts:
    post:
      summary: Request a new payout
      tags:
        - Payouts
      security:
        - ApiKeyAuth: []
      description: Creates a new withdrawal request for a consumer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePayoutSchema'
      responses:
        '201':
          description: Payout created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutSchema'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '500':
          description: Server error
  /payouts/{payout_id}:
    get:
      summary: Get payout details
      tags:
        - Payouts
      security:
        - ApiKeyAuth: []
      parameters:
        - name: payout_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutSchema'
        '401':
          description: Unauthorized
        '404':
          description: Payout not found
        '500':
          description: Server error
    patch:
      summary: Cancel a payout request
      tags:
        - Payouts
      security:
        - ApiKeyAuth: []
      parameters:
        - name: payout_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Payout updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutSchema'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Payout not found
        '500':
          description: Server error
  /wallets:
    post:
      tags:
        - Wallets
      summary: Create a new wallet
      security:
        - ApiKeyAuth: []
      description: Creates a new wallet
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWalletSchema'
      responses:
        '201':
          description: Wallet created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletSchema'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorSchema'
        '401':
          description: Unauthorized
        '500':
          description: Server error
  /wallets/{wallet_id}:
    get:
      tags:
        - Wallets
      summary: Get wallet details
      security:
        - ApiKeyAuth: []
      description: Get details for a specific wallet
      parameters:
        - name: wallet_id
          in: path
          required: true
          description: The unique identifier for the wallet
          schema:
            type: string
          example: wlt_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletSchema'
        '401':
          description: Unauthorized
        '404':
          description: Wallet not found
        '500':
          description: Server error
  /customers:
    get:
      tags:
        - Customers
      summary: List customers
      description: Get a paginated list of all customers you saved in your system
      security:
        - ApiKeyAuth: []
      parameters:
        - name: limit
          in: query
          description: The maximum number of customers to return
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: offset
          in: query
          description: The number of customers to skip
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomerSchema'
                  metadata:
                    type: object
                    properties:
                      total:
                        type: integer
                      limit:
                        type: integer
                      offset:
                        type: integer
        '401':
          description: Unauthorized
        '500':
          description: Server error
    post:
      tags:
        - Customers
      summary: Create a new customer
      security:
        - ApiKeyAuth: []
      description: Creates a new customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerSchema'
      responses:
        '201':
          description: Customer created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerSchema'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorSchema'
        '401':
          description: Unauthorized
        '500':
          description: Server error
  /customers/{customer_id}:
    get:
      tags:
        - Customers
      summary: Get customer details
      security:
        - ApiKeyAuth: []
      description: Get details for a specific customer
      parameters:
        - name: customer_id
          in: path
          required: true
          description: The unique identifier for the customer
          schema:
            type: string
          example: cust_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerSchema'
        '401':
          description: Unauthorized
        '404':
          description: Customer not found
        '500':
          description: Server error
    patch:
      tags:
        - Customers
      summary: Update customer details
      security:
        - ApiKeyAuth: []
      description: Update details for a specific customer
      parameters:
        - name: customer_id
          in: path
          required: true
          description: The unique identifier for the customer
          schema:
            type: string
          example: cust_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerSchema'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerSchema'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorSchema'
        '401':
          description: Unauthorized
        '404':
          description: Customer not found
        '500':
          description: Server error
  /merchants:
    get:
      tags:
        - Sub-Merchants
      summary: List sub-merchants
      description: >-
        Get a list of all sub-merchants associated with your parent merchant
        account.
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SubMerchantSchema'
                  metadata:
                    type: object
                    properties:
                      total:
                        type: integer
                      limit:
                        type: integer
                      offset:
                        type: integer
        '401':
          description: Unauthorized
        '403':
          description: Forbidden (Feature not enabled for your merchant account)
        '500':
          description: Server error
  /merchants/signup-sessions:
    get:
      tags:
        - Sub-Merchants
      summary: List signup sessions
      description: Get all signup sessions created by your parent merchant
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SignupSessionSchema'
                  metadata:
                    type: object
                    properties:
                      total:
                        type: integer
                      limit:
                        type: integer
                      offset:
                        type: integer
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Server error
    post:
      tags:
        - Sub-Merchants
      summary: Create signup session
      description: Create a new signup session for a sub-merchant
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMerchantSignupSessionSchema'
      responses:
        '201':
          description: Signup session created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupSessionSchema'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorSchema'
        '401':
          description: Unauthorized
        '500':
          description: Server error
  /merchants/signup-sessions/{sessionId}:
    get:
      tags:
        - Sub-Merchants
      summary: Get signup session
      description: Retrieve details of a specific signup session
      security:
        - ApiKeyAuth: []
      parameters:
        - name: sessionId
          in: path
          required: true
          description: The unique identifier for the signup session
          schema:
            type: string
          example: mrc_ses_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupSessionSchema'
        '401':
          description: Unauthorized
        '404':
          description: Signup session not found
        '500':
          description: Server error
    patch:
      tags:
        - Sub-Merchants
      summary: Update signup session
      description: Update an existing signup session
      security:
        - ApiKeyAuth: []
      parameters:
        - name: sessionId
          in: path
          required: true
          description: The unique identifier for the signup session
          schema:
            type: string
          example: mrc_ses_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMerchantSignupSessionSchema'
      responses:
        '200':
          description: Signup session updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupSessionSchema'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorSchema'
        '401':
          description: Unauthorized
        '404':
          description: Signup session not found
        '500':
          description: Server error
    delete:
      tags:
        - Sub-Merchants
      summary: Delete signup session
      description: >-
        Delete a signup session. This only works if the session is in CREATED
        status. Already completed, in progress, or expired sessions cannot be
        deleted.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: sessionId
          in: path
          required: true
          description: The unique identifier for the signup session
          schema:
            type: string
          example: mrc_ses_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
      responses:
        '204':
          description: Signup session deleted
        '401':
          description: Unauthorized
        '404':
          description: Signup session not found
        '500':
          description: Server error
  /merchants/signup-sessions/{sessionId}/reactivate:
    post:
      tags:
        - Sub-Merchants
      summary: Reactivate signup session
      description: >-
        Reactivate an expired or cancelled signup session. This extends an
        expired session by 3 days from the time of reactivation.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: sessionId
          in: path
          required: true
          description: The unique identifier for the signup session
          schema:
            type: string
          example: mrc_ses_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReactivateSignupSessionSchema'
      responses:
        '200':
          description: Signup session reactivated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupSessionSchema'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorSchema'
        '401':
          description: Unauthorized
        '404':
          description: Signup session not found
        '412':
          description: Signup session is not in a valid state to reactivate
        '500':
          description: Server error
  /merchants/{merchantId}/balance:
    get:
      tags:
        - Sub-Merchants
      summary: Get sub-merchant balance
      description: Get the current balance for a specific sub-merchant
      security:
        - ApiKeyAuth: []
      parameters:
        - name: merchantId
          in: path
          required: true
          description: The unique identifier for the sub-merchant
          schema:
            type: string
          example: mrc_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
        - name: currency
          in: query
          description: >-
            The currency code to filter the balance (e.g. USD, EUR). If not
            provided, returns balance in all currencies.
          schema:
            type: string
          example: USD
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantBalanceSchema'
        '401':
          description: Unauthorized
        '404':
          description: Merchant not found
        '500':
          description: Server error
  /merchants/{merchantId}/payments:
    get:
      tags:
        - Sub-Merchants
      summary: Get sub-merchant payments
      description: Retrieve payments for a specific sub-merchant
      security:
        - ApiKeyAuth: []
      parameters:
        - name: merchantId
          in: path
          required: true
          description: The unique identifier for the sub-merchant
          schema:
            type: string
          example: mer_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
        - name: limit
          in: query
          description: The maximum number of payments to return
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: offset
          in: query
          description: The number of payments to skip
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: status
          in: query
          description: Filter payments by status
          schema:
            type: string
            enum:
              - pending
              - completed
              - failed
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentSchema'
                  metadata:
                    type: object
                    properties:
                      total:
                        type: integer
                      limit:
                        type: integer
                      offset:
                        type: integer
        '401':
          description: Unauthorized
        '404':
          description: Merchant not found
        '500':
          description: Server error
  /merchants/{merchantId}/payouts:
    get:
      tags:
        - Sub-Merchants
      summary: Get a sub-merchant's payouts.
      description: Retrieve the payouts for a specific sub-merchant.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: merchantId
          in: path
          required: true
          description: The unique identifier for the sub-merchant
          schema:
            type: string
          example: mrc_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
        - name: limit
          in: query
          description: The maximum number of payouts to return
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: offset
          in: query
          description: The number of payouts to skip
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: status
          in: query
          description: Filter payouts by status
          schema:
            type: string
            enum:
              - pending
              - completed
              - failed
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/MerchantPayoutSchema'
                  metadata:
                    type: object
                    properties:
                      total:
                        type: integer
                      limit:
                        type: integer
                      offset:
                        type: integer
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Merchant not found
        '500':
          description: Server error
  /merchants/{merchantId}/payouts/{payoutId}:
    get:
      tags:
        - Sub-Merchants
      summary: Get the details of a specific sub-merchant payout.
      description: Retrieve the details of a specific payout for a sub-merchant.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: merchantId
          in: path
          required: true
          description: The unique identifier for the sub-merchant
          schema:
            type: string
          example: mrc_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
        - name: payoutId
          in: path
          required: true
          description: The unique identifier for the payout
          schema:
            type: string
          example: pyo_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantPayoutSchema'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Merchant not found
        '500':
          description: Server error
  /merchants/{merchantId}/payouts/{payoutId}/transactions:
    get:
      tags:
        - Sub-Merchants
      summary: Get transactions for a specific sub-merchant payout.
      description: >-
        Retrieve the transactions associated with a specific payout for a
        sub-merchant. Transactions can be of type PAYMENT or REFUND.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: merchantId
          in: path
          required: true
          description: The unique identifier for the sub-merchant
          schema:
            type: string
          example: mer_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
        - name: limit
          in: query
          description: The maximum number of transactions to return
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: offset
          in: query
          description: The number of transactions to skip
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PayoutTransactionSchema'
                  metadata:
                    type: object
                    properties:
                      total:
                        type: integer
                      limit:
                        type: integer
                      offset:
                        type: integer
        '401':
          description: Unauthorized
        '404':
          description: Merchant not found
        '500':
          description: Server error
  /merchants/{merchantId}/api-key:
    get:
      tags:
        - Sub-Merchants
      summary: Get sub-merchant API key
      description: >-
        Retrieve the API key information for a sub-merchant. This is a temporary
        endpoint and will be deprecated in the future. Useful to create payments
        on behalf of your sub-merchants.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: merchantId
          in: path
          required: true
          description: The unique identifier for the sub-merchant
          schema:
            type: string
          example: mrc_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantApiKeySchema'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Merchant not found
        '500':
          description: Server error
  /merchants/volumes:
    get:
      tags:
        - Sub-Merchants
      summary: Get merchant volumes
      description: >-
        Get gross and net volumes for all your sub-merchants for a specified
        date and currency. If no date is provided, it defaults to the previous
        full day.
      security:
        - ApiKeyAuth: []
      parameters:
        - name: currency
          in: query
          description: Filter by currency code
          schema:
            type: string
          example: EUR
        - name: date
          in: query
          description: >-
            The date to get volumes for (YYYY-MM-DD). Defaults to the previous
            full day if not provided.
          schema:
            type: string
            format: date
          example: '2025-10-01'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantVolumesSchema'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Server error
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
  schemas:
    HealthcheckSchema:
      type: object
      required:
        - message
      properties:
        message:
          type: string
    ValidationErrorSchema:
      type: object
      required:
        - message
        - errors
      properties:
        message:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/FieldErrorSchema'
    FieldErrorSchema:
      type: object
      properties:
        field:
          type: string
          example: amount
        message:
          type: string
          example: This field is required
    CreateBankSchema:
      type: object
      required:
        - mandate_type
        - data
      properties:
        bank_name:
          type: string
          description: The name of the bank
          example: Bank of Dave
        name:
          type: string
          description: Nice name of bank for user
          example: My Primary Account
        mandate_type:
          type: string
          description: The type of mandate for the bank account
          example: IBAN
        data:
          type: object
          description: The bank account data
    BankSchema:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the bank account
          example: ba_589b9558211e0182
        consumer_id:
          type: string
          description: The unique identifier for the consumer
        bank_name:
          type: string
          description: The name of the bank
        mandate_type:
          type: string
          description: The type of mandate for the bank account
          example: IBAN
        data:
          type: object
          description: The bank account data
          example: '{ "iban": "GB33BUKB20201555555555", "bic": "BUKBGB22" }'
    PayoutSchema:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the payout
        consumer_id:
          type: string
          description: The unique identifier for the consumer
        amount:
          type: number
          description: The amount of the payout
        status:
          type: string
          description: The status of the payout
        wallet_id:
          type: string
          description: The unique identifier for the wallet to payout from
        merchant_name:
          type: string
          description: The name of the merchant
        bank_account_id:
          type: string
          description: The unique identifier for the bank account
        created_at:
          type: string
          format: date-time
          description: The timestamp when the payout was created
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the payout was last updated
    CreatePayoutSchema:
      type: object
      properties:
        consumer_id:
          type: string
          description: The unique identifier for the consumer
        amount:
          type: number
          description: The amount of the payout
        currency:
          type: string
          description: The currency of the payout
        wallet_id:
          type: string
          description: The unique identifier for the wallet to payout from
        bank_account_id:
          type: string
          description: The unique identifier for the bank account
    UpdatePayoutSchema:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          description: The status of the payout
    IntegrationSchema:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the integration
        name:
          type: string
          description: The name of the integration
        type:
          type: string
          description: The type of the integration
        data:
          type: object
          description: The integration data
    CreateIntegrationSchema:
      type: object
      required:
        - integration_code
        - config
      properties:
        label:
          type: string
          description: The label for the integration
        integration_code:
          type: string
          description: The code for the integration
        config:
          type: object
          oneOf:
            - $ref: '#/components/schemas/WixIntegrationConfig'
    WixIntegrationConfig:
      type: object
      properties:
        update_url:
          type: string
          description: The URL to send updates to (via webhook)
          example: https://WIX_USER.wixsite.com/WIX_SHOP/_functions/updateTransaction/
    CreateWalletSchema:
      type: object
      properties:
        consumer_id:
          type: string
          description: The unique identifier for the consumer
          example: csm_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
        currency:
          type: string
          description: The currency of the wallet
          example: EUR
    WalletSchema:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the wallet
          example: wlt_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
        consumer_id:
          type: string
          description: The unique identifier for the consumer
        currency:
          type: string
          description: The currency of the wallet
          example: EUR
        balance:
          type: number
          description: The current balance of the wallet
        created_at:
          type: string
          format: date-time
          description: The timestamp when the wallet was created
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the wallet was last updated
    CreateCustomerSchema:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
        address:
          type: object
          properties:
            address_line_1:
              type: string
              example: 123 Main St
            address_line_2:
              type: string
              example: Apt 101
            city:
              type: string
              example: San Francisco
            state:
              type: string
              example: CA
            postal_code:
              type: string
              example: '94107'
            country:
              type: string
              example: US
    CustomerSchema:
      type: object
      properties:
        id:
          type: string
          example: cust_1ks881js771j
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
        address:
          type: object
          properties:
            address_line_1:
              type: string
              example: 123 Main St
            address_line_2:
              type: string
              example: Apt 101
            city:
              type: string
              example: San Francisco
            state:
              type: string
              example: CA
            postal_code:
              type: string
              example: '94107'
            country:
              type: string
              example: US
    UpdatePaymentSchema:
      type: object
      properties:
        description:
          type: string
        metadata:
          type: object
    SubMerchantSchema:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the sub-merchant
          example: mrc_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
        display_name:
          type: string
          description: The display name of the sub-merchant
          example: Sub-Merchant Store
        legal_name:
          type: string
          description: The legal name of the sub-merchant
          example: Sub-Merchant Store
        merchant_type_id:
          type: string
          description: The type ID of the sub-merchant
          example: BUSINESS
        merchant_category_id:
          type: string
          description: The category ID of the sub-merchant
          example: ENERGY
        country_code:
          type: string
          description: The country code of the sub-merchant
          example: US
        status:
          type: string
          description: >-
            The status of the sub-merchant. TEST_MODE is only for sandbox
            accounts.
          enum:
            - ONBOARDING
            - ACTIVE
            - TEST_MODE
          example: ACTIVE
        parent_id:
          type: string
          description: The unique identifier for the parent merchant
          example: mrc_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
    SignupSessionSchema:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the signup session
          example: mrc_ses_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
        user_email:
          type: string
          description: The email address for the signup session
          example: newmerchant@example.com
        merchant_name:
          type: string
          description: The name of the merchant to be created
          example: New Store
        status:
          type: string
          description: The status of the signup session
          enum:
            - PENDING
            - COMPLETED
            - EXPIRED
            - CANCELLED
          example: PENDING
        merchant_type:
          type: string
          description: The type of the merchant, if provided during creation
          enum:
            - BUSINESS
            - PARTNERSHIP
            - ORGANIZATION
            - SOLETRADER
          example: BUSINESS
        merchant_category:
          type: string
          description: The merchant category, if provided during creation
          example: RETAIL
        country_code:
          type: string
          description: The country code for the merchant, if provided during creation
          example: US
        expires_at:
          type: string
          format: date-time
          description: The timestamp when the signup session expires
        created_at:
          type: string
          format: date-time
          description: The timestamp when the signup session was created
    CreateMerchantSignupSessionSchema:
      type: object
      properties:
        merchant_name:
          type: string
          x-oapi-codegen-extra-tags:
            validate: required
        user_email:
          type: string
          x-oapi-codegen-extra-tags:
            validate: required,email
        merchant_type:
          type: string
          enum:
            - BUSINESS
            - PARTNERSHIP
            - ORGANIZATION
            - SOLETRADER
          example: BUSINESS
        merchant_category:
          type: string
        country_code:
          type: string
          format: iso-alpha-2
        expires_at:
          type: string
          description: The expiration date of the session
          example: '2025-01-16T00:00:00.000Z'
    UpdateMerchantSignupSessionSchema:
      type: object
      properties:
        merchant_name:
          type: string
        user_email:
          type: string
        merchant_type:
          type: string
          enum:
            - BUSINESS
            - PARTNERSHIP
            - ORGANIZATION
            - SOLETRADER
          example: BUSINESS
        merchant_category:
          type: string
        country_code:
          type: string
          format: iso-alpha-2
        expires_at:
          type: string
          description: The expiration date of the session
          example: '2025-01-16T00:00:00.000Z'
    ReactivateSignupSessionSchema:
      type: object
      properties:
        expires_in_hours:
          type: integer
          description: Number of hours until the session expires
          minimum: 1
          maximum: 168
          default: 168
          example: 168
    MerchantBalanceSchema:
      type: object
      properties:
        balance:
          type: object
          additionalProperties:
            type: number
          description: A map of currency codes to their respective balances
          example:
            USD: 1000
            EUR: 500
        currency:
          type: string
          description: >-
            The currency code of the balance (if a specific currency was
            requested)
          example: USD
    MerchantApiKeySchema:
      type: object
      properties:
        key:
          type: string
          description: The API key value
          example: hpk_test_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
    MerchantVolumesSchema:
      type: object
      properties:
        gross:
          type: number
          description: The gross volume amount
          example: 10000
        net:
          type: number
          description: The net volume amount
          example: 9500
    MerchantPayoutSchema:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the payout
        amount:
          type: number
          description: The amount of the payout
        currency:
          type: string
          description: The currency of the payout
        status:
          type: string
          description: The status of the payout
        created_at:
          type: string
          format: date-time
          description: The timestamp when the payout was created
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the payout was last updated
    PayoutTransactionSchema:
      allOf:
        - $ref: '#/components/schemas/PaymentSchema'
        - type: object
          properties:
            type:
              type: string
              description: The type of the transaction (PAYMENT or REFUND)
              enum:
                - PAYMENT
                - REFUND
    ReturnUrlsSchema:
      type: object
      properties:
        success:
          type: string
          format: uri
          example: https://example.com/payment/success
        failure:
          type: string
          format: uri
          example: https://example.com/payment/failure
    PaymentBreakdownSchema:
      type: object
      properties:
        fees:
          type: integer
        net_amount:
          type: integer
    RefundPaymentResponseSchema:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the refund
          example: rfd_123
        payment_id:
          type: string
          description: The unique identifier for the payment
          example: pay_123
        amount:
          type: integer
          description: The amount refunded
          example: 1000
        reason_code:
          type: string
          description: The reason for the refund
          example: DUPLICATE
        other_reason:
          type: string
          description: Other reason for the refund if code is OTHER
          example: Cancellation
        created_at:
          type: string
          format: date-time
          description: The date and time the refund was created
          example: '2021-01-01T00:00:00Z'
        status:
          type: string
          description: The status of the refund
          example: REFUND_REQUESTED
        updated_at:
          type: string
          format: date-time
          description: The date and time the refund was last updated
          example: '2021-01-01T00:00:00Z'
    BillingDetailsSchema:
      type: object
      properties:
        first_name:
          type: string
          description: The first name of the person or entity being billed
          example: John
        last_name:
          type: string
          description: The last name of the person or entity being billed
          example: Doe
        email:
          type: string
          description: The email address
        phone_number:
          type: string
          description: The phone number of the person or entity being billed
        address_line_1:
          type: string
          description: The first line of the billing address
          example: 123 Main St
        address_line_2:
          type: string
          description: The second line of the billing address
          example: Apt 101
        city:
          type: string
          description: The city of the billing address
          example: San Francisco
        state:
          type: string
          description: The state, region, or province of the billing address
          example: CA
        zip_code:
          type: string
          description: The postal code of the billing address
          example: '94107'
        country_code:
          type: string
          description: The country code of the billing address
          example: US
    PaymentConfigSchema:
      type: object
      properties:
        collected_fields:
          type: string
          description: Comma-separated list of fields to collect during checkout.
          example: email,phone_number
    PaymentSchema:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the payment
          example: pay_7uAd21uizm5p1psa
        amount:
          type: integer
          description: The payment amount in the lowest currency unit (e.g. cents)
          example: 1099
        currency:
          type: string
          description: The payment currency
          example: EUR
        description:
          type: string
          description: A short description of the payment
          example: 'Payment for order #1234'
        checkout_url:
          type: string
          description: The URL to redirect the user to for payment
          example: https://checkout.helixpay.io/pay_7uAd21uizm5p1psa
        return_urls:
          type: object
          $ref: '#/components/schemas/ReturnUrlsSchema'
        destination_wallet_id:
          type: string
          description: The ID of the wallet to which the payment will be sent
          example: wlt_7uAd21uizm5p1psa
        metadata:
          type: object
          description: Additional metadata for the payment
          example:
            order_id: '1234'
            customer_id: '5678'
        payment_status_code:
          type: string
          description: >-
            The status of the payment request. This will always be "Created" for
            a newly created payment request.
          example: CREATED
        payment_method_code:
          type: string
          description: The payment method used for the payment
          example: card
        test_mode:
          type: boolean
          description: If the payment is a test payment for sandbox testing
          example: false
        breakdown:
          type: object
          $ref: '#/components/schemas/PaymentBreakdownSchema'
        refund:
          type: object
          $ref: '#/components/schemas/RefundPaymentResponseSchema'
        billing_address:
          type: object
          $ref: '#/components/schemas/BillingDetailsSchema'
        payment_config:
          type: object
          $ref: '#/components/schemas/PaymentConfigSchema'
        created_at:
          type: string
          format: date-time
          description: The date and time the payment request was created
          example: '2021-01-01T12:00:00Z'
        updated_at:
          type: string
          format: date-time
          description: The date and time the payment request was last updated
          example: '2021-01-01T12:00:00Z'
        expires_at:
          type: string
          format: date-time
          description: The time after which the payment request will expire
          example: '2022-01-01T12:00:00Z'
        completed_at:
          type: string
          format: date-time
          description: The time at which the payment was completed
          example: '2022-01-01T12:00:00Z'
    CreatePaymentSchema:
      type: object
      required:
        - amount
        - currency
        - description
      properties:
        amount:
          type: integer
          description: The payment amount in the lowest currency unit (e.g. cents)
          example: 1099
          x-oapi-codegen-extra-tags:
            validate: required
        currency:
          type: string
          enum:
            - USD
            - EUR
            - GBP
          format: currency-code
          example: EUR
          x-oapi-codegen-extra-tags:
            validate: required
        description:
          type: string
          description: A short description of the payment
          example: 'Payment for order #1234'
          x-oapi-codegen-extra-tags:
            validate: required,max=255,min=1
        return_urls:
          type: object
          description: >-
            The URLs to redirect the user to after payment, depending on the
            payment status. If you want to process both statuses on the same
            page, you can use the same URL for both properties.
          properties:
            success:
              type: string
              example: https://example.com/payment/success
              x-oapi-codegen-extra-tags:
                validate: url
            failure:
              type: string
              example: https://example.com/payment/failure
              x-oapi-codegen-extra-tags:
                validate: url
        destination_wallet_id:
          type: string
          description: >-
            The ID of the wallet to which the payment will be sent. This is
            required for marketplace type flows.
          example: wlt_7uAd21uizm5p1psa
        metadata:
          type: object
          description: >-
            Additional metadata for the payment. We will store this as part of
            the payment request and return it with every GET request for a
            specific payment.
          example:
            order_id: '1234'
            customer_id: '5678'
        expires_at:
          type: string
          description: >-
            The time after which the payment request will expire. This should be
            in ISO 8601 format. Defaults to 60 minutes after the payment request
            is created.
          example: '2022-01-01T12:00:00Z'
        payment_config:
          $ref: '#/components/schemas/PaymentConfigSchema'
        billing_address:
          type: object
          description: The billing address for the payment
          properties:
            first_name:
              type: string
              example: John
              x-oapi-codegen-extra-tags:
                validate: required,max=50,min=1
            last_name:
              type: string
              example: Doe
              x-oapi-codegen-extra-tags:
                validate: required,max=50,min=1
            email:
              type: string
              x-oapi-codegen-extra-tags:
                validate: required,max=50,min=1
            phone_number:
              type: string
            address_line_1:
              type: string
              example: 123 Main St
              x-oapi-codegen-extra-tags:
                validate: required,max=100,min=1
            address_line_2:
              type: string
              example: Apt 101
            city:
              type: string
              example: San Francisco
              x-oapi-codegen-extra-tags:
                validate: required,max=50,min=1
            state:
              type: string
              example: CA
              x-oapi-codegen-extra-tags:
                validate: required,max=50,min=1
            zip_code:
              type: string
              example: '94107'
              x-oapi-codegen-extra-tags:
                validate: required,max=20,min=1
            country_code:
              type: string
              example: US
              x-oapi-codegen-extra-tags:
                validate: required,country_code
    RefundPaymentSchema:
      type: object
      required:
        - amount
        - reason_code
      properties:
        amount:
          type: integer
          description: The amount to refund. Up to the payment amount
          example: 1000
        reason_code:
          type: string
          enum:
            - FRADULENT
            - CUSTOMER_REQUESTED
            - DUPLICATE
            - OTHER
          description: The reason for the refund
          example: CUSTOMER_REQUESTED
        other_reason:
          type: string
          description: Required if reason_code is OTHER
          example: Order Cancelled
    CancelPaymentSchema:
      type: object
      properties:
        cancel_reason:
          type: string
          description: The reason for cancelling the payment
          example: ABANDONED
          x-oapi-codegen-extra-tags:
            validate: required,oneof=DUPLICATE CUSTOMER_REQUESTED FRAUDULENT ABANDONED
    CreateConsumerPersonalDetailsSchema:
      type: object
      description: >-
        If consumer_type is INDIVIDUAL, personal_details must be provided. If
        consumer_type is BUSINESS, company_details must be provided.
      required:
        - email
      properties:
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
          example: '+44123456789'
    CreateConsumerSchema:
      type: object
      required:
        - consumer_type
        - details
      properties:
        consumer_type:
          type: string
          description: The type of consumer. Can be either INDIVIDUAL or BUSINESS.
          example: INDIVIDUAL
          x-oapi-codegen-extra-tags:
            validate: required,oneof=INDIVIDUAL BUSINESS
        details:
          $ref: '#/components/schemas/CreateConsumerPersonalDetailsSchema'
    ConsumerSchema:
      type: object
      required:
        - id
        - merchant_environment_id
        - consumer_type
        - created_at
        - updated_at
      properties:
        id:
          type: string
          example: csm_1234abcd
        merchant_environment_id:
          type: string
          example: env_1234
        consumer_type:
          type: string
          example: INDIVIDUAL
          x-oapi-codegen-extra-tags:
            validate: required,oneof=INDIVIDUAL BUSINESS
        check_status:
          type: string
          nullable: true
          example: PENDING
        check_reference_id:
          type: string
          nullable: true
          example: chk_1234abcd
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  examples:
    CardPaymentRequest:
      summary: Card Payment Request
      value:
        amount: 1000
        currency: EUR
        description: 'Payment for order #1989188'
        payment_method_code: CARD
        return_urls:
          failure: https://example.com/payments/failure
          success: https://example.com/payments/success
    PaymentExample:
      summary: Payment Example
      value:
        amount: 1000
        checkout_url: >-
          https://checkout.helix-pay.net/checkout/pay_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
        created_at: '2025-01-16T00:00:00.00000Z'
        currency: EUR
        description: 'Payment for order #1989188'
        id: pay_3bbb4fe7-4c25-45b2-a363-c8db8c0084b9
        payment_method_code: CARD
        payment_status_code: CREATED
        return_urls:
          failure: https://example.com/payments/failure
          success: https://example.com/payments/success
        test_mode: false
        updated_at: '2025-01-16T00:00:00.00000Z'
    AmountNotSetPayloadExample:
      summary: Amount Not Set
      value:
        message: Invalid request body
        errors:
          - field: amount
            message: This field is required
    UnsupportedCurrencyPayloadExample:
      summary: Unsupported Currency
      value:
        message: Invalid request body
        errors:
          - field: currency
            message: Payments in CHF are not supported
    CurrencyNotEnabledForEnvironmentPayloadExample:
      summary: Currency Not Enabled
      value:
        message: Invalid request body
        errors:
          - field: currency
            message: >-
              Payments in JPY are not enabled for this environment. You can
              enable it on the environment settings page.
