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.

🧪 Interactive Demo

We provide an interactive demo tool to test the complete SDK integration:

https://demos.chicksx.com

This demo allows you to:

  • Test SDK configuration with different operation types
  • Generate public access tokens
  • Simulate webhook events
  • View code examples in real-time

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 contact our support team 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

Contact support@chicksx.com to receive:

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

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

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:

<button id="payButton">Pay with ChicksX</button>
<script>
  document.getElementById('payButton').addEventListener('click', function () {
    window.chicksX.init();
  });
</script>

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:

  • operationType - Type of operation: buy (default), sell, swap-fiat, or swap-crypto
  • 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, cash-in-mail, cash-in-person, bill-payment, balance)
  • walletAddress - Cryptocurrency wallet address

Operation Types and URL Paths

The operationType parameter determines the URL path structure for the payment flow:

Operation TypeDescription
buyBuy cryptocurrency with fiat
sellSell cryptocurrency for fiat
swap-fiatSwap between fiat currencies
swap-cryptoSwap between cryptocurrencies

Payment Methods by Operation:

  • Buy: interac, cash-in-mail, cash-in-person, bill-payment, balance
  • Sell: interac, cash-in-mail, cash-in-person
  • Swap Fiat: cash-in-mail, cash-in-person
  • Swap Crypto: No payment method required (crypto-to-crypto)

Wallet Management

The API provides comprehensive wallet management capabilities for storing and managing user cryptocurrency wallets associated with your merchant account.

Webhooks

ChicksX uses webhooks to notify your application when events occur in your account. Webhooks are particularly useful for asynchronous events like order status changes.

Setting Up Webhooks

To receive webhook notifications:

  1. Contact Support: Email support@chicksx.com to register your webhook endpoint URL
  2. Provide Your URL: Supply a publicly accessible HTTPS endpoint that can receive POST requests
  3. Environment-Specific: You can configure different webhook URLs for development, staging, and production environments

Webhook Events

ChicksX sends the following webhook event types:

OrderCreated

Triggered when a new order is created in the system.

{
  "eventType": "OrderCreated",
  "details": {
    "orderId": 1092114,
    "status": "pending",
    "paymentMethod": "Interac E-Transfer",
    "fulfilled": false,
    "totalPrice": 100.00,
    "totalPriceCurrency": "CAD",
    "exchangeDetails": {
      "baseCurrency": "CAD",
      "amountReceived": 100.00,
      "targetCurrency": "BTC",
      "amountToSend": 0.00112180,
      "operationType": "B"
    }
  }
}

OrderFulfillment

Triggered when an order the order fulfills.

{
  "eventType": "OrderFulfillment",
  "details": {
    "orderId": 1092114,
    "status": "completed",
    "paymentMethod": "Interac E-Transfer",
    "fulfilled": true,
    "totalPrice": 100.00,
    "totalPriceCurrency": "CAD",
    "exchangeDetails": {
      "baseCurrency": "CAD",
      "amountReceived": 100.00,
      "targetCurrency": "BTC",
      "amountToSend": 0.00112180,
      "operationType": "B"
    }
  }
}

Webhook Payload Structure

FieldTypeDescription
eventTypestringEvent type: OrderCreated or OrderFulfillment
details.orderIdintegerUnique order identifier
details.statusstringCurrent order status
details.paymentMethodstringPayment method used
details.fulfilledbooleanWhether the order has been fulfilled
details.totalPricenumberTotal price of the order
details.totalPriceCurrencystringCurrency of the total price
details.exchangeDetails.baseCurrencystringSource currency
details.exchangeDetails.amountReceivednumberAmount received in base currency
details.exchangeDetails.targetCurrencystringTarget currency
details.exchangeDetails.amountToSendnumberAmount to send in target currency
details.exchangeDetails.operationTypestringOperation type: B (Buy), S (Sell), SF (Swap Fiat), SC (Swap Crypto)

Handling Webhooks

Your webhook endpoint should:

  1. Return 200 OK: Respond with HTTP 200 status to acknowledge receipt
  2. Process Asynchronously: Handle the webhook data asynchronously to avoid timeouts
  3. Be Idempotent: Handle duplicate webhook deliveries gracefully (use orderId as unique identifier)
  4. Validate Data: Verify the webhook data matches expected formats

Example Webhook Handler (Node.js)

app.post('/webhook/chicksx', (req, res) => {
  const { eventType, details } = req.body;
  
  console.log(`Received ${eventType} for order ${details.orderId}`);
  
  switch (eventType) {
    case 'OrderCreated':
      // Handle new order
      handleNewOrder(details);
      break;
    case 'OrderFulfillment':
      // Handle order status update
      handleOrderUpdate(details);
      break;
  }
  
  // Always respond with 200 to acknowledge receipt
  res.status(200).send('OK');
});

Security Considerations

  • Use HTTPS endpoints only
  • Validate incoming webhook data
  • Consider implementing signature verification (contact support for details)
  • Store webhook data for audit purposes
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

Wallet Management

Cryptocurrency wallet management operations

Operations

Webhooks

Webhook event notifications for order status changes