Blacklist Customer

The Blacklist Customer operation allows you to restrict a customer's access to your services by changing their account status to BLACKLISTED. This is a critical security and fraud prevention feature that immediately prevents the customer from making new transactions while maintaining their historical data for compliance and audit purposes. The operation includes comprehensive audit logging and can be reversed when needed.

ImplementationCopied!

Note: Blacklisting is implemented using the Update Customer endpoint by setting the status field to "BLACKLISTED".

Endpoint DetailsCopied!

Method: PATCH
URL: /api/v0/customers/{id}
Content Type: application/json
Authentication: Required (x-client-key and x-client-secret)
Rate Limiting: Subject to standard API rate limits
Special Audit: Blacklist actions trigger enhanced audit logging

Path ParametersCopied!

Parameter	Type	Required	Description
`id`	string	✅	Unique customer identifier (UUID) to blacklist

Request HeadersCopied!

Content-Type: application/json
x-client-key: your_client_key_here
x-client-secret: your_client_secret_here
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Request BodyCopied!

Blacklist Customer

{
  "status": "BLACKLISTED"
}

Remove from Blacklist

{
  "status": "ACTIVE"
}

Status Values

Status	Description	Effect
`"BLACKLISTED"`	Customer is blocked from all services	Prevents new transactions, orders, and API access
`"ACTIVE"`	Customer has full access	Normal service access (removes blacklist)
`"DEACTIVATED"`	Customer account is deactivated	Soft suspension, can be reactivated

Example RequestsCopied!

Blacklist a Customer

PATCH /api/v0/customers/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1
Host: api.devdraft.com
Content-Type: application/json
x-client-key: your_client_key
x-client-secret: your_client_secret
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

{
  "status": "BLACKLISTED"
}

Remove from Blacklist

PATCH /api/v0/customers/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1
Host: api.devdraft.com
Content-Type: application/json
x-client-key: your_client_key
x-client-secret: your_client_secret
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440001

{
  "status": "ACTIVE"
}

Success ResponseCopied!

Status Code:

200 OK

Blacklisted Customer Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone_number": "+1-555-123-4567",
  "customer_type": "Individual",
  "status": "BLACKLISTED",
  "last_spent": 250.75,
  "last_purchase_date": "2024-01-10T15:30:00Z",
  "appId": "app_123456789",
  "app_id": "app_123456789",
  "createdAt": "2024-01-01T10:00:00Z",
  "updatedAt": "2024-01-20T16:45:00Z",
  "app": {
    "id": "app_123456789",
    "app_name": "My Application"
  }
}

Error ResponsesCopied!

Customer Not Found (404)

{
  "statusCode": 404,
  "message": "Customer not found",
  "error": "Not Found"
}

Invalid Status Value (400)

{
  "statusCode": 400,
  "message": [
    "Please provide a valid customer status"
  ],
  "error": "Bad Request"
}

Already Blacklisted (200)

When a customer is already blacklisted, the operation succeeds but returns the current state:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "BLACKLISTED",
  "updatedAt": "2024-01-20T16:45:00Z"
}

Authentication Error (401)

{
  "statusCode": 401,
  "message": "Invalid API credentials",
  "error": "Unauthorized"
}

Audit Trail BehaviorCopied!

Blacklisting customers triggers special audit trail entries with enhanced logging:

Blacklist Audit Entry

{
  "actionType": "CUSTOMER_BLACKLIST",
  "entityType": "CUSTOMER",
  "description": "Blacklisted customer: John Doe",
  "metadata": {
    "customerDetails": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "status": "BLACKLISTED"
    },
    "changes": {
      "status": {
        "from": "ACTIVE",
        "to": "BLACKLISTED"
      }
    },
    "timestamp": "2024-01-20T16:45:00Z"
  },
  "before": {
    "status": "ACTIVE"
  },
  "after": {
    "status": "BLACKLISTED"
  }
}

