openapi: 3.1.0
info:
  title: ChicksX Payments API
  version: 1.0.0
  description: >
    REST API that provides an interface to ChicksX cryptocurrency exchange
    ecosystem. This API enables merchants to offer their users cryptocurrency
    purchases, sales, and swaps through a simple integration.


    # Getting Started


    ### Prerequisites


    Before you can integrate with the ChicksX Payments API, you need to obtain
    your merchant credentials:


    - **x-api-key**: Your unique API key for authentication

    - **x-client-id**: Your merchant client identifier


    **Important**: If you don't have these credentials yet, please refer to your
    integration Discord thread and technology point of contact. As a last
    resort, contact our support team directly at support@chicksx.com.



    ### Security Notice


    🔒 **All endpoints requiring `x-api-key` and `x-client-id` headers MUST be
    called from your backend server only.** These credentials should never be
    exposed in client-side applications (web browsers, mobile apps, etc.) as
    they provide full access to your merchant account.


    # SDK Integration Flow


    To integrate the ChicksX SDK into your application, follow these steps:


    ### Step 1: Obtain Merchant Credentials


    Review your onboarding message in the Discord integration thread to gather:

    - `x-api-key`

    - `x-client-id`


    ### Step 2: Create a Public Access Token (Server-Side)


    From your **backend server**, make a request to create a public access
    token:


    ```bash

    POST https://develop-api.chicksx.com/v1/public_token/create

    Headers:
      x-api-key: your-api-key
      x-client-id: your-client-id
    ```


    This returns a public access token that can be safely used in your
    client-side application.


    ### Step 3: Embed the SDK Script (Client-Side)


    In your frontend application, add the ChicksX SDK script tag with the
    required parameters:


    ```html

    <script
    src="https://develop-api.chicksx.com/v1/sdk/chicksx.js?clientId=your-client-id&env=dev&baseCurrency=cad&targetCurrency=usdt&baseAmount=100&paymentMethod=interac"></script>

    ```


    Then configure and initialize the SDK:


    ```javascript

    window.chicksX.configure({
      clientId: 'your-client-id',
      env: 'dev',
      baseCurrency: 'cad',
      targetCurrency: 'usdt',
      baseAmount: 100,
      paymentMethod: 'interac',
      walletAddress: '0xYourWalletAddressOptional'
    });

    window.chicksX.init({ authenticationToken: 'your-public-token' });

    ```


    Note: `window.chicksX.init({ authenticationToken: 'your-public-token' })`
    opens the payment popup/modal. You typically want to call it in response to
    a user action (e.g., a button click) to avoid unexpected popups:


    ```javascript

    document.getElementById('payButton').addEventListener('click', function () {
      window.chicksX.init({ authenticationToken: 'your-public-token' });
    });

    ```


    ### Step 4: SDK Configuration Parameters


    **Required Parameters:**

    - `clientId` - Your merchant client identifier

    - `env` - Environment (`dev`, `staging`, or `prod`)

    - `authenticationToken` - The public token obtained from Step 2


    **Optional Parameters:**

    - `baseCurrency` - Source currency code or currency reference (default:
    based on merchant config)

    - `targetCurrency` - Target cryptocurrency code or currency reference
    (default: based on merchant config)

    - `baseAmount` - Amount in base currency

    - `targetAmount` - Amount in target currency

    - `paymentMethod` - Payment method identifier (e.g., `interac`, `paypal`)

    - `walletAddress` - Cryptocurrency wallet address


    # Webhooks


    ChicksX sends webhook notifications to your server when important events
    occur, such as order creation and fulfillment.


    ## Setting Up Webhooks


    For us to configure webhooks, refer to the **Discord integration thread**
    and provide:

    - Your webhook endpoint URL (must be HTTPS)

    - The environments you want to receive webhooks for (dev, staging, prod)


    ## Webhook Events


    - **OrderCreated** - A new order has been created

    - **OrderFulfillment** - An order has been fulfilled/completed


    ## Webhook Headers


    Every webhook request includes security headers for signature verification:


    - **X-Webhook-Id** *(string, UUID)* - Unique identifier for this webhook
    delivery

    - **X-Webhook-Timestamp** *(string)* - Unix timestamp (seconds) when the
    webhook was sent

    - **X-Webhook-Signature** *(string, hex)* - HMAC-SHA256 signature for
    verification


    ## Webhook Payload Structure


    ```json

    {
      "eventType": "OrderFulfillment",
      "sessionId": "your-session-id",
      "details": {
        "orderId": 1092114,
        "status": "completed",
        "paymentMethod": "Interac E-Transfer",
        "fulfilled": true,
        "totalPrice": 100.01,
        "totalPriceCurrency": "USD",
        "exchangeDetails": {
          "baseCurrency": "CAD",
          "amountReceived": 139.99,
          "targetCurrency": "BTC",
          "amountToSend": 0.00112180,
          "operationType": "S"
        }
      }
    }

    ```


    **Note**: The `sessionId` field contains the session identifier you provided
    when creating the access token. This value correlates the webhook event back
    to the specific session (and order) initiated from your platform.


    ## Signature Verification


    To verify webhook authenticity, you must compute an HMAC-SHA256 signature
    and compare it with the `X-Webhook-Signature` header. This ensures the
    webhook originated from ChicksX and hasn't been tampered with.


    ### Step-by-Step Verification Process


    **Step 1: Extract the headers from the incoming request**


    ```text

    X-Webhook-Id: a08d4ad3-0d83-4e41-ae85-1d03c7931615

    X-Webhook-Timestamp: 1769451142

    X-Webhook-Signature:
    e1945ff2e1d526c04072e37845b1181c2aaa787087bba7937824c4d7a22658cb

    ```


    **Step 2: Extract values from the JSON payload**


    ```json

    {
      "eventType": "OrderFulfillment",
      "details": {
        "orderId": 1092114
      }
    }

    ```


    **Step 3: Construct the signed data string**


    Concatenate the values with periods (`.`) in this exact order:


    ```text

    {webhookId}.{timestamp}.{eventType}.{orderId}

    ```


    Using our example values:


    ```text

    a08d4ad3-0d83-4e41-ae85-1d03c7931615.1769451142.OrderFulfillment.1092114

    ```


    **Step 4: Compute the HMAC-SHA256 hash**


    Using your webhook secret key (provided by ChicksX), compute the HMAC-SHA256
    hash of the signed data string:


    ```text

    HMAC-SHA256(secret, signedData)

    ```


    **Step 5: Convert to lowercase hexadecimal**


    Convert the resulting hash bytes to a lowercase hexadecimal string.


    **Step 6: Compare the signatures**


    Compare your computed signature with the `X-Webhook-Signature` header value.
    If they match, the webhook is authentic.


    ### Complete Example


    Given:

    - **Webhook Secret**: `my-webhook-secret`

    - **X-Webhook-Id**: `a08d4ad3-0d83-4e41-ae85-1d03c7931615`

    - **X-Webhook-Timestamp**: `1769451142`

    - **eventType**: `OrderFulfillment`

    - **orderId**: `1092114`


    **Signed data string:**


    ```text

    a08d4ad3-0d83-4e41-ae85-1d03c7931615.1769451142.OrderFulfillment.1092114

    ```


    **Computed signature:**


    ```text

    HMAC-SHA256("my-webhook-secret",
    "a08d4ad3-0d83-4e41-ae85-1d03c7931615.1769451142.OrderFulfillment.1092114")

    = e1945ff2e1d526c04072e37845b1181c2aaa787087bba7937824c4d7a22658cb

    ```


    ### Verification Example (Node.js)


    ```javascript

    const crypto = require('crypto');


    function verifyWebhookSignature(secret, webhookId, timestamp, eventType,
    orderId, receivedSignature) {
      // Step 3: Construct signed data
      const signedData = `${webhookId}.${timestamp}.${eventType}.${orderId}`;
      
      // Step 4 & 5: Compute HMAC-SHA256 and convert to hex
      const computedSignature = crypto
        .createHmac('sha256', secret)
        .update(signedData)
        .digest('hex');
      
      // Step 6: Compare signatures (use timing-safe comparison)
      return crypto.timingSafeEqual(
        Buffer.from(computedSignature),
        Buffer.from(receivedSignature.toLowerCase())
      );
    }


    // Usage in Express.js

    app.post('/webhook/chicksx', express.json(), (req, res) => {
      // Step 1: Extract headers
      const webhookId = req.headers['x-webhook-id'];
      const timestamp = req.headers['x-webhook-timestamp'];
      const signature = req.headers['x-webhook-signature'];
      
      // Step 2: Extract payload values
      const { eventType, details } = req.body;
      
      // Verify signature
      const isValid = verifyWebhookSignature(
        process.env.WEBHOOK_SECRET,
        webhookId,
        timestamp,
        eventType,
        details.orderId,
        signature
      );
      
      if (!isValid) {
        return res.status(401).send('Invalid signature');
      }
      
      // Process the webhook...
      res.status(200).send('OK');
    });

    ```


    ### Verification Example (C#)


    ```csharp

    using System.Security.Cryptography;

    using System.Text;


    public static bool VerifyWebhookSignature(
        string secret,
        string webhookId, 
        string timestamp,
        string eventType,
        long orderId,
        string receivedSignature)
    {
        // Step 3: Construct signed data
        var signedData = $"{webhookId}.{timestamp}.{eventType}.{orderId}";
        
        // Step 4: Compute HMAC-SHA256
        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
        var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(signedData));
        
        // Step 5: Convert to lowercase hex
        var computedSignature = Convert.ToHexString(hash).ToLowerInvariant();
        
        // Step 6: Compare signatures
        return computedSignature == receivedSignature.ToLowerInvariant();
    }

    ```


    ### Verification Example (Python)


    ```python

    import hmac

    import hashlib


    def verify_webhook_signature(secret, webhook_id, timestamp, event_type,
    order_id, received_signature):
        # Step 3: Construct signed data
        signed_data = f"{webhook_id}.{timestamp}.{event_type}.{order_id}"
        
        # Step 4 & 5: Compute HMAC-SHA256 and convert to hex
        computed_signature = hmac.new(
            secret.encode('utf-8'),
            signed_data.encode('utf-8'),
            hashlib.sha256
        ).hexdigest()
        
        # Step 6: Compare signatures (constant-time comparison)
        return hmac.compare_digest(computed_signature, received_signature.lower())
    ```


    ## Security Best Practices


    1. **Always verify signatures** - Never process webhooks without signature
    verification in production.

    2. **Use constant-time comparison** - Prevent timing attacks by using secure
    comparison functions.

    3. **Check timestamp freshness** - Reject webhooks older than 5 minutes to
    prevent replay attacks.

    4. **Use HTTPS only** - Ensure your webhook endpoint uses TLS/SSL.

    5. **Return 200 quickly** - Process webhooks asynchronously; acknowledge
    receipt immediately.

    6. **Store your secret securely** - Use environment variables or a secrets
    manager (Azure Key Vault, AWS Secrets Manager).


    # Test Data


    ## Card Payments


    Use the following test cards when paying with Debit/Credit. All listed cards
    support 3D Secure authentication, which is required for card payments.


    > **Sandbox only.** Do not enter real card details in the sandbox
    environment.


    | Network | Card Number | Scenario | 3DS Status |

    |:---|:---|:---|:---|

    | Visa | 4005519200000004 | Frictionless | Authenticated |

    | Visa | 4124939999999990 | Frictionless | Authenticated |

    | Visa | 4917300800000000 | Frictionless | Authenticated |

    | Mastercard | 5555341244441115 | Frictionless | Authenticated |

    | Mastercard | 5406004444444443 | Frictionless | Authenticated |

    | Mastercard | 5407721000353481 | Frictionless | Authenticated |

    | Amex | 370000000000002 | Frictionless | Authenticated |

    | Amex | 378282246310005 | Frictionless | Authenticated |


    ### Widget Fields


    Whenn widget prompts for card details, fill in the following:


    | Field | Value |

    |:---|:---|

    | Card Number | Any card number from the table above |

    | MM/YY | Any future expiry date (e.g. `12/26`) |

    | CVV | Any value (e.g. `123`) |

    | Address | Any address |

    | Frequency | One time |
  contact:
    name: ChicksX Support
    email: support@chicksx.com
  license:
    name: Proprietary
