{ "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.\n\n# Getting Started\n\n### Prerequisites\n\nBefore you can integrate with the ChicksX Payments API, you need to obtain your merchant credentials:\n\n- **merchant-api-key**: Your unique API key for authentication\n- **merchant-client-id**: Your merchant client identifier\n\n**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.\n\n\n### Security Notice\n\nšŸ”’ **All endpoints requiring `merchant-api-key` and `merchant-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.\n\n# SDK Integration Flow\n\nTo integrate the ChicksX SDK into your application, follow these steps:\n\n### Step 1: Obtain Merchant Credentials\n\nReview your onboarding message in the Discord integration thread to gather:\n- `merchant-api-key`\n- `merchant-client-id`\n\n### Step 2: Create a Public Access Token (Server-Side)\n\nFrom your **backend server**, make a request to create a public access token:\n\n```bash\nPOST https://develop-api.chicksx.com/v1/public_token/create\nHeaders:\n merchant-api-key: your-api-key\n merchant-client-id: your-client-id\n```\n\nThis returns a public access token that can be safely used in your client-side application.\n\n### Step 3: Embed the SDK Script (Client-Side)\n\nIn your frontend application, add the ChicksX SDK script tag with the required parameters:\n\n```html\n\n```\n\nThen configure and initialize the SDK:\n\n```javascript\nwindow.chicksX.configure({\n merchantId: 'your-merchant-id',\n env: 'dev',\n accessToken: 'your-public-token',\n baseCurrency: 'cad',\n targetCurrency: 'usdt',\n baseAmount: 100,\n paymentMethod: 'interac',\n walletAddress: '0xYourWalletAddressOptional'\n});\nwindow.chicksX.init();\n```\n\nNote: `window.chicksX.init()` 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:\n\n```javascript\ndocument.getElementById('payButton').addEventListener('click', function () {\n window.chicksX.init();\n});\n```\n\n### Step 4: SDK Configuration Parameters\n\n**Required Parameters:**\n- `merchantId` - Your merchant identifier\n- `env` - Environment (`dev`, `staging`, or `prod`)\n- `accessToken` - The public token obtained from Step 2\n\n**Optional Parameters:**\n- `baseCurrency` - Source currency code (default: based on merchant config)\n- `targetCurrency` - Target cryptocurrency code (default: based on merchant config)\n- `baseAmount` - Amount in base currency\n- `targetAmount` - Amount in target currency\n- `paymentMethod` - Payment method identifier (e.g., `interac`, `paypal`)\n- `walletAddress` - Cryptocurrency wallet address\n\n# Webhooks\n\nChicksX sends webhook notifications to your server when important events occur, such as order creation and fulfillment.\n\n## Setting Up Webhooks\n\nFor us to configure webhooks, refer to the **Discord integration thread** and provide:\n- Your webhook endpoint URL (must be HTTPS)\n- The environments you want to receive webhooks for (dev, staging, prod)\n\n## Webhook Events\n\n- **OrderCreated** - A new order has been created\n- **OrderFulfillment** - An order has been fulfilled/completed\n\n## Webhook Headers\n\nEvery webhook request includes security headers for signature verification:\n\n- **X-Webhook-Id** *(string, UUID)* - Unique identifier for this webhook delivery\n- **X-Webhook-Timestamp** *(string)* - Unix timestamp (seconds) when the webhook was sent\n- **X-Webhook-Signature** *(string, hex)* - HMAC-SHA256 signature for verification\n\n## Webhook Payload Structure\n\n```json\n{\n \"eventType\": \"OrderFulfillment\",\n \"sessionId\": \"your-session-id-or-null\",\n \"details\": {\n \"orderId\": 1092114,\n \"status\": \"completed\",\n \"paymentMethod\": \"Interac E-Transfer\",\n \"fulfilled\": true,\n \"totalPrice\": 100.01,\n \"totalPriceCurrency\": \"USD\",\n \"exchangeDetails\": {\n \"baseCurrency\": \"CAD\",\n \"amountReceived\": 139.99,\n \"targetCurrency\": \"BTC\",\n \"amountToSend\": 0.00112180,\n \"operationType\": \"S\"\n }\n }\n}\n```\n\n**Note**: The `sessionId` field contains the session identifier you provided when creating the access token. If no sessionId was provided, this field will be `null`.\n\n## Signature Verification\n\nTo 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.\n\n### Step-by-Step Verification Process\n\n**Step 1: Extract the headers from the incoming request**\n\n```text\nX-Webhook-Id: a08d4ad3-0d83-4e41-ae85-1d03c7931615\nX-Webhook-Timestamp: 1769451142\nX-Webhook-Signature: e1945ff2e1d526c04072e37845b1181c2aaa787087bba7937824c4d7a22658cb\n```\n\n**Step 2: Extract values from the JSON payload**\n\n```json\n{\n \"eventType\": \"OrderFulfillment\",\n \"details\": {\n \"orderId\": 1092114\n }\n}\n```\n\n**Step 3: Construct the signed data string**\n\nConcatenate the values with periods (`.`) in this exact order:\n\n```text\n{webhookId}.{timestamp}.{eventType}.{orderId}\n```\n\nUsing our example values:\n\n```text\na08d4ad3-0d83-4e41-ae85-1d03c7931615.1769451142.OrderFulfillment.1092114\n```\n\n**Step 4: Compute the HMAC-SHA256 hash**\n\nUsing your webhook secret key (provided by ChicksX), compute the HMAC-SHA256 hash of the signed data string:\n\n```text\nHMAC-SHA256(secret, signedData)\n```\n\n**Step 5: Convert to lowercase hexadecimal**\n\nConvert the resulting hash bytes to a lowercase hexadecimal string.\n\n**Step 6: Compare the signatures**\n\nCompare your computed signature with the `X-Webhook-Signature` header value. If they match, the webhook is authentic.\n\n### Complete Example\n\nGiven:\n- **Webhook Secret**: `my-webhook-secret`\n- **X-Webhook-Id**: `a08d4ad3-0d83-4e41-ae85-1d03c7931615`\n- **X-Webhook-Timestamp**: `1769451142`\n- **eventType**: `OrderFulfillment`\n- **orderId**: `1092114`\n\n**Signed data string:**\n\n```text\na08d4ad3-0d83-4e41-ae85-1d03c7931615.1769451142.OrderFulfillment.1092114\n```\n\n**Computed signature:**\n\n```text\nHMAC-SHA256(\"my-webhook-secret\", \"a08d4ad3-0d83-4e41-ae85-1d03c7931615.1769451142.OrderFulfillment.1092114\")\n= e1945ff2e1d526c04072e37845b1181c2aaa787087bba7937824c4d7a22658cb\n```\n\n### Verification Example (Node.js)\n\n```javascript\nconst crypto = require('crypto');\n\nfunction verifyWebhookSignature(secret, webhookId, timestamp, eventType, orderId, receivedSignature) {\n // Step 3: Construct signed data\n const signedData = `${webhookId}.${timestamp}.${eventType}.${orderId}`;\n \n // Step 4 & 5: Compute HMAC-SHA256 and convert to hex\n const computedSignature = crypto\n .createHmac('sha256', secret)\n .update(signedData)\n .digest('hex');\n \n // Step 6: Compare signatures (use timing-safe comparison)\n return crypto.timingSafeEqual(\n Buffer.from(computedSignature),\n Buffer.from(receivedSignature.toLowerCase())\n );\n}\n\n// Usage in Express.js\napp.post('/webhook/chicksx', express.json(), (req, res) => {\n // Step 1: Extract headers\n const webhookId = req.headers['x-webhook-id'];\n const timestamp = req.headers['x-webhook-timestamp'];\n const signature = req.headers['x-webhook-signature'];\n \n // Step 2: Extract payload values\n const { eventType, details } = req.body;\n \n // Verify signature\n const isValid = verifyWebhookSignature(\n process.env.WEBHOOK_SECRET,\n webhookId,\n timestamp,\n eventType,\n details.orderId,\n signature\n );\n \n if (!isValid) {\n return res.status(401).send('Invalid signature');\n }\n \n // Process the webhook...\n res.status(200).send('OK');\n});\n```\n\n### Verification Example (C#)\n\n```csharp\nusing System.Security.Cryptography;\nusing System.Text;\n\npublic static bool VerifyWebhookSignature(\n string secret,\n string webhookId, \n string timestamp,\n string eventType,\n long orderId,\n string receivedSignature)\n{\n // Step 3: Construct signed data\n var signedData = $\"{webhookId}.{timestamp}.{eventType}.{orderId}\";\n \n // Step 4: Compute HMAC-SHA256\n using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));\n var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(signedData));\n \n // Step 5: Convert to lowercase hex\n var computedSignature = Convert.ToHexString(hash).ToLowerInvariant();\n \n // Step 6: Compare signatures\n return computedSignature == receivedSignature.ToLowerInvariant();\n}\n```\n\n### Verification Example (Python)\n\n```python\nimport hmac\nimport hashlib\n\ndef verify_webhook_signature(secret, webhook_id, timestamp, event_type, order_id, received_signature):\n # Step 3: Construct signed data\n signed_data = f\"{webhook_id}.{timestamp}.{event_type}.{order_id}\"\n \n # Step 4 & 5: Compute HMAC-SHA256 and convert to hex\n computed_signature = hmac.new(\n secret.encode('utf-8'),\n signed_data.encode('utf-8'),\n hashlib.sha256\n ).hexdigest()\n \n # Step 6: Compare signatures (constant-time comparison)\n return hmac.compare_digest(computed_signature, received_signature.lower())\n```\n\n## Security Best Practices\n\n1. **Always verify signatures** - Never process webhooks without signature verification in production.\n2. **Use constant-time comparison** - Prevent timing attacks by using secure comparison functions.\n3. **Check timestamp freshness** - Reject webhooks older than 5 minutes to prevent replay attacks.\n4. **Use HTTPS only** - Ensure your webhook endpoint uses TLS/SSL.\n5. **Return 200 quickly** - Process webhooks asynchronously; acknowledge receipt immediately.\n6. **Store your secret securely** - Use environment variables or a secrets manager (Azure Key Vault, AWS Secrets Manager).\n", "contact": { "name": "ChicksX Support", "email": "support@chicksx.com" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://develop-api.chicksx.com/v1", "description": "Development server" }, { "url": "https://staging-api.chicksx.com/v1", "description": "Staging server" }, { "url": "https://api.chicksx.com/v1", "description": "Production server" } ], "security": [ { "MerchantAuth": [] } ], "components": { "securitySchemes": { "MerchantAuth": { "type": "apiKey", "in": "header", "name": "merchant-api-key", "description": "Merchant API authentication requires two headers:\n- `merchant-api-key`: Your API key\n- `merchant-client-id`: Your client ID\n\n**Security Warning**: Never expose these credentials in client-side code. Use only from secure backend servers.\n" } }, "parameters": { "MerchantClientId": { "name": "merchant-client-id", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Your merchant client identifier (must be kept secure)" } }, "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", "properties": { "scope": { "type": "array", "items": { "type": "string" }, "description": "Array of permission scopes for the token", "example": [ "wallet.read", "merchant.read" ] }, "sessionId": { "type": "string", "description": "Optional session identifier for tracking", "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", "null" ], "description": "Session identifier provided when creating the access token (null if not provided)", "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" } } }, "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.\n\nThe returned access token can be safely used in client-side applications to authenticate with the ChicksX SDK.\n\n**Security**: Never expose your merchant-api-key or merchant-client-id in client-side code.\n", "operationId": "createPublicToken", "tags": [ "SDK Authentication" ], "security": [ { "MerchantAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/MerchantClientId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicTokenRequest" }, "examples": { "defaultScopes": { "summary": "Default scopes", "value": { "scope": [ "wallet.read", "merchant.read" ] } }, "withSession": { "summary": "With session tracking", "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 `\n```\n", "operationId": "getSdkScript", "tags": [ "SDK" ], "security": [], "parameters": [ { "name": "merchantId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Your merchant identifier", "example": "demo-merchant" }, { "name": "env", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "dev", "staging", "prod" ] }, "description": "Target environment", "example": "dev" }, { "name": "accessToken", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Public access token obtained from /public_token/create endpoint", "example": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." }, { "name": "baseCurrency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Source currency code (fiat)", "example": "cad" }, { "name": "targetCurrency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Target cryptocurrency code", "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 (merchant-api-key, merchant-client-id) and optionally an Authorization Bearer token (SDK JWT).\n", "operationId": "getPaymentMethods", "tags": [ "Merchant" ], "security": [ { "MerchantAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/MerchantClientId" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "description": "Bearer JWT from public token (optional for server-to-server)" }, "example": "eyJhbGciOiJSUzI1NiIsImtpZCI6InNkay1rZXktMjAyNS0wMyJ9..." }, { "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 (merchant-api-key, merchant-client-id) and optionally an Authorization Bearer token (SDK JWT).\n", "operationId": "getExchangeCurrencies", "tags": [ "Merchant" ], "security": [ { "MerchantAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/MerchantClientId" }, { "name": "Authorization", "in": "header", "required": false, "schema": { "type": "string", "description": "Bearer JWT from public token (optional for server-to-server)" }, "example": "eyJhbGciOiJSUzI1NiIsImtpZCI6InNkay1rZXktMjAyNS0wMyJ9..." }, { "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" }, { "id": 4, "code": "LINK", "description": "Chainlink", "shortName": null, "symbol": "LINK", "type": "C" }, { "id": 5, "code": "DOGE", "description": "Dogecoin", "shortName": null, "symbol": "DOGE", "type": "C" } ], "spendCurrencies": [ { "id": 21, "code": "USD", "description": "United States Dollar", "shortName": "US Dollar", "symbol": "$", "type": "F" }, { "id": 22, "code": "CAD", "description": "Canadian Dollar", "shortName": "CA Dollar", "symbol": "C$", "type": "F" }, { "id": 23, "code": "EUR", "description": "European Euro", "shortName": "EU Euro", "symbol": "ā‚¬", "type": "F" } ] } } } } } } }, "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 (merchant-api-key, merchant-client-id).\n", "operationId": "calculateExchangeQuote", "tags": [ "Merchant" ], "security": [ { "MerchantAuth": [] } ], "parameters": [ { "$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" } ] }