Payments - Shoppex

There are three ways to accept payments with Shoppex.

Storefront

Customers browse your shop and check out directly

Payment Links

Share a link that takes customers straight to checkout

API

Create invoices programmatically from your app

This guide covers both hosted/public Shoppex flows (storefront, payment links) and Developer API flows (POST /dev/v1/payments, POST /dev/v1/orders).

The payment flow

You do not need to integrate with Stripe or PayPal directly. Shoppex handles all gateway communication for you.

Important integration rule

One Shoppex invoice can have more than one payment attempt over time. A customer can open checkout, try PayPal, abandon it, come back, and finish with Stripe. This surprises most people integrating for the first time. Redirect the customer to the Shoppex checkout URL, listen for webhook events, and fulfill based on the final invoice status. Do not build your fulfillment logic around a single provider-side session ID.

Method 1: Storefront (hosted, public)

Your storefront at yourshop.shoppex.io is ready by default:

Customer browses products
Adds to cart
Completes checkout
Receives product automatically

Best for: Digital products, subscriptions, simple e-commerce

Method 2: Payment Links (hosted flow)

Create a link that goes directly to checkout. Share it on social media, in emails, or anywhere else.

Create through the dashboard

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

Create through the 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: 'customer@example.com',
    value: 49.99,
    currency: 'USD',
    webhook: 'https://your-site.com/api/shoppex/payment-webhook'
  })
});

const { data } = await response.json();
console.log(data.url); // https://checkout.shoppex.io/invoice/4ea04c92-5cc3-4ea8-845c-cd3c7085796c
console.log(data.webhook_secret); // returned once when webhook is provided

If you pass webhook, Shoppex sends payment lifecycle events only for that created payment or invoice to that URL. Store webhook_secret immediately. Shoppex does not return it on later reads. The webhook value must be your own HTTP(S) endpoint. Discord webhook URLs are not compatible with Shoppex developer-event payloads. Configure Discord notifications under Notifications → Sales Alerts instead. Best for: Social media sales, email campaigns, one-off payments

Method 3: API integration (Developer API)

Use the Developer API when you need your own checkout UI or a backend-driven payment flow.

Payment vs order

POST /dev/v1/payments and POST /dev/v1/orders look similar, but they solve different problems. Use POST /dev/v1/payments when you have your own checkout and want a hosted payment URL. You do not get Shoppex catalog line items or automatic product delivery. Use POST /dev/v1/orders when you want to charge for real Shoppex products. It includes line items, variants, and automatic delivery (files, serials, subscriptions, or DYNAMIC). The quick rule: payments = generic developer payment. orders = catalog-backed Shoppex order.

Subscriptions, serials, files, and DYNAMIC delivery always require POST /dev/v1/orders.POST /dev/v1/payments creates a one-off developer invoice with a free-form title and amount. It does not link to catalog products, does not create subscription records, and does not appear in the Subscriptions dashboard tab.A common integration mistake: load a product from GET /dev/v1/products, then call POST /dev/v1/payments with that product’s title and price. That disconnects checkout from the catalog. Pass the product uniqid in POST /dev/v1/orders instead.The API returns 422 when POST /dev/v1/payments receives catalog fields such as product_id or items.Recurring-billing custom fields such as plan_type still create the payment, but the 201 response includes a warnings array with code subscription_checkout_mismatch pointing you to POST /dev/v1/orders.

Check which payment methods are enabled

Use GET /dev/v1/me/capabilities to see which payment methods the shop currently accepts. A common mistake: GET /dev/v1/payments returns existing payment records, not the shop’s payment configuration. If you want to know which gateways (Stripe, PayPal, Crypto) are enabled, use GET /dev/v1/me/capabilities instead.

Crypto payments require a connected crypto provider: your own OxaPay, Cryptomus, or NowPayments account (connected in the dashboard under Settings → Payments → Crypto), or a Native Crypto wallet. GET /dev/v1/me/capabilities shows the enabled payment methods and native crypto gateways for your shop.

Skip the crypto picker on hosted checkout

