Tebex Payment Integration

Complete guide to integrate Tebex Headless API for processing payments in your store system.

Prerequisites

Before you begin, ensure you have:

• ✅ A Tebex account (Sign up here)
• ✅ A Tebex Webstore
• ✅ Admin access to your dashboard
• ✅ Backend server running

Overview

The Tebex integration uses the Headless API approach:

• Products are managed in Tebex Dashboard
• Baskets are created via API
• Payments are processed by Tebex
• Webhooks notify your system of completed payments

Architecture

[Your Store] → [Tebex API] → [User Checkout] → [Tebex Webhooks] → [Your Backend]

Step 1: Get Tebex Credentials

Step 2: Configure Products in Tebex

Step 3: Setup Webhook

Webhooks are crucial for receiving payment notifications.

Step 4: Configure Provider in Admin Panel

Step 5: Test the Integration

Webhook Verification

Your backend automatically verifies webhooks using HMAC-SHA256.

How It Works

// Backend verifies each webhook
const signature = headers['x-signature'];
const isValid = verifySignature(payload, signature, webhookSecret);

if (!isValid) {
  return 403; // Forbidden
}

IP Whitelisting

Tebex webhooks come from these IPs:

• 18.209.80.3
• 54.87.231.232

Troubleshooting

Products Not Loading

Problem: Shop page shows "No products found"

Solutions:

1. Verify API token is correct
2. Check products are published in Tebex
3. Ensure products have a price set
4. Check backend logs for API errors

Webhook Not Working

Problem: Payments successful but not recorded

Solutions:

1. Verify webhook URL is correct (includes provider ID)
2. Check webhook secret matches
3. Review backend logs: /api/store/webhook/{providerId}
4. Test webhook in Tebex Dashboard → Webhooks → Send Test

Invalid Signature Error

Problem: Webhook returns "Invalid signature"

Solutions:

1. Verify webhook secret in admin panel
2. Ensure secret matches Tebex webhook configuration
3. Check raw body is preserved (required for signature verification)

Cloudflare Issues

Problem: Webhook IP validation fails

Solution:

# Add to backend .env
SKIP_WEBHOOK_IP_CHECK=true

Production Checklist

Before going live:

• All products configured in Tebex
• Prices are correct
• Webhook URL updated with real provider ID
• Webhook secret configured
• Test purchase completed successfully
• Transaction appears in admin panel
• SSL/HTTPS enabled on your domain
• Backend logs show successful webhooks

API Reference

Tebex Headless API Endpoints

Your backend uses these endpoints:

Webhook Payload Example

{
  "id": "webhook-id",
  "type": "payment.completed",
  "date": "2024-11-05T12:00:00Z",
  "subject": {
    "transaction_id": "tbx-xxxxxx",
    "status": "Complete",
    "price": {
      "amount": 9.99,
      "currency": "USD"
    },
    "customer": {
      "email": "[email protected]",
      "username": "player123"
    },
    "products": [
      {
        "id": 12345,
        "name": "VIP Rank",
        "quantity": 1
      }
    ]
  }
}

Environment Variables

Add these to your backend .env:

# Cloudflare users (optional)
SKIP_WEBHOOK_IP_CHECK=true

# For production
NODE_ENV=production

Best Practices

Security

✅ Do:

• Keep webhook secret secure
• Use HTTPS in production
• Verify webhook signatures
• Validate IP addresses (unless using Cloudflare)

❌ Don't:

• Commit secrets to git
• Use HTTP in production
• Skip signature verification
• Disable security checks without reason

Product Management

✅ Do:

• Use clear product names
• Add detailed descriptions
• Upload high-quality images
• Organize products in categories
• Set appropriate prices

❌ Don't:

• Use confusing names
• Leave descriptions empty
• Forget to set prices
• Mix unrelated products

Testing

✅ Do:

• Test in Tebex sandbox first
• Complete full checkout flow
• Verify webhook delivery
• Check transaction records

❌ Don't:

• Test with real money initially
• Skip webhook testing
• Forget to check logs

Support Resources

• 📚 Tebex Documentation
• 💬 Tebex Discord
• 🎫 Support Tickets
• 📧 Email: [email protected]

Next Steps

After successful integration:

1. ✅ Configure your products
2. ✅ Test thoroughly
3. ✅ Set up transaction monitoring
4. ✅ Configure email notifications
5. ✅ Review analytics regularly

Additional Features

Coupons & Gift Cards

Tebex supports discount codes:

// Apply coupon
await basket.applyCoupon('SUMMER2024');

// Apply gift card
await basket.applyGiftCard('GIFT-XXXX-XXXX');

Subscription Products

Enable recurring payments in Tebex Dashboard:

1. Edit product → "Subscription" tab
2. Set renewal period (monthly, yearly)
3. Save changes

Multi-Currency

Tebex automatically handles currency conversion:

• Customer sees price in their local currency
• You receive payment in your preferred currency
• Exchange rates are updated automatically

Migration from Other Providers

Switching from another provider?

1. Export existing customer data
2. Recreate products in Tebex
3. Configure webhooks
4. Run parallel for testing period
5. Switch completely when confident

Need help? Check our FAQ or Contact Support.