shora-ai-payment-sdk

Shora AI Payment SDK

Commerce infrastructure for the AI era.

Quick Start

Install the SDK and start processing payments in under 2 minutes.

npm install shora-ai-payment-sdk

Get Your API Key

👉 Get Your API Key →

• Visit app.shora.cloud and sign up/login
• Go to Developer Dashboard → API Management
• Click Generate API Key (one-click, uses your account info)
• Copy your API key and start coding!

Need help? Check our Developer Documentation

Alternative: Generate Test Keys (Development Only)

For development and testing, you can use generated API keys:

# Generate test API keys
node -e "
const crypto = require('crypto');
console.log('Sandbox Key:', 'shora_test_' + crypto.randomBytes(32).toString('base64url'));
console.log('Production Key:', 'shora_live_' + crypto.randomBytes(32).toString('base64url'));
"

For production, register a merchant to get official API keys:

curl -X POST https://api.shora.cloud/merchants/register \
 -H "Content-Type: application/json" \
 -d '{
 "business_name": "Your Store",
 "business_type": "ecommerce",
 "contact_name": "Your Name",
 "contact_email": "[e-mail]"
 }'

Basic Usage

import ShoraSDK from 'shora-ai-payment-sdk';

// Use your API key from app.shora.cloud
const sdk = new ShoraSDK({
 apiKey: 'your_api_key_from_shora_app', // Get it from app.shora.cloud
 environment: 'production' // or 'sandbox' for testing
});

// Create a payment session
const payment = await sdk.createPaymentSession({
 amount: 100,
 currency: 'TRY',
 description: 'Test payment',
 customer: { email: '[e-mail]' }
});

console.log('Payment created:', payment.id);

What This SDK Does

The Shora AI Payment SDK handles payment processing for modern applications. It provides secure payment sessions, automatic retry logic, and enterprise-grade security features. Built for developers who need reliable payment infrastructure without the complexity.

Core features include payment session management, WooCommerce integration, AES-256 encryption for sensitive data, and comprehensive audit logging. The SDK automatically retries failed requests and includes circuit breaker patterns for production reliability.

API Key Management

Development Keys

For development and testing, use generated API keys:

// Generate a test API key
const crypto = require('crypto');
const testKey = 'shora_test_' + crypto.randomBytes(32).toString('base64url');
console.log('Test API Key:', testKey);

Production Keys

For production, register a merchant to get official API keys:

# Register a new merchant
curl -X POST https://api.shora.cloud/merchants/register \
 -H "Content-Type: application/json" \
 -d '{
 "business_name": "Your Store",
 "business_type": "ecommerce",
 "contact_name": "Your Name",
 "contact_email": "[e-mail]",
 "contact_phone": "[phone]",
 "address_line1": "123 Main St",
 "city": "Your City",
 "state": "Your State",
 "postal_code": "12345",
 "country": "US"
 }'

API Key Security

• Store API keys in environment variables
• Never commit API keys to version control
• Use different keys for development and production
• Rotate keys regularly for security

# Environment variables
export SHORA_API_KEY="shora_test_your_key_here"
export SHORA_ENVIRONMENT="sandbox"

Configuration

BaseUrl Resolution

The SDK resolves the API base URL in the following order:

• config.baseUrl - Explicit baseUrl in SDK configuration (highest priority)
• SHORA_API_BASE_URL - Environment variable
• Production default - https://api.shora.cloud (only for environment: 'production')

Important: For sandbox or staging environments, you must provide an explicit baseUrl or set SHORA_API_BASE_URL. The SDK will throw an error if you attempt to use sandbox/staging without an explicit baseUrl to prevent accidental production calls.

// Production (uses default if no baseUrl provided)
const sdk = new ShoraSDK({
  apiKey: 'your-key',
  environment: 'production'
});

// Sandbox requires explicit baseUrl
const sandboxSdk = new ShoraSDK({
  apiKey: 'your-key',
  environment: 'sandbox',
  baseUrl: 'https://sandbox.api.shora.cloud' // Required!
});

// Or use environment variable
process.env.SHORA_API_BASE_URL = 'https://sandbox.api.shora.cloud';
const sandboxSdk2 = new ShoraSDK({
  apiKey: 'your-key',
  environment: 'sandbox'
});

Configuration

The SDK accepts a simple configuration object:

interface ShoraConfig {
 apiKey: string; // Your Shora API key
 baseUrl?: string; // Custom API endpoint
 environment?: 'sandbox' | 'production';
 timeout?: number; // Request timeout in ms
 tenantId?: string; // Multi-tenant support
 encryptionKey?: string; // AES-256 encryption key
 enableAuditLogging?: boolean; // Enable audit logs
 auditLogEndpoint?: string; // Custom audit endpoint
}

Payment Processing