servers:
  - url: https://develop-api.chicksx.com/v1
    description: Development server
  - url: https://api.chicksx.com/v1
    description: Production server
components:
  parameters:
    MerchantApiKey:
      name: x-api-key
      in: header
      required: true
      schema:
        type: string
        default: your-api-key
      description: >-
        Your merchant API key (must be kept secure, never expose in client-side
        code)
      example: your-api-key
    MerchantClientId:
      name: x-client-id
      in: header
      required: true
      schema:
        type: string
        default: your-client-id
      description: >-
        Your merchant client identifier (must be kept secure, never expose in
        client-side code)
      example: your-client-id
  schemas:
    ApiResponse:
      type: object
      properties:
        code:
          type: string
          description: Result code indicating the operation status
          example: OK
        data:
          type: object
          description: Response data payload
        message:
          type: string
          description: Human-readable response message
          example: Operation completed successfully
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: INVALID_INPUT
        message:
          type: string
          description: Error message
          example: Invalid JSON in request body
    PublicTokenRequest:
      type: object
      required:
        - sessionId
      properties:
        scope:
          type: array
          items:
            type: string
          description: Array of permission scopes for the token
          example:
            - wallet.read
            - merchant.read
        sessionId:
          type: string
          description: >
            Unique session identifier that correlates this public token to a
            single order. Each session must map to exactly one order — once an
            order has been placed, the session expires and cannot be reused. If
            a user attempts to start another order within the same session, they
            will be prompted to restart the process from your platform.
          example: session-123abc
    PublicTokenResponse:
      type: object
      properties:
        accessToken:
          type: string
          description: JWT access token for SDK authentication
          example: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
        tokenType:
          type: string
          description: Token type
          example: Bearer
        expiresIn:
          type: integer
          description: Token lifetime in seconds
          example: 3600
        expiresAt:
          type: integer
          description: Unix timestamp when token expires
          example: 1696531200
        scope:
          type: array
          items:
            type: string
          description: Granted permission scopes
          example:
            - wallet.read
            - merchant.read
        jti:
          type: string
          description: Unique token identifier (JWT ID)
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
    WalletRequest:
      type: object
      required:
        - walletAddress
        - currencyCode
      properties:
        walletAddress:
          type: string
          description: Cryptocurrency wallet address
          example: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
        currencyCode:
          type: string
          description: Currency code (e.g., BTC, ETH, USDT)
          example: USDT
        networkCode:
          type: string
          description: Blockchain network code (e.g., ERC20, TRC20, BEP20)
          example: ERC20
    WalletResponse:
      type: object
      properties:
        id:
          type: integer
          description: Unique wallet identifier
          example: 1001
        user:
          type: object
          properties:
            firstName:
              type: string
              example: John
            lastName:
              type: string
              example: Doe
        walletAddress:
          type: string
          description: Cryptocurrency wallet address
          example: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
        currencyCode:
          type: string
          description: Currency code
          example: USDT
        networkCode:
          type: string
          description: Network code
          example: ERC20
    WalletLookupResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the lookup was successful
          example: true
        message:
          type: string
          description: Result message
          example: Wallet found
        wallet:
          oneOf:
            - $ref: '#/components/schemas/WalletResponse'
            - type: 'null'
        availableNetworks:
          type: array
          items:
            type: string
          description: List of available networks for this currency
          example:
            - ERC20
            - TRC20
            - BEP20
        requiresNetworkCode:
          type: boolean
          description: Whether network code is required for this currency
          example: true
    WebhookPayload:
      type: object
      description: Webhook event payload sent to your endpoint
      properties:
        eventType:
          type: string
          enum:
            - OrderCreated
            - OrderFulfillment
          description: Type of event that triggered the webhook
          example: OrderFulfillment
        sessionId:
          type: string
          description: >-
            Session identifier provided when creating the access token.
            Correlates this event to the specific order placed within that
            session.
          example: user-session-abc123
        details:
          $ref: '#/components/schemas/WebhookOrderDetails'
    WebhookOrderDetails:
      type: object
      description: Order details included in webhook payload
      properties:
        orderId:
          type: integer
          description: Unique order identifier
          example: 1092114
        status:
          type: string
          description: Current order status
          example: completed
        paymentMethod:
          type: string
          description: Payment method used for the order
          example: Interac E-Transfer
        fulfilled:
          type: boolean
          description: Whether the order has been fulfilled
          example: true
        totalPrice:
          type: number
          description: Total price of the order
          example: 100.01
        totalPriceCurrency:
          type: string
          description: Currency of the total price
          example: USD
        exchangeDetails:
          $ref: '#/components/schemas/WebhookExchangeDetails'
    WebhookExchangeDetails:
      type: object
      description: Exchange details for the order
      properties:
        baseCurrency:
          type: string
          description: Source currency code
          example: CAD
        amountReceived:
          type: number
          description: Amount received in base currency
          example: 139.99
        targetCurrency:
          type: string
          description: Target cryptocurrency code
          example: BTC
        amountToSend:
          type: number
          description: Amount to send in target currency
          example: 0.0011218
        operationType:
          type: string
          description: >-
            Type of operation (e.g. S = Sell, B = Buy, FF = Fiat to Fiat, CC =
            Crypto to Crypto)
          example: S
    WebhookHeaders:
      type: object
      description: Security headers included with every webhook request
      properties:
        X-Webhook-Id:
          type: string
          format: uuid
          description: Unique identifier for this webhook delivery
          example: a08d4ad3-0d83-4e41-ae85-1d03c7931615
        X-Webhook-Timestamp:
          type: string
          description: Unix timestamp (seconds) when the webhook was sent
          example: '1769451142'
        X-Webhook-Signature:
          type: string
          description: HMAC-SHA256 signature for payload verification (lowercase hex)
          example: e1945ff2e1d526c04072e37845b1181c2aaa787087bba7937824c4d7a22658cb
    PaymentMethodItem:
      type: object
      description: A single payment method available for the merchant
      properties:
        id:
          type: integer
          description: Payment method identifier
          example: 7
        live:
          type: boolean
          description: Whether this method is live (vs test)
          example: true
        name:
          type: string
          description: Display name of the payment method
          example: Interac E-Transfer
        reference:
          type: string
          description: Reference key for the payment method (e.g. for SDK)
          example: interac
    CurrencyItem:
      type: object
      description: A single currency (crypto or fiat)
      properties:
        id:
          type: integer
          description: Currency identifier
          example: 1
        code:
          type: string
          description: Currency code (e.g. USDT, USD)
          example: USDT
        description:
          type: string
          description: Full description of the currency
          example: Tether (Omni)
        shortName:
          type:
            - string
            - 'null'
          description: Short display name (null for crypto)
          example: null
        symbol:
          type: string
          description: Currency symbol
          example: USDT
        type:
          type: string
          description: Currency type (C = Crypto, F = Fiat)
          example: C
        reference:
          type:
            - string
            - 'null'
          description: >-
            Unique reference key for the currency. Can be used as the value for
            `targetCurrency` or `baseCurrency` in the SDK initialization.
          example: tether-omni-coinpayments
    ExchangeCurrenciesData:
      type: object
      description: Receive and spend currencies for exchange
      properties:
        receiveCurrencies:
          type: array
          items:
            $ref: '#/components/schemas/CurrencyItem'
          description: Cryptocurrencies that can be received
        spendCurrencies:
          type: array
          items:
            $ref: '#/components/schemas/CurrencyItem'
          description: Fiat (or spend) currencies
    ExchangeQuoteRequest:
      type: object
      description: Request body for exchange quote calculation
      required:
        - operationType
        - baseCurrencyId
        - baseAmount
        - targetCurrencyId
        - paymentMethodId
      properties:
        operationType:
          type: string
          description: >-
            Type of operation (e.g. S = Sell, B = Buy, FF = Fiat to Fiat, CC =
            Crypto to Crypto)
          example: B
        baseCurrencyId:
          type: integer
          description: Base (spend) currency identifier
          example: 22
        baseAmount:
          type: number
          description: Amount in base (spend) currency
          example: 100
        targetCurrencyId:
          type: integer
          description: Target (receive) currency identifier
          example: 1
        paymentMethodId:
          type: integer
          description: Payment method identifier
          example: 7
        deliveryMethodId:
          type: integer
          description: Optional delivery method identifier
          example: 1
    ExchangeQuoteData:
      type: object
      description: Quote details for an exchange
      properties:
        spend:
          type: object
          properties:
            amount:
              type: number
              example: 100
            currencyCode:
              type: string
              example: CAD
            currencyReference:
              type:
                - string
                - 'null'
              example: null
        transactionFee:
          type: object
          properties:
            amount:
              type: number
              example: 8.1
            currencyCode:
              type: string
              example: USDT
        receive:
          type: object
          properties:
            amount:
              type: number
              example: 65.56
            currencyCode:
              type: string
              example: USDT
            currencyReference:
              type: string
              example: tether-omni-coinpayments
        delivery:
          type: object
          properties:
            fee:
              type: object
              properties:
                amount:
                  type: number
                  example: 0
                currencyCode:
                  type: string
                  example: USDT
            time:
              type: object
              properties:
                minDays:
                  type:
                    - integer
                    - 'null'
                  example: null
                maxDays:
                  type:
                    - integer
                    - 'null'
                  example: null
        paymentMethod:
          type: object
          properties:
            id:
              type: integer
              example: 7
            name:
              type: string
              example: Interac E-Transfer
            reference:
              type: string
              example: interac
        receivePaymentMethod:
          type: object
          properties:
            id:
              type: integer
              example: 7
            name:
              type: string
              example: Interac E-Transfer
            reference:
              type: string
              example: interac
        rate:
          type: number
          description: Effective exchange rate (target/base)
          example: 0.74