If you want to keep Shoppex hosted checkout but open a concrete coin directly, pass:

gateway: the merchant crypto provider you want Shoppex to use
crypto_gateway: the concrete coin or network the buyer pays with

This works for merchant crypto providers like OXAPAY, CRYPTOMUS, and NOWPAYMENTS.

cURL

curl -X POST https://api.shoppex.io/dev/v1/payments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Discord Boost Package",
    "email": "customer@example.com",
    "value": 59.99,
    "currency": "USD",
    "gateway": "OXAPAY",
    "crypto_gateway": "TRON"
  }'

Example response shape:

{
  "data": {
    "uniqid": "4ea04c92-5cc3-4ea8-845c-cd3c7085796c",
    "crypto_gateway": "TRON",
    "url": "https://checkout.shoppex.io/invoice/4ea04c92-5cc3-4ea8-845c-cd3c7085796c?selected_gateway=TRON&auto_start_gateway=1&auto_start_crypto=1",
    "url_branded": "https://checkout.shoppex.io/invoice/4ea04c92-5cc3-4ea8-845c-cd3c7085796c?selected_gateway=TRON&auto_start_gateway=1&auto_start_crypto=1&shop=12345"
  }
}

Simple example:

gateway: "OXAPAY" + crypto_gateway: "TRON" -> hosted checkout opens directly on TRON
gateway: "CRYPTOMUS" + crypto_gateway: "USDT_TRC20" -> hosted checkout opens directly on USDT TRC20
gateway: "NOWPAYMENTS" + crypto_gateway: "BITCOIN" -> hosted checkout opens directly on Bitcoin through your NowPayments account
gateway: "NATIVE_CRYPTO" + crypto_gateway: "LITECOIN" -> Shoppex derives a non-custodial Litecoin receive address from your active native wallet

If you omit crypto_gateway, the buyer lands on the normal generic crypto payment selection first. If you only send crypto_gateway without gateway, Shoppex uses your active native wallet when it covers that coin. Otherwise, Shoppex uses your connected crypto provider. Either way, Shoppex starts the crypto session immediately. If you have no connected crypto provider and no native wallet, the request fails with a validation error.

Native crypto payments (BTC, LTC, USDT-TRC20, SOL, USDT-SPL)

Use this flow when you want crypto paid directly into your own non-custodial wallet. Shoppex assigns a fresh receive address from your active native wallet. The address is derived from your wallet key, or pre-created on your device for Solana. Shoppex watches the chain and marks the payment paid after the chain’s confirmation policy. Shoppex does not create a provider payment and does not hold keys or funds. Check availability first:

cURL

curl https://api.shoppex.io/dev/v1/me/capabilities \
  -H "Authorization: Bearer YOUR_API_KEY"

Look for:

{
  "data": {
    "features": {
      "nativeCryptoCheckout": {
        "available": true,
        "enabled": true,
        "gateways": ["BITCOIN", "LITECOIN", "USDT_TRC20", "SOLANA", "USDT_SOL"]
      }
    }
  }
}

Create a native Litecoin payment:

cURL

curl -X POST https://api.shoppex.io/dev/v1/payments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Discord Boost Package",
    "email": "customer@example.com",
    "value": 59.99,
    "currency": "USD",
    "gateway": "NATIVE_CRYPTO",
    "crypto_gateway": "LITECOIN"
  }'

Example response shape:

{
  "data": {
    "uniqid": "4ea04c92-5cc3-4ea8-845c-cd3c7085796c",
    "gateway": "NATIVE",
    "crypto_gateway": "LITECOIN",
    "crypto_address": "ltc1qexampleaddress",
    "crypto_amount": 0.42133742,
    "crypto_received": 0,
    "crypto_uri": "litecoin:ltc1qexampleaddress?amount=0.42133742",
    "crypto_confirmations_needed": 2,
    "status": "PENDING",
    "url": "https://checkout.shoppex.io/invoice/4ea04c92-5cc3-4ea8-845c-cd3c7085796c"
  }
}