Create payment sessions and process payments with automatic retry logic:

// Create a payment session
const session = await sdk.createPaymentSession({
 amount: 250,
 currency: 'TRY',
 description: 'Product purchase',
 customer: { email: '[e-mail]' }
});

// Process the payment
const result = await sdk.processPayment(session.paymentId, 'card', 'tok_123');

WooCommerce Integration

For e-commerce applications, use the ACP checkout method:

const checkout = await sdk.payWithACP({
 woo_product_id: 123,
 amount: 99.99,
 currency: 'USD',
 customer_email: '[e-mail]',
 order_id: 'WC-12345'
});

// Redirect user to checkout.checkout_url

Security Features

The SDK includes enterprise-grade security features:

// Encrypt sensitive tokens
const encrypted = sdk.encryptToken('sensitive-token');
const decrypted = sdk.decryptToken(encrypted);

// Generate secure payment tokens
const paymentToken = sdk.generateSecurePaymentToken({
 amount: 100,
 currency: 'TRY',
 userId: 'user_123'
});

// Audit logging
sdk.logAudit('payment_created', 'Payment session created', 'session_123');
const logs = sdk.getAuditLogs('2024-01-01', '2024-12-31');

Error Handling

The SDK provides clear error handling with automatic retries:

try {
 const payment = await sdk.createPaymentSession(request);
 console.log('Success:', payment.paymentId);
} catch (error) {
 if (error instanceof ShoraError) {
 console.log('Error Code:', error.code);
 console.log('Status:', error.status);
 console.log('Message:', error.message);
 }
}

Troubleshooting

Import Error? Check your module type in package.json. For CommonJS use require('shora-ai-payment-sdk').default, for ESM use import ShoraSDK from 'shora-ai-payment-sdk'.

Network Issues? The SDK automatically retries failed requests with exponential backoff. Increase the timeout if needed: new ShoraSDK({ timeout: 30000 }).

TypeScript Issues? Install types with npm install @types/node and use proper imports: import ShoraSDK, { PaymentRequest } from 'shora-ai-payment-sdk'.

Testing

Run the test suite to verify everything works:

npm test

For load testing with k6:

npm run test:load

Development

Build the SDK from source:

npm install
npm run build
npm run lint

Performance

The SDK is optimized for production use with automatic retry logic, circuit breaker patterns, and in-memory caching. It handles 1000+ requests per second and includes comprehensive error recovery mechanisms.

Production Optimized

This SDK has been optimized for production use with a clean dist folder, core payment functionality only, and enterprise-ready security features. The bundle size is kept minimal at 144K total.

Troubleshooting

Common Issues

API Key Errors

// Error: Invalid API key
// Solution: Check your API key format
const sdk = new ShoraSDK({
 apiKey: 'shora_test_your_key_here', // Must start with 'shora_test_' or 'shora_live_'
 environment: 'sandbox'
});

Connection Errors

// Error: Request failed with status code 404
// Solution: Check your base URL
const sdk = new ShoraSDK({
 apiKey: 'your-key',
 baseUrl: 'https://api.shora.cloud', // Use correct API endpoint
 environment: 'sandbox'
});

Payment Endpoint Errors

// Error: Payment session creation failed
// Solution: Ensure merchant registration is complete
// For development, use generated API keys
// For production, register a merchant first

Debug Mode

Enable debug logging to troubleshoot issues:

const sdk = new ShoraSDK({
 apiKey: 'your-key',
 environment: 'sandbox',
 debug: true // Enable debug logging
});

Health Check

Always check API health before processing payments:

const health = await sdk.healthCheck();
console.log('API Status:', health.status);
console.log('Database:', health.database);
console.log('Redis:', health.redis);

Community & Feedback

We believe the SDK grows stronger with community input:

• Star the repository and follow updates at github.com/shoraco/shora-ai-payment-sdk
• Share improvements by opening pull requests—check the open issues or start a discussion if you need guidance
• Every installation triggers a friendly reminder to send feedback; you can respond by filing an issue, starting a GitHub Discussion, or emailing [e-mail]
• Tell us how you are using the SDK so we can feature your use-case and shape the roadmap together

Performance

The SDK is optimized for production use with automatic retry logic, circuit breaker patterns, and in-memory caching. It handles 1000+ requests per second and includes comprehensive error recovery mechanisms.

Production Optimized

This SDK has been optimized for production use with a clean dist folder, core payment functionality only, and enterprise-ready security features. The bundle size is kept minimal at 144K total.

License

MIT

Support

• Documentation: developer.shora.cloud
• Developer Panel: app.shora.cloud
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [e-mail]
• Website: shora.co

The SDK is designed for developer productivity with automatic retry logic, clear error messages, and comprehensive TypeScript support. Get started in 2 minutes and scale to production with confidence.