Skip to content

Merchant Configuration API

Manage merchant payment settings including settlement chains, tokens, wallet addresses, and other configuration options.

Endpoints

Get Merchant Configuration

GET /v1/merchant/config/{merchantId}

Update Merchant Configuration

PUT /v1/merchant/config/{merchantId}

Authentication

This endpoint requires API key authentication:

Authorization: Bearer YOUR_API_KEY

Path Parameters

ParameterTypeRequiredDescription
merchantIdstring✅Merchant identifier

Request Parameters (PUT)

ParameterTypeRequiredDescription
settlementConfigobject✅Settlement configuration settings
paymentConfigobject❌Payment processing settings
webhookConfigobject❌Webhook notification settings
securityConfigobject❌Security and access settings

SettlementConfig Object

interface SettlementConfig {
  defaultChainId: number;           // Default settlement network
  defaultTokenAddress: string;      // Default settlement token
  defaultTokenSymbol: string;       // Token symbol
  walletAddress: string;           // Settlement wallet address
  autoSettle: boolean;             // Enable automatic settlement
  settlementSchedule?: string;     // Settlement frequency ("daily", "weekly")
  minimumAmount?: string;          // Minimum settlement amount
}

PaymentConfig Object

interface PaymentConfig {
  acceptedChains: number[];        // Accepted payment networks
  acceptedTokens: string[];        // Accepted token addresses
  maxPaymentAmount?: string;       // Maximum payment amount
  minPaymentAmount?: string;       // Minimum payment amount
  paymentTimeout?: number;         // Payment timeout in seconds
}

WebhookConfig Object

interface WebhookConfig {
  url: string;                     // Webhook endpoint URL
  events: string[];                // Subscribed events
  secret: string;                  // Webhook secret for verification
  retryAttempts?: number;          // Number of retry attempts
  timeout?: number;                // Request timeout in seconds
}

Response Format

Success Response

