Global Settings

Global Settings

The GlobalSettings section in appsettings.json contains core parameters that affect the operation of the entire ApiCharge service. This page explains each setting and its implications.

For detailed information about clustered deployments, see the Clustering page.

Example Configuration

    "GlobalSettings": {
    "UseNetwork": "Testnet",
    "ToleratedClockSkew": "00:02:00",
    "QuoteValidityDuration": "01:00:00",
    "SigningKeyEnvironmentVariable": "APICHARGE_SIGNING_KEY",
    "StellarEndpointRPC": "http://localhost:8000",
    "StellarNetworkPassphraseEnvironmentVariable": "APICHARGE_NETWORK_PASSPHRASE",
    "AllowSelfSignedServerCertificates": true,
    "AllowedServerCertificateThumbprints": [],
    "AllowedServerCertificateIssuers": []
    }
    

Network Settings

UseNetwork

Specifies which Stellar network to use for blockchain operations.

The network setting affects which contract ID is used for ApiCharge operations and which Stellar network passphrase is expected.

StellarEndpointRPC

The URL of the Stellar Soroban RPC server to connect to for blockchain operations.

Default values:

• Testnet: "https://soroban-testnet.stellar.org"
• Mainnet: "https://soroban.stellar.org"

You can also use a self-hosted Soroban RPC server by providing its URL.

Time Settings

ToleratedClockSkew

The maximum allowed difference between the server and client clocks when validating quotes and tokens. Specified as a TimeSpan.

Default: "00:02:00" (2 minutes)

This setting helps accommodate minor clock differences between systems while preventing replay attacks.

QuoteValidityDuration

How long a generated quote remains valid before expiring. Specified as a TimeSpan.

Default: "01:00:00" (1 hour)

After this duration, clients must request a new quote. This prevents outdated quotes from being used.

Security Settings

SigningKeyEnvironmentVariable

The name of the environment variable that contains the service's ED25519 private signing key.

Default: "APICHARGE_SIGNING_KEY"

This key is used to sign quotes and access tokens. It should be kept secure and never shared.

StellarNetworkPassphraseEnvironmentVariable

The name of the environment variable that contains the Stellar network passphrase.

Default: "APICHARGE_NETWORK_PASSPHRASE"

This passphrase is used for cryptographic operations and must match the selected network.

• Testnet passphrase: "Test SDF Network ; September 2015"
• Mainnet passphrase: "Public Global Stellar Network ; September 2015"

SSL/TLS Certificate Settings

AllowSelfSignedServerCertificates

Controls whether self-signed certificates are accepted for backend server connections.

Default: true (development environments),
false (production environments)

AllowedServerCertificateThumbprints

An array of specific certificate thumbprints that are trusted even if they would otherwise be rejected.

Default: [] (empty array)

This allows you to whitelist specific self-signed or private certificates by their thumbprint.

"AllowedServerCertificateThumbprints": [
  "A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0"
]

AllowedServerCertificateIssuers

An array of certificate issuer names that are trusted for backend server connections.

Default: [] (empty array)

This allows you to whitelist certificates from specific issuers.

"AllowedServerCertificateIssuers": [
  "CN=My Company CA, O=My Company, C=US"
]

Advanced Settings

The following properties are automatically derived and should not be manually set:

• ApiChargeContract: Automatically set based on UseNetwork
• SorobanServer: Initialized at runtime based on StellarEndpointRPC

Security Recommendations

Follow these best practices for securing your ApiCharge deployment:

• Store signing keys in secure environment variables or secrets management systems
• Use different signing keys for development, staging, and production environments
• Disable AllowSelfSignedServerCertificates in production
• Regularly rotate signing keys (requires coordination with clients)
• Use HTTPS for all client and backend communications

Stellar Blockchain Integration

ApiCharge connects to the Stellar blockchain network to process payments. This section describes the key configuration options for this integration.

Overview

The Stellar blockchain connection is essential for payment processing. By default, ApiCharge is pre-configured to connect to the Stellar network, but you can customize this connection based on your requirements.

Blockchain Connection Options

You have two options for connecting to the Stellar blockchain:

1. Default Connection (Recommended)

The simplest approach that works for most deployments.

• Advantages: Simple setup, automatic configuration, minimal management
• Best for: Development, testing, and standard production workloads

2. External Connection

Connect to an externally hosted Stellar RPC service.

• Advantages: Better scaling for high-volume scenarios, dedicated resources
• Best for: High-transaction production environments, multi-instance deployments

Configuring an External Connection

To use an external Stellar connection, update the StellarEndpointRPC setting:

{
  "GlobalSettings": {
    "UseNetwork": "Testnet",
    "StellarEndpointRPC": "https://your-external-rpc-service.example.com",
    // Other settings...
  }
}

Ensure your external service matches the network you've configured (Testnet or Mainnet).

Security Best Practices

Follow these guidelines to secure your blockchain connection:

• Always use secure HTTPS connections
• Restrict network access to administrative endpoints
• Monitor connection health and set up alerts
• Implement regular backups of your configuration
• Use firewalls to control access to your services

Performance Recommendations

For optimal performance in high-volume scenarios:

• Use high-performance storage (SSD) for databases
• Consider dedicated connections for clustered environments
• Monitor resource usage and scale as needed
• Use connection pooling for efficient resource utilization

Next Steps

Continue to the Environment Variables page to learn about the important environment variables needed for ApiCharge.