openapi: 3.0.3
info:
  title: HooPay Partner API
  description: |
    # HooPay Partner API Documentation
    
    Welcome to the HooPay Partner API documentation. This API enables external 
    partners to integrate payment and deposit services with HooPay.
    
    ## API Overview
    
    The Partner API provides two main capabilities:
    
    | Domain | Description | Use Case |
    |--------|-------------|----------|
    | **Deposits** | Partner → HooPay | Credit funds to user wallets |
    | **Withdrawals** | HooPay → Partner | Transfer funds from HooPay to partner |
    
    ## Getting Started
    
    ### 1. Obtain API Credentials
    
    Contact HooPay to register as a partner and receive:
    - Partner account credentials
    - Sandbox API key and secret
    - Production API key and secret (after testing)
    
    ### 2. Integrate in Sandbox
    
    Use the sandbox environment to test your integration:
    - Base URL: `https://sandbox-api.hoopay.so/api/v1/partner`
    - Test with sandbox API credentials
    - Use test wallet IDs: `100001`, `100002`, `100003`
    
    ### 3. Go Live
    
    After successful testing:
    - Request production credentials
    - Update your integration to use production endpoints
    - Monitor transactions via Partner Dashboard
    
    ## Authentication
    
    All API requests require two headers:
    
    ```http
    X-API-Key: hpk_your_api_key_here
    X-Signature: hmac_sha256_signature
    ```
    
    See [Authentication Guide](#section/Authentication) for details.
    
    ## Response Format
    
    All responses follow a consistent format:
    
    **Success Response:**
    ```json
    {
      "success": true,
      "message": "Operation completed successfully",
      "data": { ... }
    }
    ```
    
    **Error Response:**
    ```json
    {
      "success": false,
      "error": {
        "code": "ERROR_CODE",
        "message": "Human-readable error message",
        "details": [ ... ]
      }
    }
    ```
    
    ## Rate Limiting
    
    - Default: **60 requests per minute** per partner
    - Rate limit headers included in all responses
    - Contact support for higher limits
    
    ## Support
    
    - **Email**: developers@hoopaywallet.com
    - **Documentation**: https://hoopaywallet.com/docs
    - **Status Page**: https://hoopaywallet.com/status
    
  version: 1.0.0
  termsOfService: https://hoopaywallet.com/terms
  contact:
    name: HooPay API Support
    email: developers@hoopaywallet.com
    url: https://hoopaywallet.com/support
  license:
    name: Proprietary
    url: https://hoopaywallet.com/api-terms
  x-logo:
    url: https://hoopaywallet.com/logo.png
    altText: HooPay

externalDocs:
  description: Full API Documentation
  url: https://hoopaywallet.com/docs

servers:
  - url: https://hoopaywallet.com/api/v1/partner
    description: Production & Sandbox (use sandbox API keys for testing)
  - url: http://localhost:8000/api/v1/partner
    description: Local Development

tags:
  - name: Deposits
    description: |
      **Partner → HooPay**
      
      Create deposits to credit funds into user wallets.
      
      [View Deposits API →](partner-deposits.yaml)
    externalDocs:
      url: ./partner-deposits.yaml
  
  - name: Withdrawals
    description: |
      **HooPay → Partner**
      
      Request withdrawals to transfer funds from HooPay to your platform.
      
      [View Withdrawals API →](partner-withdrawals.yaml)
    externalDocs:
      url: ./partner-withdrawals.yaml
  
  - name: Webhooks
    description: |
      **Real-time Event Notifications**
      
      Receive webhooks when transaction statuses change.
      
      [View Webhook Events →](webhooks.yaml)
    externalDocs:
      url: ./webhooks.yaml

# =============================================================================
# Security Section
# =============================================================================

security:
  - ApiKeyAuth: []
    HmacSignature: []

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: |
        Partner API key for authentication.
        
        **Format**: `hpk_` prefix followed by 32 alphanumeric characters
        
        **Example**: `hpk_EXAMPLE_API_KEY_REPLACE_WITH_YOUR_ACTUAL_KEY`
        
        **How to Obtain**:
        1. Register as a HooPay Partner
        2. Access Partner Dashboard
        3. Generate API keys in Settings
        
        **Security**:
        - Keep keys confidential
        - Use environment variables
        - Rotate keys periodically
        - Use separate keys for sandbox/production

    HmacSignature:
      type: apiKey
      in: header
      name: X-Signature
      description: |
        HMAC-SHA256 signature for request integrity verification.
        
        **Algorithm**: HMAC-SHA256
        
        **Steps**:
        1. Canonicalize JSON (sort keys, remove whitespace)
        2. Compute: `HMAC-SHA256(canonical_json, api_secret)`
        3. Encode as lowercase hex string
        
        **Example**:
        ```
        Input: {"amount":"100.00","currency":"USD"}
        Signature: a1b2c3d4e5f6...
        ```

# =============================================================================
# API Paths (References to individual spec files)
# =============================================================================

paths:
  # Pay User
  /pay-user:
    $ref: 'partner-deposits.yaml#/paths/~1pay-user'
  /pay-user/{reference_id}:
    $ref: 'partner-deposits.yaml#/paths/~1pay-user~1{reference_id}'
  
  # Collect From User
  /collect-from-user:
    $ref: 'partner-withdrawals.yaml#/paths/~1collect-from-user'
  /collect-from-user/stats:
    $ref: 'partner-withdrawals.yaml#/paths/~1collect-from-user~1stats'
  /collect-from-user/{reference}:
    $ref: 'partner-withdrawals.yaml#/paths/~1collect-from-user~1{reference}'
  /collect-from-user/{reference}/cancel:
    $ref: 'partner-withdrawals.yaml#/paths/~1collect-from-user~1{reference}~1cancel'

# =============================================================================
# Webhook Events (x-webhooks extension for OpenAPI 3.1 compatibility)
# =============================================================================

x-webhooks:
  deposit.completed:
    $ref: 'webhooks.yaml#/x-webhooks/deposit.completed'
  deposit.failed:
    $ref: 'webhooks.yaml#/x-webhooks/deposit.failed'
  withdrawal.completed:
    $ref: 'webhooks.yaml#/x-webhooks/withdrawal.completed'
  withdrawal.failed:
    $ref: 'webhooks.yaml#/x-webhooks/withdrawal.failed'
  refund.completed:
    $ref: 'webhooks.yaml#/x-webhooks/refund.completed'
  refund.failed:
    $ref: 'webhooks.yaml#/x-webhooks/refund.failed'

