CACI - Fiat Transaction Reporting API (1.0.1)

API for exchanges to report fiat deposit and withdrawal transactions to CACI for reconciliation and compliance tracking.

This API allows cryptocurrency exchanges to report completed fiat transactions to CACI in real-time or batch mode.

Key Features:

• Report deposits and withdrawals with full transaction details
• Batch processing up to 100 transactions per request
• Flexible metadata support for additional context
• Individual status reporting for each transaction
• Idempotency support with transaction IDs

API Key Authentication:

• API Key authentication via X-Api-Key header
• Each exchange receives a unique API key
• API key must match the exchange_id in the request

Generating Signature

To generate the HMAC-SHA512 signature, follow these steps:

1. Create canonical JSON: Sort the request body JSON keys alphabetically to ensure consistent ordering
2. Build payload string: Format as "METHOD|PATH|BODY|TIMESTAMP"
3. Calculate HMAC-SHA512: Use your API secret as the key
4. Convert to hex: Get the lowercase hexadecimal representation

Python Implementation

import hmac
import hashlib
import json

def generate_signature(method, path, raw_body, timestamp, client_secret):
    """
    Generate HMAC-SHA512 signature for CACI API authentication
    
    Args:
        method: HTTP method (e.g., 'POST', 'GET')
        path: API endpoint path (e.g., '/v1/transactions/fiat')
        raw_body: Raw request body JSON string (empty string for GET/DELETE)
        timestamp: Unix timestamp in milliseconds
        client_secret: Your API secret key
    
    Returns:
        Hexadecimal signature string
    """
    # Create canonical JSON with sorted keys
    if raw_body:
        try:
            # Parse and re-sort JSON to ensure canonical ordering
            body_dict = json.loads(raw_body)
            canonical_body = json.dumps(body_dict, sort_keys=True, separators=(',', ':'))
        except json.JSONDecodeError:
            canonical_body = raw_body
    else:
        canonical_body = ""
    
    # Build payload
    payload = f"{method}|{path}|{canonical_body}|{timestamp}"
    
    # Generate HMAC-SHA512 signature
    signature = hmac.new(
        client_secret.encode("utf-8"),
        payload.encode("utf-8"),
        hashlib.sha512
    ).hexdigest()
    
    return signature

# Example usage
if __name__ == "__main__":
    # Sample request data
    method = "POST"
    path = "/v1/transactions/fiat"
    timestamp = 1763474667930
    client_secret = "your_api_secret_here"
    
    # Sample request body
    request_data = {
        "exchange_id": "EXCHANGE-001",
        "request_id": "3ed3502d-321b-4b84-b1b1-df45629bd46f",
        "request_ts_ms": 1763474667930,
        "transactions": [
            {
                "transaction_id": "5023ed3d-321b-4b84-b1b1-d29bd4f4566f",
                "user_id": "USER-001",
                "transaction_type": "DEPOSIT",
                "amount": "10000000",
                "currency": "IDR",
                "transaction_ts_ms": 1763474667930,
                "status": "COMPLETED",
                "bank_code": "BCA",
                "bank_account_number": "1234567890",
                "bank_account_name": "John Doe",
                "reference_number": "REF-001",
                "fee_amount": "5000",
                "fee_currency": "IDR",
                "metadata": [
                    {
                        "key": "payment_channel",
                        "value_type": "string",
                        "value": "bank_transfer"
                    },
                    {
                        "key": "verification_required",
                        "value_type": "boolean",
                        "value": False
                    }
                ]
            }
        ]
    }
    
    # Convert to canonical JSON
    raw_body = json.dumps(request_data, sort_keys=True, separators=(',', ':'))
    
    # Generate signature
    signature = generate_signature(method, path, raw_body, timestamp, client_secret)
    
    print(f"Payload: {method}|{path}|{raw_body}|{timestamp}")
    print(f"Signature: {signature}")
    
    # Headers to include in request
    headers = {
        "X-Api-Key": "your_api_key_here",
        "X-Signature": signature,
        "X-Timestamp": str(timestamp)
    }

Important Notes

• Canonical JSON: Always sort JSON keys alphabetically to ensure consistent signature generation
• Timestamp: Use current Unix timestamp in milliseconds (must be within 5 minutes of server time)
• Empty body: For GET/DELETE requests, use empty string for the BODY component
• Path: Use only the path portion, no host or query parameters
• Encoding: Use UTF-8 encoding for both payload and secret key

Use Cases:

• Daily transaction batch reporting
• Real-time transaction sync for compliance
• Historical transaction backfill
• Regulatory reporting support

System health check

Fiat transaction reporting API for exchanges

v1.0.1 — 2026-05-20

• Added include_fee boolean field to FiatTransactionPayload to indicate whether the transaction amount already includes the transfer fee
• Added fiat_partner field to capture the fiat payment partner used by the exchange (e.g. XENDIT, DOKU)
• Added fiat_partner_trx_id field for payment partner transaction reference tracking
• Renamed provider_trx_id field clarification — use fiat_partner_trx_id for partner-level reference

v1.0.0 — Initial Release

• Fiat deposit and withdrawal transaction reporting for exchanges
• Batch processing support (up to 100 transactions per request)
• transactions-fiat-v1 envelope payload format with payload_type discriminator
• Support for TRANSFER, VIRTUAL_ACCOUNT, EWALLET, and QRIS transaction channels
• HMAC-SHA512 request signature authentication (X-Api-Key, X-Signature, X-Timestamp)
• Optional metadata support via typed key-value pairs (string, number, boolean)
• Idempotency support via client-generated request_id