openapi: 3.2.0
info:
  title: Malt - API Guidelines Payments API
  version: 0.0.1
  description: "# Table of contents\n\n1. [Overview](/#/#getting-started)\n2. [Authentication](/#/#api-token-types)\n\n\n\n---\n\n# Overview\n\nWelcome to the Malt APIs documentation. This section provides comprehensive information about publicly accessible APIs.\n\n## Getting Started\n\nTo start using Malt's APIs, you'll need:\n\n1. **API Access Token** - Contact your Malt representative to obtain access credentials\n2. **API Documentation** - Browse the available endpoints using the API list on this site\n3. **Rate Limiting Guidelines** - Understand the usage limits and best practices\n\n## Authentication\n\nAll APIs require authentication using access tokens:\n\n```http\nAuthorization: your-api-token-here\n```\n\n## Support\n\nFor support with APIs:\n\n- **Documentation Issues**: Create an issue in the internal documentation repository\n- **API Access**: Contact your Malt representative\n- **Technical Support**: Use the standard Malt support channels\n\n---\n\n# [Authentication](/#authentication)\n\nThis guide explains how to authenticate with Malt's APIs.\n\n## API Token Types\n\nMalt provides different types of API tokens for different use cases:\n\n### Identity Based Tokens\n\nAPIs are accessible with a given identity based scope at malt.\n\n- Freelancer Account tokens\n- Client team token\n- Organization token\n\n## Obtaining an API Token\n\nTo request an API token:\n\n1. **Create an identity** in [signup page](https://www.malt.com/signup)\n2. Access the access token page in [My Account > API Keys](https://www.malt.com/account/tokens)\n3. Create an access token with related permission scopes\n4. Copy the access token, it will only be accessible at the moment you see it.\n\n## Using Your Token\n\nInclude your token in the `Authorization` header of every request:\n\n```http\n\nGET https://api.malt.com/exposed/endpoint\nAuthorization: YOUR_TOKEN_HERE\nContent-Type: application/json\n```\n\n### Example with cURL\n\n```bash\ncurl -H \"Authorization: YOUR_TOKEN_HERE\" \\\n     -H \"Content-Type: application/json\" \\\n     https://api.malt.com/exposed/endpoint\n```\n\n### Example with JavaScript\n\n```javascript\nconst response = await fetch('https://api.malt.com/exposed/endpoint', {\n  headers: {\n    'Authorization': 'YOUR_TOKEN_HERE',\n    'Content-Type': 'application/json'\n  }\n});\n```\n\n## Token Security\n\n⚠️ **Important Security Guidelines:**\n\n- Never expose your token in client-side code\n- Store tokens securely\n- Rotate tokens regularly\n- Monitor token usage in your API dashboard\n\n## Error Responses\n\nCommon authentication errors:\n\n### 401 Unauthorized\n```json\n{\n   \"timestamp\": \"1970-01-01T00:00:00.000+00:00\",\n   \"status\": 401,\n   \"error\": \"Unauthorized\",\n   \"path\": \"/exposed/endpoint\"\n}\n```\n\n### 403 Forbidden\n```json\n{\n   \"timestamp\": \"1970-01-01T00:00:00.000+00:00\",\n   \"status\": 403,\n   \"error\": \"Forbidden\",\n   \"path\": \"/exposed/endpoint\"\n}\n```"
  contact:
    name: Malt API Support
    url: https://malt.com/support
servers:
- url: https://api.malt.com
  description: Production API server
security: []
tags:
- description: Operations related to freelancer payments
  name: Payments
paths:
  /freelancer/payments:
    get:
      description: Get payment history for the authenticated freelancer within a specified date range
      operationId: findPayments
      parameters:
      - description: Start date for the payment search range
        example: '2023-01-01T00:00:00Z'
        explode: true
        in: query
        name: since
        required: true
        schema:
          format: date-time
          type: string
        style: form
      - description: End date for the payment search range (optional)
        example: '2023-12-31T23:59:59Z'
        explode: true
        in: query
        name: until
        required: false
        schema:
          format: date-time
          type: string
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/PaymentResource'
                type: array
          description: List of payments retrieved successfully
        '400':
          description: Bad request - invalid date format
        '401':
          description: Unauthorized - invalid or missing authentication
        '403':
          description: Forbidden - insufficient permissions
      summary: Retrieve list of payments from a range of date
      tags:
      - Payments
components:
  schemas:
    LightInvoiceType:
      description: Type of invoice
      enum:
      - SERVICE_FEES
      - INVOICE
      example: INVOICE
      type: string
    LightInvoiceResource:
      description: Lightweight representation of an invoice
      properties:
        id:
          description: Unique identifier for the invoice
          example: INV-123456
          type: string
        externalId:
          description: External identifier for the invoice
          example: EXT-789
          type:
          - string
          - 'null'
        type:
          $ref: '#/components/schemas/LightInvoiceType'
      required:
      - id
      - type
      type: object
    PaymentResource:
      description: Represents a payment made to the freelancer
      properties:
        id:
          description: Unique identifier for the payment
          example: PAY-123456
          type: string
        date:
          description: Date when the payment was made
          example: '2023-04-01T10:00:00Z'
          format: date-time
          type: string
        amount:
          description: Payment amount
          example: 1200
          format: decimal
          type: number
        currency:
          description: Currency code for the payment
          example: EUR
          type: string
        wireRef:
          description: Wire transfer reference
          example: WIRE-REF-789
          type:
          - string
          - 'null'
        invoices:
          description: List of invoices covered by this payment
          items:
            $ref: '#/components/schemas/LightInvoiceResource'
          type: array
      required:
      - amount
      - currency
      - date
      - id
      - invoices
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: JWT
      description: API token obtained from your Malt representative
      scheme: bearer
      type: http
    ApiKeyAuth:
      description: 'To obtain an access token, please follow [these instructions](https://api.malt.com).

        '
      in: header
      name: Authorization
      type: apiKey