# ChicksX Payments API

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](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:

```bash
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:

```html
<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:

```html
<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:

```html
<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 Type | Description |
|---------------|-------------|
| `buy` | Buy cryptocurrency with fiat |
| `sell` | Sell cryptocurrency for fiat |
| `swap-fiat` | Swap between fiat currencies |
| `swap-crypto` | Swap 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.

```json
{
  "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.

```json
{
  "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

| Field | Type | Description |
|-------|------|-------------|
| `eventType` | string | Event type: `OrderCreated` or `OrderFulfillment` |
| `details.orderId` | integer | Unique order identifier |
| `details.status` | string | Current order status |
| `details.paymentMethod` | string | Payment method used |
| `details.fulfilled` | boolean | Whether the order has been fulfilled |
| `details.totalPrice` | number | Total price of the order |
| `details.totalPriceCurrency` | string | Currency of the total price |
| `details.exchangeDetails.baseCurrency` | string | Source currency |
| `details.exchangeDetails.amountReceived` | number | Amount received in base currency |
| `details.exchangeDetails.targetCurrency` | string | Target currency |
| `details.exchangeDetails.amountToSend` | number | Amount to send in target currency |
| `details.exchangeDetails.operationType` | string | Operation 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)

```javascript
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


Version: 1.0.0
License: Proprietary

## Servers

Development server
```
https://develop-api.chicksx.com/v1
```

Staging server
```
https://staging-api.chicksx.com/v1
```

Production server
```
https://api.chicksx.com/v1
```

## Security

### MerchantAuth

Merchant API authentication requires two headers:
- `merchant-api-key`: Your API key
- `merchant-client-id`: Your client ID

**Security Warning**: Never expose these credentials in client-side code. Use only from secure backend servers.


Type: apiKey
In: header
Name: merchant-api-key

## Download OpenAPI description

[ChicksX Payments API](https://docs.chicksx.com/_bundle/apis/openapi.yaml)

## SDK Authentication

Endpoints for SDK authentication and token management

### Create public access token

 - [POST /public_token/create](https://docs.chicksx.com/apis/openapi/sdk-authentication/createpublictoken.md): 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.

## SDK

SDK script delivery

### Get ChicksX SDK Script

 - [GET /sdk/chicksx.js](https://docs.chicksx.com/apis/openapi/sdk/getsdkscript.md): Retrieves the ChicksX SDK JavaScript file with embedded configuration. This script should be embedded in your client-side application using a `` tag.

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

### Example Usage

html

## Wallet Management

Cryptocurrency wallet management operations

### Create Wallet

 - [POST /wallets](https://docs.chicksx.com/apis/openapi/wallet-management/createwallet.md): Creates a new cryptocurrency wallet entry for a user. This endpoint must be called from your secure backend server.

Security: Requires merchant authentication headers.

### Get All Wallets

 - [GET /wallets](https://docs.chicksx.com/apis/openapi/wallet-management/getallwallets.md): Retrieves all cryptocurrency wallets associated with your merchant account. This endpoint must be called from your secure backend server.

Security: Requires merchant authentication headers.

### Search Wallet

 - [GET /wallets/search](https://docs.chicksx.com/apis/openapi/wallet-management/getwallet.md): Searches for a wallet by currency code and optionally by network code. This endpoint must be called from your secure backend server.

If multiple networks exist for a currency and no network code is provided, the response will include available networks.

Security: Requires merchant authentication headers.

### Get Wallet by ID

 - [GET /wallets/{id}](https://docs.chicksx.com/apis/openapi/wallet-management/getwalletbyid.md): Retrieves a specific wallet by its unique identifier. This endpoint must be called from your secure backend server.

Security: Requires merchant authentication headers.

### Update Wallet

 - [PATCH /wallets/{id}](https://docs.chicksx.com/apis/openapi/wallet-management/updatewallet.md): Updates an existing wallet's information. This endpoint must be called from your secure backend server.

Security: Requires merchant authentication headers.

### Delete Wallet

 - [DELETE /wallets/{id}](https://docs.chicksx.com/apis/openapi/wallet-management/deletewallet.md): Deletes a wallet by its ID. This endpoint must be called from your secure backend server.

Security: Requires merchant authentication headers.