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

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

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


Version: 1.0.0
License: Proprietary

## Servers

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

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

## Download OpenAPI description

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

## SDK Authentication

Endpoints for SDK authentication and token management

### Create public access token

 - [POST /public_token/create](https://docs.chicksx.com/apis/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 x-api-key or x-client-id in client-side code.

### Create public access token

 - [POST /public_token/create](https://docs.chicksx.com/apis/merchant/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 x-api-key or x-client-id in client-side code.

## Merchant

Merchant endpoints for payment methods and exchange currencies

### Create public access token

 - [POST /public_token/create](https://docs.chicksx.com/apis/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 x-api-key or x-client-id in client-side code.

### Create public access token

 - [POST /public_token/create](https://docs.chicksx.com/apis/merchant/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 x-api-key or x-client-id in client-side code.

### Get payment methods

 - [GET /payment-methods](https://docs.chicksx.com/apis/merchant/getpaymentmethods.md): Returns the list of payment methods available for the given operation type and country. Requires merchant authentication (x-api-key, x-client-id).

### Get exchange currencies

 - [GET /exchange/currencies](https://docs.chicksx.com/apis/merchant/getexchangecurrencies.md): Returns receive (crypto) and spend (fiat) currencies available for exchange. Requires merchant authentication (x-api-key, x-client-id).

### Calculate exchange quote

 - [POST /exchange/quotes](https://docs.chicksx.com/apis/merchant/calculateexchangequote.md): Calculates an exchange quote for a given operation, currencies, amount and payment method. Requires merchant authentication (x-api-key, x-client-id).

## SDK

SDK script delivery

### Get ChicksX SDK Script

 - [GET /sdk/chicksx.js](https://docs.chicksx.com/apis/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