Skip to main content

Overview

There are three ways to accept payments with Shoppex:

Storefront

Customers browse your shop and checkout directly

Payment Links

Share a link that takes customers straight to checkout

API

Create invoices programmatically from your app

The Payment Flow

Every payment in Shoppex follows this flow:
You don’t need to integrate with Stripe or PayPal directly. Shoppex handles all gateway communication for you.

Method 1: Storefront (No Code)

Your storefront at yourshop.shoppex.io is ready out of the box:
  1. Customer browses products
  2. Adds to cart
  3. Completes checkout
  4. Receives product automatically
Best for: Digital products, subscriptions, simple e-commerce
Create a link that goes directly to checkout - perfect for sharing on social media, emails, or anywhere.

Create via Dashboard

  1. Go to Products → Your Product
  2. Click Copy Payment Link
  3. Share the URL: https://yourshop.shoppex.io/product/your-product

Create via API

const response = await fetch('https://api.shoppex.io/dev/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Pro License',
    email: '[email protected]',
    value: 49.99,
    currency: 'USD'
  })
});

const { data } = await response.json();
console.log(data.url); // https://shoppex.io/invoice/4ea04c92-5cc3-4ea8-845c-cd3c7085796c
Best for: Social media sales, email campaigns, one-off payments

Method 3: API Integration

For full control, create payments directly via API. This is ideal when you have your own checkout UI or need to integrate payments into your app.

Create a Payment

const response = await fetch('https://api.shoppex.io/dev/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Order #123',
    email: '[email protected]',
    value: 29.99,
    currency: 'USD',
    // Optional settings
    gateway: 'STRIPE',           // Force specific gateway
    return_url: 'https://yoursite.com/success',
    cancel_url: 'https://yoursite.com/cancelled'
  })
});

const { data } = await response.json();

// Redirect customer to checkout
window.location.href = data.url;

Handle the Webhook

After payment, Shoppex sends a webhook to your server:
import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = crypto.createHmac('sha512', secret).update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

app.post('/webhooks/shoppex', async (req, res) => {
  // Verify signature (important!)
  const signature = req.headers['x-shoppex-signature'] as string;
  if (!verifyWebhook(req.rawBody, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const { event, data } = req.body;

  switch (event) {
    case 'order:paid':
      // Payment successful - fulfill the order
      await fulfillOrder(data.uniqid, data.customer_email);
      break;

    case 'order:cancelled':
      // Payment failed or expired
      await handleFailedPayment(data.uniqid);
      break;
  }

  res.status(200).send('OK');
});
Always verify webhook signatures in production. Shoppex uses HMAC-SHA512. See the Webhooks Guide for details.

FeatureInvoice (API)Payment Link
Use caseCustom checkout flowsQuick sharing
Customer emailRequiredOptional
Multiple productsYesSingle product
Custom fieldsYesProduct default
ExpirationConfigurableNo expiration
TrackingFull invoice dataBasic analytics
Rule of thumb:
  • Use Payment Links for simple, shareable checkouts
  • Use Invoices when you need control over the checkout or customer data

Payment Gateways

Configure your payment providers in Settings → Payments. Supports: Credit cards, Apple Pay, Google Pay, SEPA, Klarna, and more.
1

Get API Keys

Log in to Stripe DashboardDevelopers → API Keys
2

Add to Shoppex

Enter your Publishable Key and Secret Key in Settings → Payments → Stripe
3

Configure Webhook

In Stripe Dashboard, create a webhook pointing to:
https://api.shoppex.io/v1/webhooks/stripe/{your_shop_id}

PayPal

1

Create REST App

Go to PayPal Developer → Create App
2

Add Credentials

Enter Client ID and Secret in Settings → Payments → PayPal

Cryptocurrency

Two options available:
OptionSetupFees
Self-hosted (BTC/LTC)Run your own nodeNetwork fees only
NowPayments / CryptomusAPI key onlyProvider fees

Testing Payments

Enable Test Mode in Settings before going live.

Test Card Numbers

CardNumberResult
Visa4242 4242 4242 4242Success
Mastercard5555 5555 5555 4444Success
Declined4000 0000 0000 0002Declined
3D Secure4000 0025 0000 3155Requires auth
Use any future expiry date and any 3-digit CVC.

Test Checklist

1

Create Test Invoice

Create an invoice via dashboard or API
2

Complete Checkout

Pay with test card 4242 4242 4242 4242
3

Verify Webhook

Check that your webhook endpoint received order:paid
4

Check Fulfillment

Confirm the product was delivered (email, license, download)
Use ngrok to test webhooks locally:
ngrok http 3000
# Use the generated URL as your webhook endpoint

Common Scenarios

  1. Create product with File delivery type
  2. Upload your file
  3. Share your storefront or payment link
  4. Customer pays → receives download automatically
  1. Create product with Serials delivery type
  2. Add license keys (one per line)
  3. Customer pays → receives unique license key
  1. Create invoice via API with customer email
  2. Redirect customer to checkout_url
  3. Listen for order:paid webhook
  4. Fulfill order in your system
  1. Create product with Subscription type
  2. Set billing interval (monthly, yearly, etc.)
  3. Customer pays → subscription created
  4. Renewals happen automatically
See Subscriptions Guide for details.

Next Steps