Skip to content

ChicksX Payments API (1.0.0)

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:

  • merchant-api-key: Your unique API key for authentication
  • merchant-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 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.

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:

  • merchant-api-key
  • merchant-client-id

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

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

POST https://develop-api.chicksx.com/v1/public_token/create
Headers:
  merchant-api-key: your-api-key
  merchant-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:

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

Then configure and initialize the SDK:

window.chicksX.configure({
  merchantId: 'your-merchant-id',
  env: 'dev',
  accessToken: 'your-public-token',
  baseCurrency: 'cad',
  targetCurrency: 'usdt',
  baseAmount: 100,
  paymentMethod: 'interac',
  walletAddress: '0xYourWalletAddressOptional'
});
window.chicksX.init();

Note: 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:

document.getElementById('payButton').addEventListener('click', function () {
  window.chicksX.init();
});

Step 4: SDK Configuration Parameters

Required Parameters:

  • merchantId - Your merchant identifier
  • env - Environment (dev, staging, or prod)
  • accessToken - The public token obtained from Step 2

Optional Parameters:

  • baseCurrency - Source currency code (default: based on merchant config)
  • targetCurrency - Target cryptocurrency code (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

{
  "eventType": "OrderFulfillment",
  "sessionId": "your-session-id-or-null",
  "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. If no sessionId was provided, this field will be null.

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

X-Webhook-Id: a08d4ad3-0d83-4e41-ae85-1d03c7931615
X-Webhook-Timestamp: 1769451142
X-Webhook-Signature: e1945ff2e1d526c04072e37845b1181c2aaa787087bba7937824c4d7a22658cb

Step 2: Extract values from the JSON payload

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

Step 3: Construct the signed data string

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

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

Using our example values:

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:

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:

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

Computed signature:

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

Verification Example (Node.js)

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#)

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)

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).
Download OpenAPI description
openapi.json
openapi.yaml
Overview
ChicksX Support
support@chicksx.com
License
Proprietary
Languages
Servers
Mock server
https://chicksx-payments-api.redocly.app/_mock/apis/openapi
Development server
https://develop-api.chicksx.com/v1
Staging server
https://staging-api.chicksx.com/v1
Production server
https://api.chicksx.com/v1

SDK Authentication

Endpoints for SDK authentication and token management

Operations

Create public access token

Request

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.

Security: Never expose your merchant-api-key or merchant-client-id in client-side code.

Security
MerchantAuth
Headers
merchant-client-idstringrequired

Your merchant client identifier (must be kept secure)

Bodyapplication/json
scopeArray of strings

Array of permission scopes for the token

Example: ["wallet.read","merchant.read"]
sessionIdstring

Optional session identifier for tracking

Example: "session-123abc"
curl -i -X POST \
  https://chicksx-payments-api.redocly.app/_mock/apis/openapi/public_token/create \
  -H 'Content-Type: application/json' \
  -H 'merchant-api-key: YOUR_API_KEY_HERE' \
  -H 'merchant-client-id: string' \
  -d '{
    "scope": [
      "wallet.read",
      "merchant.read"
    ]
  }'

Responses

Public token created successfully

Bodyapplication/json
codestring

Result code indicating the operation status

Example: "OK"
dataobject

Response data payload

messagestring

Human-readable response message

Example: "Operation completed successfully"
Response
application/json
{
  "code": "OK",
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJjaGlja3N4LWFwaSIsInN1YiI6Im1lcmNoYW50LWRlbW8iLCJhdWQiOiJjaGlja3N4LXNkayIsImV4cCI6MTY5NjUzNDgwMCwiaWF0IjoxNjk2NTMxMjAwLCJqdGkiOiJmNDdhYzEwYi01OGNjLTQzNzItYTU2Ny0wZTAyYjJjM2Q0NzkiLCJlbnZpcm9ubWVudCI6InNhbmRib3giLCJzY29wZSI6WyJ3YWxsZXQucmVhZCIsIm1lcmNoYW50LnJlYWQiXX0.signature",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "expiresAt": 1696534800,
    "scope": [ … ],
    "jti": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }
}

SDK

SDK script delivery

Operations

Merchant

Merchant endpoints for payment methods and exchange currencies

Operations