paths:
  /public_token/create:
    post:
      summary: Create public access token
      description: >
        Creates a public access token for SDK authentication. This endpoint must
        be called from your **secure backend server** using your merchant
        credentials.


        The returned access token can be safely used in client-side applications
        to authenticate with the ChicksX SDK.


        **Session and order correlation**: A `sessionId` is required and ties
        each public token to exactly one order. Once an order has been placed,
        the session expires and cannot be reused. If a user attempts to place
        another order within the same session, they will see a message
        indicating the session has expired and must restart the checkout process
        from your platform.


        **Security**: Never expose your x-api-key or x-client-id in client-side
        code.
      operationId: createPublicToken
      tags:
        - SDK Authentication
        - Merchant
      parameters:
        - $ref: '#/components/parameters/MerchantApiKey'
        - $ref: '#/components/parameters/MerchantClientId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicTokenRequest'
            examples:
              default:
                summary: Create token with session
                value:
                  scope:
                    - wallet.read
                    - merchant.read
                  sessionId: user-session-abc123
      responses:
        '201':
          description: Public token created successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/PublicTokenResponse'
              examples:
                success:
                  summary: Successful token creation
                  value:
                    code: OK
                    data:
                      accessToken: >-
                        eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJjaGlja3N4LWFwaSIsInN1YiI6Im1lcmNoYW50LWRlbW8iLCJhdWQiOiJjaGlja3N4LXNkayIsImV4cCI6MTY5NjUzNDgwMCwiaWF0IjoxNjk2NTMxMjAwLCJqdGkiOiJmNDdhYzEwYi01OGNjLTQzNzItYTU2Ny0wZTAyYjJjM2Q0NzkiLCJlbnZpcm9ubWVudCI6InNhbmRib3giLCJzY29wZSI6WyJ3YWxsZXQucmVhZCIsIm1lcmNoYW50LnJlYWQiXX0.signature
                      tokenType: Bearer
                      expiresIn: 3600
                      expiresAt: 1696534800
                      scope:
                        - wallet.read
                        - merchant.read
                      jti: f47ac10b-58cc-4372-a567-0e02b2c3d479
        '400':
          description: Bad request - Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidJson:
                  summary: Invalid JSON
                  value:
                    code: INVALID_INPUT
                    message: Invalid JSON in request body
        '401':
          description: Unauthorized - Invalid or missing merchant credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                serverError:
                  summary: Token generation failed
                  value:
                    message: Token generation failed
  /sdk/chicksx.js:
    get:
      summary: Get ChicksX SDK Script
      description: >
        Retrieves the ChicksX SDK JavaScript file with embedded configuration.
        This script should be embedded in your client-side application using a
        `<script>` tag.


        **This endpoint does not require merchant authentication headers** as
        it's meant to be called from client-side applications.


        ### Example Usage


        ```html

        <script
        src="https://develop-api.chicksx.com/v1/sdk/chicksx.js?clientId=demo-merchant&env=dev&baseCurrency=cad&targetCurrency=usdt&baseAmount=100&paymentMethod=interac"></script>

        ```
      operationId: getSdkScript
      tags:
        - SDK
      security: []
      parameters:
        - name: clientId
          in: query
          required: true
          schema:
            type: string
          description: Your client ID
          example: demo-merchant
        - name: env
          in: query
          required: true
          schema:
            type: string
            enum:
              - dev
              - staging
              - prod
          description: Target environment
          example: dev
        - name: baseCurrency
          in: query
          required: false
          schema:
            type: string
          description: Source currency code or currency reference
          example: cad
        - name: targetCurrency
          in: query
          required: false
          schema:
            type: string
          description: Target cryptocurrency code or currency reference
          example: usdt
        - name: baseAmount
          in: query
          required: false
          schema:
            type: number
          description: Amount in base currency
          example: 100
        - name: targetAmount
          in: query
          required: false
          schema:
            type: number
          description: Amount in target currency
          example: 73.45
        - name: paymentMethod
          in: query
          required: false
          schema:
            type: string
          description: Payment method identifier (e.g., interac, paypal, cash-in-mail)
          example: interac
        - name: walletAddress
          in: query
          required: false
          schema:
            type: string
          description: Cryptocurrency wallet address
          example: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
      responses:
        '200':
          description: SDK script returned successfully
          content:
            application/javascript:
              schema:
                type: string
                description: JavaScript SDK code with embedded configuration
        '500':
          description: Error serving script
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Error serving script
  /payment-methods:
    get:
      summary: Get payment methods
      description: >
        Returns the list of payment methods available for the given operation
        type and country. Requires merchant authentication (x-api-key,
        x-client-id).
      operationId: getPaymentMethods
      tags:
        - Merchant
      parameters:
        - $ref: '#/components/parameters/MerchantApiKey'
        - $ref: '#/components/parameters/MerchantClientId'
        - name: operationType
          in: query
          required: true
          schema:
            type: string
            description: >-
              Operation type (e.g. S = Sell, B = Buy, FF = Fiat to Fiat, CC =
              Crypto to Crypto)
            example: S
        - name: countryCode
          in: query
          required: true
          schema:
            type: string
            description: ISO country code (e.g. US, CA)
            example: US
        - name: includeDeliveryMethods
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
            description: Include delivery method details
      responses:
        '200':
          description: List of payment methods
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  code:
                    type: string
                    example: ok
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentMethodItem'
              examples:
                success:
                  summary: Payment methods (mock)
                  value:
                    success: true
                    code: ok
                    data:
                      - id: 7
                        live: true
                        name: Interac E-Transfer
                        reference: interac
                      - id: 78
                        live: true
                        name: Cash in Mail
                        reference: cash-in-mail
                      - id: 6
                        live: true
                        name: Western Union
                        reference: western-union
        '400':
          description: Bad request - Invalid input or missing required params
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid merchant credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /exchange/currencies:
    get:
      summary: Get exchange currencies
      description: >
        Returns receive (crypto) and spend (fiat) currencies available for
        exchange. Requires merchant authentication (x-api-key, x-client-id).
      operationId: getExchangeCurrencies
      tags:
        - Merchant
      parameters:
        - $ref: '#/components/parameters/MerchantApiKey'
        - $ref: '#/components/parameters/MerchantClientId'
        - name: operationType
          in: query
          required: true
          schema:
            type: string
            description: >-
              Operation type (e.g. S = Sell, B = Buy, FF = Fiat to Fiat, CC =
              Crypto to Crypto)
            example: S
        - name: countryCode
          in: query
          required: true
          schema:
            type: string
            description: ISO country code (e.g. US, CA)
            example: US
      responses:
        '200':
          description: Receive and spend currencies
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  code:
                    type: string
                    example: ok
                  data:
                    $ref: '#/components/schemas/ExchangeCurrenciesData'
              examples:
                success:
                  summary: Exchange currencies (mock)
                  value:
                    success: true
                    code: ok
                    data:
                      receiveCurrencies:
                        - id: 1
                          code: USDT
                          description: Tether (Omni)
                          shortName: null
                          symbol: USDT
                          type: C
                          reference: tether-omni-coinpayments
                        - id: 4
                          code: LINK
                          description: Chainlink
                          shortName: null
                          symbol: LINK
                          type: C
                          reference: chainlink
                        - id: 5
                          code: DOGE
                          description: Dogecoin
                          shortName: null
                          symbol: DOGE
                          type: C
                          reference: dogecoin
                      spendCurrencies:
                        - id: 21
                          code: USD
                          description: United States Dollar
                          shortName: US Dollar
                          symbol: $
                          type: F
                          reference: null
                        - id: 22
                          code: CAD
                          description: Canadian Dollar
                          shortName: CA Dollar
                          symbol: C$
                          type: F
                          reference: null
                        - id: 23
                          code: EUR
                          description: European Euro
                          shortName: EU Euro
                          symbol: €
                          type: F
                          reference: null
        '400':
          description: Bad request - Invalid input or missing required params
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid merchant credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /exchange/quotes:
    post:
      summary: Calculate exchange quote
      description: >
        Calculates an exchange quote for a given operation, currencies, amount
        and payment method. Requires merchant authentication (x-api-key,
        x-client-id).
      operationId: calculateExchangeQuote
      tags:
        - Merchant
      parameters:
        - $ref: '#/components/parameters/MerchantApiKey'
        - $ref: '#/components/parameters/MerchantClientId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExchangeQuoteRequest'
            examples:
              default:
                summary: Calculate quote (mock)
                value:
                  operationType: B
                  baseCurrencyId: 22
                  baseAmount: 100
                  targetCurrencyId: 1
                  paymentMethodId: 7
      responses:
        '200':
          description: Exchange quote calculated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  code:
                    type: string
                    example: ok
                  data:
                    $ref: '#/components/schemas/ExchangeQuoteData'
              examples:
                success:
                  summary: Exchange quote (mock)
                  value:
                    success: true
                    code: ok
                    data:
                      spend:
                        amount: 100
                        currencyCode: CAD
                        currencyReference: null
                      transactionFee:
                        amount: 8.1
                        currencyCode: USDT
                      receive:
                        amount: 65.56
                        currencyCode: USDT
                        currencyReference: tether-omni-coinpayments
                      delivery:
                        fee:
                          amount: 0
                          currencyCode: USDT
                        time:
                          minDays: null
                          maxDays: null
                      paymentMethod:
                        id: 7
                        name: Interac E-Transfer
                        reference: interac
                      receivePaymentMethod:
                        id: 7
                        name: Interac E-Transfer
                        reference: interac
                      rate: 0.74
        '400':
          description: Bad request - Invalid input or missing required fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid merchant credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
tags:
  - name: SDK Authentication
    description: Endpoints for SDK authentication and token management
  - name: SDK
    description: SDK script delivery
  - name: Merchant
    description: Merchant endpoints for payment methods and exchange currencies