If gateway is NATIVE_CRYPTO, Shoppex fails if no active native wallet exists for the requested chain. If you only send crypto_gateway (for example "BITCOIN" or "SOLANA"), an active native wallet is prioritized over external providers offering the same coin.

White-label crypto checkout (removed)

Shoppex removed managed white-label crypto checkout, together with the white_label request parameter. Crypto payments always use your own accounts now:

Native Crypto for non-custodial receive addresses from your own wallet (BTC, LTC, USDT-TRC20, SOL, USDT-SPL)
Your own OxaPay, Cryptomus, or NowPayments account for other coins

Historical white-label crypto payments can still be read through the Developer API and can still complete through the normal payment lifecycle. Schema validation rejects requests that still send white_label.

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: 'customer@example.com',
    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;

import requests

response = requests.post(
    'https://api.shoppex.io/dev/v1/payments',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'title': 'Order #123',
        'email': 'customer@example.com',
        'value': 29.99,
        'currency': 'USD'
    }
)

data = response.json()['data']
print(f"Checkout URL: {data['url']}")

curl -X POST https://api.shoppex.io/dev/v1/payments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Order #123",
    "email": "customer@example.com",
    "value": 29.99,
    "currency": "USD"
  }'

If you create the payment with gateway: 'PANDABASE', Shoppex also returns checkout_url and session_id.

Use data.checkout_url if you want the direct Pandabase checkout session URL.
Keep listening for Shoppex webhooks for the final paid or cancelled state.

Server-side completion is also different:

POST /dev/v1/payments/:id/complete confirms a generic developer payment only
POST /dev/v1/orders/:id/fulfill completes and fulfills a catalog-backed order
POST /dev/v1/orders/:id/complete is the same completion pipeline, exposed as an alias for integrations that look for a complete endpoint

Handle the webhook

After payment, Shoppex sends a webhook to your server. Use the webhook_secret returned by POST /dev/v1/payments for a per-payment webhook. Use the endpoint secret from Settings → Webhooks only for global webhook endpoints.

import crypto from 'crypto';