{
  "success": true,
  "data": {
    "merchantId": "merchant_123456789",
    "merchantName": "CyberPay Demo Store",
    "status": "active",
    "settlementConfig": {
      "defaultChainId": 1,
      "defaultTokenAddress": "0xA0b86a33E6441b8e776f89d2b5B977c737C5e0b6",
      "defaultTokenSymbol": "USDC",
      "walletAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b9",
      "autoSettle": true,
      "settlementSchedule": "daily",
      "minimumAmount": "100.00"
    },
    "paymentConfig": {
      "acceptedChains": [1, 137, 10, 42161, 8453],
      "acceptedTokens": [
        "0xA0b86a33E6441b8e776f89d2b5B977c737C5e0b6",
        "0xdAC17F958D2ee523a2206206994597C13D831ec7"
      ],
      "maxPaymentAmount": "10000.00",
      "minPaymentAmount": "1.00",
      "paymentTimeout": 1800
    },
    "webhookConfig": {
      "url": "https://yourstore.com/webhooks/cyberpay",
      "events": [
        "payment.completed",
        "payment.failed",
        "settlement.processed"
      ],
      "retryAttempts": 3,
      "timeout": 30
    },
    "securityConfig": {
      "ipWhitelist": ["192.168.1.0/24"],
      "requireSignature": true,
      "apiKeyRotationDays": 90
    },
    "createdAt": 1759231185,
    "updatedAt": 1759234785
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

Update Configuration

Example Request

{
  "settlementConfig": {
    "defaultChainId": 137,
    "defaultTokenAddress": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
    "defaultTokenSymbol": "USDC",
    "walletAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b9",
    "autoSettle": true,
    "settlementSchedule": "weekly",
    "minimumAmount": "500.00"
  },
  "paymentConfig": {
    "acceptedChains": [1, 137, 10],
    "maxPaymentAmount": "5000.00",
    "minPaymentAmount": "5.00",
    "paymentTimeout": 3600
  },
  "webhookConfig": {
    "url": "https://yourstore.com/webhooks/cyberpay",
    "events": [
      "payment.completed",
      "payment.failed"
    ],
    "retryAttempts": 5,
    "timeout": 60
  }
}

Error Responses

Merchant Not Found

{
  "success": false,
  "error": {
    "code": "MERCHANT_NOT_FOUND",
    "message": "Merchant not found or inactive",
    "details": {
      "merchantId": "merchant_123456789"
    }
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

Invalid Configuration

{
  "success": false,
  "error": {
    "code": "INVALID_CONFIGURATION",
    "message": "Invalid configuration parameters",
    "details": {
      "field": "settlementConfig.walletAddress",
      "reason": "Invalid Ethereum address format"
    }
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

Insufficient Permissions

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "API key does not have permission to modify merchant configuration",
    "details": {
      "requiredPermission": "merchant:config:write"
    }
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

Code Examples

JavaScript/TypeScript

import { CyberPaySDK } from '@cyberpay/sdk';
 
const sdk = new CyberPaySDK({
  apiKey: 'YOUR_API_KEY',
  environment: 'production'
});
 
async function getMerchantConfig(merchantId: string) {
  try {
    const config = await sdk.merchant.getConfig(merchantId);
    console.log('Merchant configuration:', config);
    return config;
  } catch (error) {
    console.error('Error fetching merchant config:', error);
    throw error;
  }
}
 
async function updateMerchantConfig(merchantId: string, updates: any) {
  try {
    const updatedConfig = await sdk.merchant.updateConfig(merchantId, {
      settlementConfig: {
        defaultChainId: 137,
        defaultTokenAddress: '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359',
        defaultTokenSymbol: 'USDC',
        walletAddress: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b9',
        autoSettle: true,
        settlementSchedule: 'daily',
        minimumAmount: '100.00'
      },
      paymentConfig: {
        acceptedChains: [1, 137, 10, 42161, 8453],
        maxPaymentAmount: '10000.00',
        minPaymentAmount: '1.00'
      }
    });
    
    console.log('Configuration updated:', updatedConfig);
    return updatedConfig;
  } catch (error) {
    console.error('Error updating merchant config:', error);
    throw error;
  }
}

cURL Examples

# Get merchant configuration
curl -X GET "https://api.cyberpay.org/v1/merchant/config/merchant_123456789" \
  -H "Authorization: Bearer YOUR_API_KEY"
 
# Update merchant configuration
curl -X PUT "https://api.cyberpay.org/v1/merchant/config/merchant_123456789" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settlementConfig": {
      "defaultChainId": 137,
      "defaultTokenAddress": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
      "defaultTokenSymbol": "USDC",
      "walletAddress": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b9",
      "autoSettle": true,
      "minimumAmount": "100.00"
    }
  }'

Configuration Options

Settlement Networks

NetworkChain IDRecommended For
Ethereum1High-value settlements
Polygon137Low-cost, fast settlements
Optimism10Layer 2 efficiency
Arbitrum42161Low fees, high throughput
Base8453Coinbase ecosystem

Settlement Tokens

TokenSymbolNetworksUse Case
USD CoinUSDCAllStable value settlements
TetherUSDTMostAlternative stablecoin
DaiDAIMostDecentralized stablecoin
EthereumETHEthereum L2sNative token settlements

Settlement Schedules

ScheduleDescriptionMinimum Amount
instantImmediate settlementAny amount
dailyOnce per day at UTC midnight$100+
weeklyEvery Monday at UTC midnight$500+
monthlyFirst day of month$1000+

Webhook Events

Available Events

EventDescription
merchant.config.updatedConfiguration changed
payment.completedPayment successfully processed
payment.failedPayment failed
settlement.initiatedSettlement process started
settlement.completedSettlement completed
settlement.failedSettlement failed

Webhook Payload Example

{
  "event": "merchant.config.updated",
  "merchantId": "merchant_123456789",
  "data": {
    "changes": {
      "settlementConfig.defaultChainId": {
        "from": 1,
        "to": 137
      }
    },
    "updatedBy": "api_key_abc123",
    "timestamp": 1759231185
  },
  "signature": "sha256=...",
  "timestamp": "2024-01-01T00:00:00Z"
}

Security Considerations

API Key Permissions

Ensure your API key has the required permissions:

  • merchant:config:read - View configuration
  • merchant:config:write - Modify configuration
  • merchant:config:admin - Full administrative access

Wallet Address Security

  • Use multi-signature wallets for high-value settlements
  • Regularly rotate settlement addresses
  • Monitor settlement transactions
  • Implement withdrawal limits

Webhook Security

  • Always verify webhook signatures
  • Use HTTPS endpoints only
  • Implement proper error handling
  • Log all webhook events

Best Practices

Configuration Management

  1. Test Changes: Use testnet to validate configuration changes
  2. Gradual Rollout: Update settings incrementally
  3. Monitor Impact: Track settlement success rates
  4. Backup Settings: Keep configuration backups
  5. Regular Reviews: Audit settings monthly

Settlement Optimization

  1. Choose Appropriate Networks: Balance cost vs speed
  2. Set Reasonable Minimums: Avoid frequent small settlements
  3. Monitor Gas Prices: Adjust timing based on network conditions
  4. Use Stable Tokens: Minimize exchange rate risk

Rate Limits

  • Standard: 10 requests per minute
  • Premium: 100 requests per minute
  • Enterprise: Custom limits available

Next Steps

Support