Removal Audit Entry

{
  "actionType": "CUSTOMER_UPDATE",
  "entityType": "CUSTOMER", 
  "description": "Removed customer from blacklist: John Doe",
  "metadata": {
    "changes": {
      "status": {
        "from": "BLACKLISTED",
        "to": "ACTIVE"
      }
    }
  }
}

Integration ExamplesCopied!

cURL - Blacklist Customer

curl -X PATCH https://api.devdraft.com/api/v0/customers/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -H "x-client-key: your_client_key" \
  -H "x-client-secret: your_client_secret" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"status": "BLACKLISTED"}'

cURL - Remove from Blacklist

curl -X PATCH https://api.devdraft.com/api/v0/customers/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -H "x-client-key: your_client_key" \
  -H "x-client-secret: your_client_secret" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"status": "ACTIVE"}'

JavaScript/Node.js

Basic Blacklist Implementation

async function blacklistCustomer(customerId, reason = '') {
  try {
    const response = await fetch(`https://api.devdraft.com/api/v0/customers/${customerId}`, {
      method: 'PATCH',
      headers: {
        'Content-Type': 'application/json',
        'x-client-key': process.env.DEVDRAFT_CLIENT_KEY,
        'x-client-secret': process.env.DEVDRAFT_CLIENT_SECRET,
        'Idempotency-Key': crypto.randomUUID()
      },
      body: JSON.stringify({
        status: 'BLACKLISTED'
      })
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    const customer = await response.json();
    
    // Log the action internally
    console.log(`Customer ${customer.first_name} ${customer.last_name} has been blacklisted`);
    if (reason) {
      console.log(`Reason: ${reason}`);
    }
    
    return customer;
  } catch (error) {
    console.error('Failed to blacklist customer:', error.message);
    throw error;
  }
}

async function removeFromBlacklist(customerId, reason = '') {
  try {
    const response = await fetch(`https://api.devdraft.com/api/v0/customers/${customerId}`, {
      method: 'PATCH',
      headers: {
        'Content-Type': 'application/json',
        'x-client-key': process.env.DEVDRAFT_CLIENT_KEY,
        'x-client-secret': process.env.DEVDRAFT_CLIENT_SECRET,
        'Idempotency-Key': crypto.randomUUID()
      },
      body: JSON.stringify({
        status: 'ACTIVE'
      })
    });

    const customer = await response.json();
    console.log(`Customer ${customer.first_name} ${customer.last_name} removed from blacklist`);
    
    return customer;
  } catch (error) {
    console.error('Failed to remove customer from blacklist:', error.message);
    throw error;
  }
}

// Usage examples
await blacklistCustomer('550e8400-e29b-41d4-a716-446655440000', 'Fraudulent activity detected');
await removeFromBlacklist('550e8400-e29b-41d4-a716-446655440000', 'False positive - investigation complete');

Customer Blacklist Manager

class CustomerBlacklistManager {
  constructor(apiKey, apiSecret) {
    this.baseUrl = 'https://api.devdraft.com/api/v0/customers';
    this.headers = {
      'Content-Type': 'application/json',
      'x-client-key': apiKey,
      'x-client-secret': apiSecret
    };
  }

  async blacklistCustomer(customerId, options = {}) {
    const { reason, notify = false, internal_notes } = options;
    
    const response = await fetch(`${this.baseUrl}/${customerId}`, {
      method: 'PATCH',
      headers: {
        ...this.headers,
        'Idempotency-Key': crypto.randomUUID()
      },
      body: JSON.stringify({
        status: 'BLACKLISTED'
      })
    });

    if (!response.ok) {
      const error = await response.json().catch(() => ({}));
      throw new Error(error.message || `HTTP ${response.status}`);
    }

    const customer = await response.json();
    
    // Create internal record
    await this.logBlacklistAction(customerId, 'BLACKLISTED', {
      reason,
      internal_notes,
      timestamp: new Date().toISOString(),
      user: options.user || 'system'
    });

    // Send notification if requested
    if (notify && customer.email) {
      await this.sendBlacklistNotification(customer.email, reason);
    }

    return customer;
  }

  async removeFromBlacklist(customerId, options = {}) {
    const { reason, notify = false, internal_notes } = options;
    
    const response = await fetch(`${this.baseUrl}/${customerId}`, {
      method: 'PATCH',
      headers: {
        ...this.headers,
        'Idempotency-Key': crypto.randomUUID()
      },
      body: JSON.stringify({
        status: 'ACTIVE'
      })
    });

    const customer = await response.json();
    
    await this.logBlacklistAction(customerId, 'REMOVED', {
      reason,
      internal_notes,
      timestamp: new Date().toISOString(),
      user: options.user || 'system'
    });

    if (notify && customer.email) {
      await this.sendRemovalNotification(customer.email, reason);
    }

    return customer;
  }

  async getBlacklistedCustomers() {
    const response = await fetch(`${this.baseUrl}?status=BLACKLISTED&take=100`, {
      headers: this.headers
    });

    return await response.json();
  }

  async isBlacklisted(customerId) {
    try {
      const response = await fetch(`${this.baseUrl}/${customerId}`, {
        headers: this.headers
      });
      
      if (response.status === 404) {
        return false;
      }
      
      const customer = await response.json();
      return customer.status === 'BLACKLISTED';
    } catch (error) {
      console.error('Error checking blacklist status:', error);
      return false;
    }
  }

  // Internal logging method
  async logBlacklistAction(customerId, action, metadata) {
    // This would integrate with your internal logging system
    console.log(`Blacklist Action: ${action} for customer ${customerId}`, metadata);
  }

  // Notification methods
  async sendBlacklistNotification(email, reason) {
    // Implementation depends on your notification system
    console.log(`Sending blacklist notification to ${email}: ${reason}`);
  }

  async sendRemovalNotification(email, reason) {
    console.log(`Sending removal notification to ${email}: ${reason}`);
  }
}

// Usage
const blacklistManager = new CustomerBlacklistManager(
  process.env.DEVDRAFT_CLIENT_KEY,
  process.env.DEVDRAFT_CLIENT_SECRET
);

// Blacklist with full options
await blacklistManager.blacklistCustomer('550e8400-e29b-41d4-a716-446655440000', {
  reason: 'Multiple failed payment attempts',
  notify: true,
  internal_notes: 'Flagged by fraud detection system',
  user: 'admin@company.com'
});

// Check if customer is blacklisted
const isBlacklisted = await blacklistManager.isBlacklisted('550e8400-e29b-41d4-a716-446655440000');
console.log('Customer is blacklisted:', isBlacklisted);

// Get all blacklisted customers
const blacklistedCustomers = await blacklistManager.getBlacklistedCustomers();
console.log(`Found ${blacklistedCustomers.length} blacklisted customers`);

Python

Basic Implementation

import requests
import os
import uuid
from typing import Optional, Dict, Any
from datetime import datetime

class CustomerBlacklistAPI:
    def __init__(self):
        self.base_url = "https://api.devdraft.com/api/v0/customers"
        self.headers = {
            'Content-Type': 'application/json',
            'x-client-key': os.getenv('DEVDRAFT_CLIENT_KEY'),
            'x-client-secret': os.getenv('DEVDRAFT_CLIENT_SECRET')
        }

    def blacklist_customer(
        self, 
        customer_id: str, 
        reason: Optional[str] = None
    ) -> Dict[str, Any]:
        """Blacklist a customer by setting their status to BLACKLISTED."""
        
        headers = {
            **self.headers,
            'Idempotency-Key': str(uuid.uuid4())
        }
        
        data = {"status": "BLACKLISTED"}
        
        try:
            response = requests.patch(
                f"{self.base_url}/{customer_id}",
                headers=headers,
                json=data
            )
            
            response.raise_for_status()
            customer = response.json()
            
            # Log the action
            self._log_blacklist_action(
                customer_id=customer_id,
                action="BLACKLISTED",
                reason=reason,
                customer_data=customer
            )
            
            return customer
            
        except requests.exceptions.RequestException as e:
            print(f"Error blacklisting customer {customer_id}: {e}")
            raise

    def remove_from_blacklist(
        self, 
        customer_id: str, 
        reason: Optional[str] = None
    ) -> Dict[str, Any]:
        """Remove a customer from blacklist by setting their status to ACTIVE."""
        
        headers = {
            **self.headers,
            'Idempotency-Key': str(uuid.uuid4())
        }
        
        data = {"status": "ACTIVE"}
        
        try:
            response = requests.patch(
                f"{self.base_url}/{customer_id}",
                headers=headers,
                json=data
            )
            
            response.raise_for_status()
            customer = response.json()
            
            self._log_blacklist_action(
                customer_id=customer_id,
                action="REMOVED_FROM_BLACKLIST",
                reason=reason,
                customer_data=customer
            )
            
            return customer
            
        except requests.exceptions.RequestException as e:
            print(f"Error removing customer {customer_id} from blacklist: {e}")
            raise

    def is_blacklisted(self, customer_id: str) -> bool:
        """Check if a customer is currently blacklisted."""
        try:
            response = requests.get(
                f"{self.base_url}/{customer_id}",
                headers=self.headers
            )
            
            if response.status_code == 404:
                return False
                
            response.raise_for_status()
            customer = response.json()
            
            return customer.get('status') == 'BLACKLISTED'
            
        except requests.exceptions.RequestException:
            return False

    def get_blacklisted_customers(self, limit: int = 100) -> list:
        """Get all blacklisted customers."""
        try:
            response = requests.get(
                self.base_url,
                headers=self.headers,
                params={'status': 'BLACKLISTED', 'take': limit}
            )
            
            response.raise_for_status()
            return response.json()
            
        except requests.exceptions.RequestException as e:
            print(f"Error fetching blacklisted customers: {e}")
            return []

    def _log_blacklist_action(
        self, 
        customer_id: str, 
        action: str, 
        reason: Optional[str], 
        customer_data: Dict[str, Any]
    ):
        """Internal method to log blacklist actions."""
        log_entry = {
            'customer_id': customer_id,
            'action': action,
            'reason': reason,
            'customer_name': f"{customer_data.get('first_name', '')} {customer_data.get('last_name', '')}".strip(),
            'timestamp': datetime.now().isoformat(),
            'status': customer_data.get('status')
        }
        
        print(f"Blacklist Action: {action} for customer {customer_id}")
        if reason:
            print(f"Reason: {reason}")

# Usage examples
api = CustomerBlacklistAPI()

# Blacklist a customer
customer = api.blacklist_customer(
    '550e8400-e29b-41d4-a716-446655440000',
    reason='Suspicious transaction patterns detected'
)
print(f"Blacklisted: {customer['first_name']} {customer['last_name']}")

# Check if customer is blacklisted
is_blacklisted = api.is_blacklisted('550e8400-e29b-41d4-a716-446655440000')
print(f"Customer is blacklisted: {is_blacklisted}")

# Remove from blacklist
customer = api.remove_from_blacklist(
    '550e8400-e29b-41d4-a716-446655440000',
    reason='Investigation completed - customer cleared'
)

# Get all blacklisted customers
blacklisted = api.get_blacklisted_customers()
print(f"Total blacklisted customers: {len(blacklisted)}")

Advanced Fraud Detection Integration

import pandas as pd
from typing import List, Dict
from datetime import datetime, timedelta

class FraudDetectionBlacklist:
    def __init__(self, api_client: CustomerBlacklistAPI):
        self.api = api_client
        self.risk_thresholds = {
            'high_value_transactions': 5000,
            'transaction_frequency': 10,  # per day
            'failed_payments': 3,
            'suspicious_locations': ['unknown', 'high-risk']
        }

    def analyze_and_blacklist(self, customer_data: Dict) -> bool:
        """Analyze customer behavior and auto-blacklist if fraud detected."""
        risk_score = self._calculate_risk_score(customer_data)
        
        if risk_score >= 70:  # High risk threshold
            reason = self._generate_blacklist_reason(customer_data, risk_score)
            
            try:
                self.api.blacklist_customer(
                    customer_data['id'], 
                    reason=reason
                )
                
                # Send alert to fraud team
                self._send_fraud_alert(customer_data, risk_score, reason)
                
                return True
            except Exception as e:
                print(f"Failed to auto-blacklist customer {customer_data['id']}: {e}")
                return False
        
        return False

    def bulk_blacklist_review(self, customer_ids: List[str]) -> Dict:
        """Review multiple customers for potential blacklisting."""
        results = {
            'blacklisted': [],
            'reviewed': [],
            'errors': []
        }
        
        for customer_id in customer_ids:
            try:
                # Get customer data (this would come from your transaction system)
                customer_data = self._get_customer_transaction_data(customer_id)
                
                if self.analyze_and_blacklist(customer_data):
                    results['blacklisted'].append(customer_id)
                else:
                    results['reviewed'].append(customer_id)
                    
            except Exception as e:
                results['errors'].append({'customer_id': customer_id, 'error': str(e)})
        
        return results

    def _calculate_risk_score(self, customer_data: Dict) -> int:
        """Calculate fraud risk score based on customer behavior."""
        score = 0
        
        # High value transactions
        if customer_data.get('last_spent', 0) > self.risk_thresholds['high_value_transactions']:
            score += 30
        
        # Multiple failed payments
        failed_payments = customer_data.get('failed_payment_count', 0)
        if failed_payments >= self.risk_thresholds['failed_payments']:
            score += 40
        
        # Account age (new accounts are riskier)
        created_date = datetime.fromisoformat(customer_data.get('createdAt', '').replace('Z', '+00:00'))
        days_old = (datetime.now(created_date.tzinfo) - created_date).days
        if days_old < 7:
            score += 20
        
        # Suspicious patterns
        if customer_data.get('rapid_transactions', False):
            score += 25
        
        return min(score, 100)  # Cap at 100

    def _generate_blacklist_reason(self, customer_data: Dict, risk_score: int) -> str:
        """Generate a detailed reason for blacklisting."""
        reasons = []
        
        if customer_data.get('last_spent', 0) > self.risk_thresholds['high_value_transactions']:
            reasons.append("High-value transaction detected")
        
        if customer_data.get('failed_payment_count', 0) >= self.risk_thresholds['failed_payments']:
            reasons.append("Multiple failed payment attempts")
        
        if customer_data.get('rapid_transactions', False):
            reasons.append("Suspicious transaction frequency")
        
        created_date = datetime.fromisoformat(customer_data.get('createdAt', '').replace('Z', '+00:00'))
        days_old = (datetime.now(created_date.tzinfo) - created_date).days
        if days_old < 7:
            reasons.append("New account with suspicious activity")
        
        base_reason = f"Auto-blacklisted due to fraud detection (Risk Score: {risk_score})"
        if reasons:
            base_reason += f" - {', '.join(reasons)}"
        
        return base_reason

    def _get_customer_transaction_data(self, customer_id: str) -> Dict:
        """Get customer transaction data for analysis."""
        # This would integrate with your transaction/payment system
        # For demo purposes, returning mock data
        return {
            'id': customer_id,
            'last_spent': 7500,
            'failed_payment_count': 4,
            'rapid_transactions': True,
            'createdAt': (datetime.now() - timedelta(days=3)).isoformat()
        }

    def _send_fraud_alert(self, customer_data: Dict, risk_score: int, reason: str):
        """Send alert to fraud investigation team."""
        alert = {
            'customer_id': customer_data['id'],
            'risk_score': risk_score,
            'reason': reason,
            'timestamp': datetime.now().isoformat(),
            'requires_review': risk_score >= 80
        }
        
        # This would integrate with your alerting system
        print(f"🚨 FRAUD ALERT: Customer {customer_data['id']} auto-blacklisted")
        print(f"Risk Score: {risk_score}, Reason: {reason}")

# Usage
api = CustomerBlacklistAPI()
fraud_detector = FraudDetectionBlacklist(api)

# Analyze single customer
customer_data = {
    'id': '550e8400-e29b-41d4-a716-446655440000',
    'last_spent': 8000,
    'failed_payment_count': 5,
    'rapid_transactions': True,
    'createdAt': '2024-01-18T10:00:00Z'
}

if fraud_detector.analyze_and_blacklist(customer_data):
    print("Customer has been automatically blacklisted due to fraud detection")

# Bulk review
suspicious_customers = [
    '550e8400-e29b-41d4-a716-446655440000',
    '550e8400-e29b-41d4-a716-446655440001',
    '550e8400-e29b-41d4-a716-446655440002'
]

results = fraud_detector.bulk_blacklist_review(suspicious_customers)
print(f"Blacklisted: {len(results['blacklisted'])}, Reviewed: {len(results['reviewed'])}")

PHP

Basic Implementation

<?php
class CustomerBlacklist {
    private $baseUrl = 'https://api.devdraft.com/api/v0/customers';
    private $headers;

    public function __construct($clientKey, $clientSecret) {
        $this->headers = [
            'Content-Type: application/json',
            'x-client-key: ' . $clientKey,
            'x-client-secret: ' . $clientSecret
        ];
    }

    public function blacklistCustomer($customerId, $reason = '') {
        $data = json_encode(['status' => 'BLACKLISTED']);
        
        $headers = array_merge($this->headers, [
            'Idempotency-Key: ' . $this->generateUUID()
        ]);

        $context = stream_context_create([
            'http' => [
                'method' => 'PATCH',
                'header' => implode("\r\n", $headers),
                'content' => $data
            ]
        ]);

        $result = file_get_contents($this->baseUrl . '/' . $customerId, false, $context);
        
        if ($result === false) {
            throw new Exception('Failed to blacklist customer');
        }

        $customer = json_decode($result, true);
        
        // Log the action
        $this->logBlacklistAction($customerId, 'BLACKLISTED', $reason, $customer);
        
        return $customer;
    }

    public function removeFromBlacklist($customerId, $reason = '') {
        $data = json_encode(['status' => 'ACTIVE']);
        
        $headers = array_merge($this->headers, [
            'Idempotency-Key: ' . $this->generateUUID()
        ]);

        $context = stream_context_create([
            'http' => [
                'method' => 'PATCH',
                'header' => implode("\r\n", $headers),
                'content' => $data
            ]
        ]);

        $result = file_get_contents($this->baseUrl . '/' . $customerId, false, $context);
        $customer = json_decode($result, true);
        
        $this->logBlacklistAction($customerId, 'REMOVED', $reason, $customer);
        
        return $customer;
    }

    public function isBlacklisted($customerId) {
        $context = stream_context_create([
            'http' => [
                'method' => 'GET',
                'header' => implode("\r\n", $this->headers)
            ]
        ]);

        $result = @file_get_contents($this->baseUrl . '/' . $customerId, false, $context);
        
        if ($result === false) {
            return false;
        }

        $customer = json_decode($result, true);
        return isset($customer['status']) && $customer['status'] === 'BLACKLISTED';
    }

    public function getBlacklistedCustomers($limit = 100) {
        $url = $this->baseUrl . '?status=BLACKLISTED&take=' . $limit;
        
        $context = stream_context_create([
            'http' => [
                'method' => 'GET',
                'header' => implode("\r\n", $this->headers)
            ]
        ]);

        $result = file_get_contents($url, false, $context);
        return $result ? json_decode($result, true) : [];
    }

    private function logBlacklistAction($customerId, $action, $reason, $customerData) {
        $logEntry = [
            'customer_id' => $customerId,
            'action' => $action,
            'reason' => $reason,
            'customer_name' => trim(($customerData['first_name'] ?? '') . ' ' . ($customerData['last_name'] ?? '')),
            'timestamp' => date('c'),
            'status' => $customerData['status'] ?? 'unknown'
        ];
        
        error_log("Blacklist Action: " . json_encode($logEntry));
        
        echo "Blacklist Action: $action for customer $customerId\n";
        if ($reason) {
            echo "Reason: $reason\n";
        }
    }

    private function generateUUID() {
        return sprintf('%04x%04x-%04x-%04x-%04x-%04x%04x%04x',
            mt_rand(0, 0xffff), mt_rand(0, 0xffff),
            mt_rand(0, 0xffff),
            mt_rand(0, 0x0fff) | 0x4000,
            mt_rand(0, 0x3fff) | 0x8000,
            mt_rand(0, 0xffff), mt_rand(0, 0xffff), mt_rand(0, 0xffff)
        );
    }
}

// Usage
$blacklist = new CustomerBlacklist(
    $_ENV['DEVDRAFT_CLIENT_KEY'],
    $_ENV['DEVDRAFT_CLIENT_SECRET']
);

$customerId = '550e8400-e29b-41d4-a716-446655440000';

// Blacklist customer
try {
    $customer = $blacklist->blacklistCustomer($customerId, 'Fraudulent activity detected');
    echo "Blacklisted: " . $customer['first_name'] . " " . $customer['last_name'] . "\n";
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

// Check if blacklisted
if ($blacklist->isBlacklisted($customerId)) {
    echo "Customer is currently blacklisted\n";
}

// Get all blacklisted customers
$blacklistedCustomers = $blacklist->getBlacklistedCustomers();
echo "Total blacklisted customers: " . count($blacklistedCustomers) . "\n";

// Remove from blacklist
$customer = $blacklist->removeFromBlacklist($customerId, 'False positive - investigation complete');
echo "Removed from blacklist: " . $customer['first_name'] . " " . $customer['last_name'] . "\n";
?>

Business Logic and EffectsCopied!

Immediate Effects of Blacklisting

Transaction Blocking: Customer cannot initiate new transactions
API Access Restriction: Customer-related API calls may be restricted
Payment Processing: All payment attempts are automatically declined
Service Access: Customer loses access to platform services

Data Retention

Historical Data: All historical transactions and data remain intact
Audit Trail: Complete record of customer activity is preserved
Compliance: Meets regulatory requirements for data retention

Reversal Process

Status Change: Set status back to "ACTIVE" to restore access
Immediate Effect: Customer regains full access upon status change
Audit Logging: Removal from blacklist is fully audited

Common Use CasesCopied!

1. Fraud Prevention

// Auto-blacklist on suspicious activity
if (suspiciousActivityDetected) {
  await blacklistCustomer(customerId, 'Suspicious transaction patterns detected');
}

2. Payment Failures

// Blacklist after multiple failed payments
if (failedPaymentCount >= 5) {
  await blacklistCustomer(customerId, 'Multiple payment failures - potential fraud');
}

3. Compliance Requirements

// Regulatory compliance blacklisting
await blacklistCustomer(customerId, 'Customer appears on sanctions list');

4. Account Security

// Security breach response
await blacklistCustomer(customerId, 'Account compromised - security investigation');

5. Dispute Resolution

// Temporary blacklist during investigation
await blacklistCustomer(customerId, 'Under investigation for chargeback dispute');

// Remove after resolution
await removeFromBlacklist(customerId, 'Investigation complete - customer cleared');

Best PracticesCopied!

1. Document Reasons

Always provide clear, specific reasons for blacklisting:

// Good
await blacklistCustomer(customerId, 'Multiple failed payments with different cards - fraud indicator');

// Bad
await blacklistCustomer(customerId, 'suspicious');

2. Use Idempotency Keys

Always include idempotency keys to prevent duplicate actions during retries.

3. Implement Review Process

// Set up automated review for blacklisted customers
setInterval(async () => {
  const blacklistedCustomers = await getBlacklistedCustomers();
  
  for (const customer of blacklistedCustomers) {
    const daysSinceBlacklist = getDaysSince(customer.updatedAt);
    
    if (daysSinceBlacklist >= 30) {
      // Flag for manual review
      await flagForReview(customer.id, 'Blacklisted for 30+ days - review required');
    }
  }
}, 24 * 60 * 60 * 1000); // Daily check

4. Monitor Audit Trails

Regularly review blacklist audit trails for patterns and compliance.

5. Customer Communication

Consider notifying customers of their blacklist status through appropriate channels.

6. Integration with Fraud Systems

Integrate blacklisting with your fraud detection and prevention systems.

Security ConsiderationsCopied!

Access Control

Blacklisting requires appropriate API permissions
All actions are logged with user identification
Cannot blacklist customers from other applications

Audit Compliance

Enhanced audit logging for compliance requirements
Immutable audit records of all blacklist actions
Complete before/after state tracking

Data Privacy

Blacklisted customer data remains encrypted
Access to blacklisted customer information is logged
Compliance with data protection regulations

Rate LimitingCopied!

Standard Limits: Subject to normal API rate limits
Bulk Operations: Consider rate limits when blacklisting multiple customers
Monitoring: Track blacklist API usage for capacity planning

PATCH /api/v0/customers/{id} - Update customer (main blacklist endpoint)
GET /api/v0/customers - List customers (filter by status=BLACKLISTED)
GET /api/v0/customers/{id} - Check individual customer blacklist status

SupportCopied!

For technical support or questions about customer blacklisting:

Verify customer ID format and existence
Check audit trails for blacklist history
Review your application's blacklist policies
Contact support with customer ID and specific use case for assistance

Blacklist Customer

ImplementationCopied!

Endpoint DetailsCopied!

Path ParametersCopied!

Request HeadersCopied!

Request BodyCopied!

Blacklist Customer

Remove from Blacklist

Status Values

Example RequestsCopied!

Blacklist a Customer

Remove from Blacklist

Success ResponseCopied!

Blacklisted Customer Response

Error ResponsesCopied!

Customer Not Found (404)

Invalid Status Value (400)

Already Blacklisted (200)

Authentication Error (401)

Audit Trail BehaviorCopied!

Blacklist Audit Entry

Removal Audit Entry

Integration ExamplesCopied!

cURL - Blacklist Customer

cURL - Remove from Blacklist

JavaScript/Node.js

Basic Blacklist Implementation

Customer Blacklist Manager

Python

Basic Implementation

Advanced Fraud Detection Integration

PHP

Basic Implementation

Business Logic and EffectsCopied!

Immediate Effects of Blacklisting

Data Retention

Reversal Process

Common Use CasesCopied!

1. Fraud Prevention

2. Payment Failures

3. Compliance Requirements

4. Account Security

5. Dispute Resolution

Best PracticesCopied!

1. Document Reasons

2. Use Idempotency Keys

3. Implement Review Process

4. Monitor Audit Trails

5. Customer Communication

6. Integration with Fraud Systems

Security ConsiderationsCopied!

Access Control

Audit Compliance

Data Privacy

Rate LimitingCopied!

Related EndpointsCopied!

SupportCopied!