CACI Clearing Gateway API (1.0.8)

Merchant-facing APIs exposed by CACI Clearing Gateway for PAKD needs.

This API allows merchants to manage users, virtual accounts, deposits, and withdrawals through the CACI Clearing Gateway API.

Key Features:

• User management (CRUD) with KYC and whitelisted accounts
• Virtual account creation and management
• Withdrawal processing (asynchronous)
• Fraud detection (FDS) checks for proposed withdrawals
• Deposit and withdrawal transaction inquiry
• Payment instrument discovery
• Webhooks creation and management
• Payment simulation (non-production only)

API Key Authentication:

• API Key via X-Api-Key header
• HMAC-SHA512 signature via X-Signature header
• Unix timestamp (ms) via X-Timestamp header

To access the API, your server's outbound IP address must be whitelisted by the CACI team.

• Contact support@caci.id and provide your static IP address(es) to be whitelisted
• All API requests must originate from a whitelisted IP — requests from non-whitelisted IPs will be rejected with 401 Unauthorized
• If you have multiple environments (staging, production), provide the IPs for each separately
• Notify the CACI team promptly if your IP address changes

Generating Signature

To generate the HMAC-SHA512 signature:

1. Create canonical JSON: Sort the request body JSON keys alphabetically
2. Build payload string: Format as "METHOD|PATH|BODY|TIMESTAMP"
3. Calculate HMAC-SHA512: Use your client secret as the key
4. Convert to hex: 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 = "/d/v1/users"
    timestamp = 1763474667930
    client_secret = "your_api_secret_here"
    
    # Sample request body
    request_data = {
        "requestId": str(uuid.uuid4()),
        "userId": str(uuid.uuid4())[:8],
        "kycName": "Jhon Doe",
        "phone": "+6281234567891",
        "email": "jhon.doe@icex.id",
        "type": "retail",
        "nationality": "ID", 
        "whitelistedKycNames": [
          "Jhon",
          "Pg"
        ]
    }
    
    # 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
• Timestamp: Unix timestamp in milliseconds (must be within 5 minutes of server time)
• Empty body: For GET/DELETE requests, use empty string for BODY component
• Path: Use only the path portion, no host or query parameters

Merchant user CRUD operations

Merchant payment instrument discovery

Virtual account creation and management

Withdrawal processing and inquiry

Deposit transaction inquiry

Merchant balance inquiry per provider and vault type

Merchant webhook configuration, retry operations, and outgoing notification reference.

After a transaction is processed, the platform asynchronously POSTs a JSON payload to all webhook URLs the merchant has configured for that event type. Delivery runs in a background goroutine and never blocks the transaction response.

Flow

Transaction Processed
        │
        ▼
Payload enriched from DB (VA info, user info)
        │
        ▼
POST to each configured webhook URL
        │
        ▼
WebhookLog stored in Redis
  key: webhook:log:<transactionId>  |  TTL: 24h

Event Types

Verifying Notifications (Required)

Treat every webhook as a signal, not as proof. A webhook payload is delivered to your URL and must not be trusted on its own. After receiving a notification, your server must call the corresponding read API to confirm the transaction's authoritative status before crediting funds, releasing goods, or settling:

Act only on the status returned by these endpoints — not on the webhook body. This protects you against forged or replayed notifications, since the read API is authenticated and returns CACI's source-of-truth record. Always dedupe on caciTxId or paymentRequestId so a repeated notification never credits the same transaction twice.

Delivery Details

• Method: POST
• Content-Type: application/json
• User-Agent: CACI-PG-Webhook/1.0
• Custom headers defined per webhook config are merged into every request.
• Success is determined by an HTTP 200 or 201 response from the merchant endpoint.
• The platform makes up to 3 delivery attempts per notification. If the merchant endpoint returns an error with status code 408, 429, or any 5xx, the delivery is retried automatically — up to 2 additional attempts with a 3-second delay between each attempt. Use the retry endpoint to manually re-trigger delivery after all automatic attempts have been exhausted.

Source IP Addresses

Webhook requests will originate from the following IPs. Whitelist these on your server to ensure delivery:

Deposit — va_payment

{
  "partnerServiceId": "merchant-uuid",
  "customerNo": "merchant-user-id",
  "virtualAccountNo": "1234567890",
  "trxId": "tx-uuid",
  "paymentRequestId": "tx-uuid",
  "paidAmount": {
    "value": "100000",
    "currency": "IDR"
  },
  "trxDateTime": "2025-01-01T10:00:00Z",
  "virtualAccountName": "John Doe",
  "virtualAccountType": "01",
  "virtualAccountPhone": "+62812345678",
  "virtualAccountEmail": "john@example.com",
  "additionalInfo": {
    "minAmount": 0,
    "maxAmount": 10000000,
    "bankCode": "BCA",
    "customerInfo": {
      "customer_id": "internal-user-uuid",
      "customer_ref_id": "merchant-user-ref",
      "given_name": "John Doe",
      "email": "john@example.com",
      "mobile": "+62812345678"
    },
    "expiredDate": "2025-01-02T00:00:00Z",
    "failureReason": null,
    "merchantUserId": "merchant-user-ref",
    "caciTxId": "tx-uuid"
  }
}

Withdrawal — transfer

{
  "originalReferenceNo": "provider-reference-number",
  "originalPartnerReferenceNo": "merchant-reference",
  "responseCode": "00",
  "responseMessage": "Success",
  "amount": {
    "value": "500000",
    "currency": "IDR"
  },
  "paymentInstrumentId": "pi-uuid",
  "beneficiaryAccountNo": "0987654321",
  "beneficiaryBankCode": "BNI",
  "sourceAccountNo": "source-account-number",
  "additionalInfo": {
    "merchantUserId": "merchant-user-ref",
    "caciTxId": "tx-uuid"
  }
}

Merchants register endpoint URLs via the endpoints below. A merchant may register multiple URLs for the same event type — the platform delivers to all of them.