Environments
BITXpay provides two environments: a sandbox for development and testing, and a production environment for live transactions.
Sandbox Environment
Use the sandbox account for development. For engine-backed checkout, explicitly create a link with is_test: true to request a simulated order. Discover available currencies and networks through the checkout catalog; choosing the sandbox host alone does not set test mode.
Sandbox Configuration
import { BitxpayClient } from '@bitxpay/sdk';
const bitxpay = new BitxpayClient({
apiKey: process.env.MERCHANT_API_KEY,
privateKey: process.env.MERCHANT_PRIVATE_KEY,
environment: 'sandbox'
});Sandbox API Base URL
https://sandboxapi.bitxpay.com/api/v1Sandbox Dashboard
sandbox.bitxpay.com — Sign up and generate your sandbox API keys here.
Sandbox API Keys
- Format:
btxm_*(Merchant API) - Access: Sandbox account access; explicitly request simulated checkout with
is_test: true - Authentication: Ed25519 signature (EdDSA, raw bytes, Base64)
Production Environment
The production environment handles real transactions with actual cryptocurrency.
Production Configuration
import { BitxpayClient } from '@bitxpay/sdk';
const bitxpay = new BitxpayClient({
apiKey: process.env.MERCHANT_API_KEY,
privateKey: process.env.MERCHANT_PRIVATE_KEY,
environment: 'production'
});Production API Base URL
https://api.bitxpay.com/api/v1Production API Keys
- Format:
btxm_*(Merchant API) - Access: Full production access — real funds
- Security: Store securely, never commit to version control
- Authentication: Ed25519 signature (EdDSA, raw bytes, Base64)
Testing & Development
Use the sandbox environment for all development and testing. Additional local testing tools:
Webhook Testing
- webhook.site - Free temporary webhook URLs
- ngrok - Expose local development server
- Postman - Manual webhook simulation
# Example: Using ngrok for local webhook testing
ngrok http 3000Production Best Practices
Before going live with production traffic:
Security Checklist
- [x] API Keys: Store in environment variables or secure vault
- [x] HTTPS Only: All webhook endpoints must use HTTPS
- [x] Signature Verification: Always verify webhook signatures
- [x] Error Handling: Implement robust error handling
- [x] Logging: Log all transactions and errors
- [x] Rate Limiting: Handle API rate limits gracefully
- [x] Monitoring: Set up alerts for failed transactions
Transaction Safety
// Always implement proper error handling
try {
const payment = await bitxpay.payments.create({
payment_name: 'Order #12345',
amount: 100.00,
currency: 'USDT',
description: 'Order #12345'
});
// Store payment ID for tracking
await database.savePayment({
paymentId: payment.id,
status: payment.payment_status,
amount: payment.amount
});
} catch (error) {
console.error('Payment creation failed:', error);
// Implement proper error handling
await notifyAdmin(error);
}Webhook Security
Verify X-Webhook-Signature: sha256=<hex> over the raw request body with the webhook secret for that environment. Use the shared webhook handler examples.
Need Help?
We're here to help ensure your integration is secure and reliable:
- Documentation: https://docs.bitxpay.com/
- Email Support: support@bitxpay.com
Important
All production transactions on BITXpay involve real funds on mainnet. Always fully test your integration in the sandbox environment before switching to production credentials.