CACI Clearing Gateway API (1.0.3)

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)
• 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.
• One delivery attempt is made per notification. Use the retry endpoint for failed deliveries.

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.

Payment simulation endpoints for non-production environments only.

Prerequisites: Before simulating a deposit, you must complete the following steps:

1. Create a user via POST /v1/users
2. Create a virtual account for that user via POST /v1/virtual-accounts
3. Use the simulator to send a test payment to the created VA

You can also test deposits via the UI at: https://sandbox-simulator.caci.id