ACP Documentation
API Reference

API Reference

ACP API Reference

The ACP API provides complete agent commerce functionality interfaces, including instant checkout, delegated payment, webhooks and other core features.

🚀 API Overview

Base URL 

Production: https://api.acplib.com/v1
Sandbox: https://sandbox-api.acplib.com/v1

Authentication 

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

📚 API Categories

Checkout API
Create and manage instant checkout sessions, handle shopping carts and payment flows.
Payment API
Complete interface for delegated payment creation, authorization and execution.
Webhook API
Configure and manage real-time event notification interfaces.

🔑 Quick Start

1. Get API Key 

# Register developer account
curl -X POST https://api.acplib.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "company": "Your Company",
    "use_case": "e-commerce integration"
  }'

2. Test Connection 

# Verify API connection
curl -X GET https://api.acplib.com/v1/health \
  -H "Authorization: Bearer YOUR_API_KEY"

3. Create First Checkout Session 

curl -X POST https://api.acplib.com/v1/checkout/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "name": "Example Product",
        "price": 2999,
        "currency": "usd",
        "quantity": 1
      }
    ],
    "success_url": "https://your-site.com/success",
    "cancel_url": "https://your-site.com/cancel"
  }'

📋 Common Parameters

Request Headers

ParameterTypeRequiredDescription
Authorizationstring✓API key in Bearer token format
Content-Typestring✓Request content type, usually application/json
X-Request-IDstring-Unique request identifier for tracking and debugging

Response Format

Success Response 

{
  "data": {
    // Response data
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:00:00Z"
  }
}

Error Response 

{
  "error": {
    "type": "invalid_request",
    "code": "missing_parameter", 
    "message": "Required parameter missing",
    "param": "items"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:00:00Z"
  }
}

🔒 Security Best Practices

1. API Key Management

  • Store API keys in environment variables
  • Rotate keys regularly
  • Never expose keys in client-side code

2. Request Signing 

import hmac
import hashlib
import time

def sign_request(payload: str, secret: str) -> str:
    timestamp = str(int(time.time()))
    string_to_sign = f"{timestamp}.{payload}"
    
    signature = hmac.new(
        secret.encode(),
        string_to_sign.encode(),
        hashlib.sha256
    ).hexdigest()
    
    return f"t={timestamp},v1={signature}"

3. Idempotency Control 

POST /v1/checkout/sessions
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: unique-key-123
Content-Type: application/json

{
  "items": [...]
}

📊 Rate Limiting

Limit TypeLimitTime Window
Read Operations1000 requestsper hour
Write Operations100 requestsper hour
Webhook Configuration10 requestsper hour

Rate Limit Headers 

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642694400

🧪 Testing Environment

Test Data

Use the following test data for development:

{
  "test_cards": {
    "visa_success": "4242424242424242",
    "visa_decline": "4000000000000002",
    "mastercard_success": "5555555555554444"
  },
  "test_amounts": {
    "success": [100, 1000, 5000],
    "decline": [2000, 3000],
    "error": [4000]
  }
}

Sandbox Environment 

export ACP_API_BASE_URL="https://sandbox-api.acplib.com/v1"
export ACP_API_KEY="sk_test_..."

📞 Support and Help

Technical Support

Developer Resources

📝 Changelog

v1.2.0 (2025-01-15)

  • Added delegated payment API
  • Improved error response format
  • Added request retry mechanism

v1.1.0 (2024-12-01)

  • Added webhook configuration API
  • Support for batch operations
  • Performance optimizations

v1.0.0 (2024-10-01)

  • Initial release
  • Basic checkout API
  • Payment processing functionality

Browse the left navigation menu to view specific API endpoint documentation and usage examples.