function verifyWebhook(
  payload: string,
  signatureHeader: string,
  deliveryId: string,
  timestampHeader: string,
  secret: string,
): boolean {
  const segments = signatureHeader.split(',').map((part) => part.trim());
  const hasV1Marker = segments.includes('v1');
  const parts = Object.fromEntries(segments.filter((part) => part.includes('=')).map((part) => {
    const [key, value] = part.trim().split('=');
    return [key, value ?? ''];
  }));
  if (!deliveryId || !hasV1Marker || parts.t !== timestampHeader) {
    return false;
  }
  const timestamp = Number(parts.t);
  if (!Number.isFinite(timestamp)) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > 300) {
    return false;
  }
  if (!/^[0-9a-f]{64}$/i.test(parts.h ?? '')) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${deliveryId}.${parts.t}.${payload}`)
    .digest('hex');
  if (parts.h.length !== expected.length) return false;

  return crypto.timingSafeEqual(
    Buffer.from(parts.h, 'hex'),
    Buffer.from(expected, 'hex'),
  );
}

app.post('/webhooks/shoppex', async (req, res) => {
  // Verify signature (important!)
  const signature = req.headers['x-shoppex-signature-v2'] as string;
  const deliveryId = req.headers['x-shoppex-delivery'] as string;
  const timestamp = req.headers['x-shoppex-timestamp'] as string;
  if (!verifyWebhook(req.rawBody, signature, deliveryId, timestamp, 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. New integrations must use X-Shoppex-Signature-V2. See Webhooks for details.

Dynamic product fulfillment

If you use products with type: "DYNAMIC", there is one more callback contract to implement: dynamic_webhook. This is separate from normal Shoppex event webhooks and uses the product’s dynamic webhook signing secret, not the secret from Settings → Webhooks. The order:paid webhook tells your app that the invoice is paid. The dynamic_webhook is a separate fulfillment callback that asks your server for the delivered token, key, or access data. Use the dedicated contract docs here:

Dynamic product delivery

Invoice vs payment link

Feature	Invoice (API)	Payment Link
Use case	Custom checkout flows	Quick sharing
Customer email	Required	Optional
Multiple products	Yes	Single product
Custom fields	Yes	Product default
Expiration	Configurable	No expiration
Tracking	Full invoice data	Basic 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. For gateway-specific setup, supported methods, and fees, see Payment gateways. For a developer integration, the enabled gateways decide two things: which gateway value you can pass to POST /dev/v1/payments or POST /dev/v1/orders, and which crypto_gateway values are valid. Use GET /dev/v1/me/capabilities to check what is enabled for the shop before you hardcode a gateway value.

Testing payments

Enable Test Mode in Settings before going live.

Test card numbers

Card	Number	Result
Visa	`4242 4242 4242 4242`	Success
Mastercard	`5555 5555 5555 4444`	Success
Declined	`4000 0000 0000 0002`	Declined
3D Secure	`4000 0025 0000 3155`	Requires auth

Use any future expiry date and any 3-digit CVC.

These numbers are Stripe-specific. PayPal and crypto gateways have their own sandbox modes.

Test checklist

Create a test invoice

Create an invoice through the dashboard or the API.

Complete checkout

Pay with test card 4242 4242 4242 4242.

Verify the webhook

Check that your webhook endpoint received order:paid.

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

Sell a digital product

Create a product with File delivery type.
Upload your file.
Share your storefront or payment link.
The customer pays, then receives the download automatically.

Sell software licenses

Create a product with Serials delivery type.
Add license keys, one per line.
The customer pays, then receives a unique license key.

Custom checkout in your app

Create a payment through the API with the customer email.
Redirect the customer to data.url.
Listen for the order:paid webhook.
Fulfill the order in your system.

Custom manual gateway (local PSP)

Create a Manual gateway with a redirect URL and {{invoice_id}} template variables.
Listen for order:manual_payment_pending on your shop webhook.
When your PSP confirms payment, call POST /dev/v1/invoices/{uniqid}/complete.
Shoppex delivers the product and sends order:paid.

See Manual payment auto-completion for a Cloudflare Worker example.

Recurring subscription

Create a product with Subscription type.
Set the billing interval (monthly, yearly, and so on).
The customer pays, then Shoppex creates the subscription.
Renewals happen automatically.

See Subscriptions for details.

Invoices

Deep dive into invoice lifecycle and statuses

Webhooks

Set up real-time notifications

Subscriptions

Set up recurring billing

API reference

Explore all endpoints

Storefront

Payment Links

API

​The payment flow

​Important integration rule

​Method 1: Storefront (hosted, public)

​Method 2: Payment Links (hosted flow)

​Create through the dashboard

​Create through the API

​Method 3: API integration (Developer API)

​Payment vs order

​Check which payment methods are enabled

​Skip the crypto picker on hosted checkout

​Native crypto payments (BTC, LTC, USDT-TRC20, SOL, USDT-SPL)

​White-label crypto checkout (removed)

​Create a payment

​Handle the webhook

​Dynamic product fulfillment

​Invoice vs payment link

​Payment gateways

​Testing payments

​Test card numbers

​Test checklist

​Common scenarios

​Sell a digital product

​Sell software licenses

​Custom checkout in your app

​Custom manual gateway (local PSP)

​Recurring subscription

Invoices

Webhooks

Subscriptions

API reference

The payment flow

Important integration rule

Method 1: Storefront (hosted, public)

Method 2: Payment Links (hosted flow)

Create through the dashboard

Create through the API

Method 3: API integration (Developer API)

Payment vs order

Check which payment methods are enabled

Skip the crypto picker on hosted checkout

Native crypto payments (BTC, LTC, USDT-TRC20, SOL, USDT-SPL)

White-label crypto checkout (removed)

Create a payment

Handle the webhook

Dynamic product fulfillment

Invoice vs payment link

Payment gateways

Testing payments

Test card numbers

Test checklist

Common scenarios

Sell a digital product

Sell software licenses

Custom checkout in your app

Custom manual gateway (local PSP)

Recurring subscription