Payments - Shoppex

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

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 don’t 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 might open checkout, try PayPal, abandon it, come back and finish with Stripe. This surprises most people integrating for the first time. The important thing: redirect the customer to the Shoppex checkout URL, listen for webhook events, and fulfill based on the final invoice status. Don’t build your fulfillment logic around a single provider-side session ID.

Method 1: Storefront (Hosted/Public)

Your storefront at yourshop.shoppex.io is ready out of the box:

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 - perfect for sharing on social media, emails, or anywhere.

Create via Dashboard

Go to Products → Your Product
Click Copy Payment Link
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://checkout.shoppex.io/invoice/4ea04c92-5cc3-4ea8-845c-cd3c7085796c

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 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 just want a hosted payment URL. You don’t get Shoppex catalog line items or automatic product delivery. Use POST /dev/v1/orders when you want to charge for real Shoppex products — with line items, variants, and automatic delivery (files, serials, subscriptions, or DYNAMIC). The quick rule: payments = generic developer payment. orders = catalog-backed Shoppex order.

Need to know which payment methods the shop currently accepts?

Use GET /dev/v1/me/capabilities for that. 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.

White-label crypto checkout is available by manual approval. Contact support to request access.Use GET /dev/v1/me/capabilities to check whether white_label_crypto_checkout is enabled for your shop before you build a bot or custom crypto payment UI around it.

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 should pay with

This works for merchant crypto providers like OXAPAY and CRYPTOMUS.

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": "[email protected]",
    "value": 59.99,
    "currency": "USD",
    "gateway": "OXAPAY",
    "crypto_gateway": "TRON",
    "white_label": false
  }'

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
white_label: true + crypto_gateway: "BITCOIN" -> Shoppex-managed white-label crypto returns Bitcoin payment data and exposes gateway: "WHITE_LABEL" in the response

If you omit crypto_gateway, the buyer lands on the normal generic crypto payment selection first.

White-label Crypto Checkout

Use this flow when you want to show the crypto payment details inside your own UI instead of redirecting the buyer to a normal Shoppex checkout page. Think: your Discord bot showing a TRON address and QR code directly in an embed, or your app rendering its own payment card with address, amount, and live status. This feature is available by manual approval only.

How it works

Ask Shoppex support to enable white-label crypto checkout for your shop.
Call GET /dev/v1/me/capabilities.
Check features.white_label_crypto_checkout.enabled.
If it is true, create the payment with crypto_gateway: "TRON" and white_label: true.
Render the returned crypto fields in your own UI.

Do not send gateway: "NOWPAYMENTS" for this flow. White-label crypto is selected with white_label: true plus crypto_gateway, and the public response label is WHITE_LABEL. If the feature is not enabled, POST /dev/v1/payments returns 403 FORBIDDEN for white-label crypto requests.

Check access

cURL

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

Example response shape:

{
  "data": {
    "features": {
      "white_label_crypto_checkout": {
        "available": true,
        "enabled": true
      }
    }
  }
}

Create a white-label crypto 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": "[email protected]",
    "value": 59.99,
    "currency": "USD",
    "crypto_gateway": "TRON",
    "white_label": true
  }'

Example response shape:

{
  "data": {
    "uniqid": "4ea04c92-5cc3-4ea8-845c-cd3c7085796c",
    "gateway": "WHITE_LABEL",
    "crypto_gateway": "TRON",
    "crypto_address": "TXieysuGaFATfeHCPvkfZRisUuKrudrFGQ",
    "crypto_amount": 233.72,
    "crypto_received": 0,
    "crypto_uri": "tron:TXieysuGaFATfeHCPvkfZRisUuKrudrFGQ?amount=233.72",
    "crypto_confirmations_needed": 1,
    "payment_id": "np_123",
    "status": "PENDING",
    "url": "https://checkout.shoppex.io/invoice/4ea04c92-5cc3-4ea8-845c-cd3c7085796c"
  }
}

What to render in your own UI

Use these fields from the response:

gateway: WHITE_LABEL for the Shoppex-managed white-label crypto rail
crypto_gateway: the crypto the buyer should send
crypto_address: the wallet address to pay
crypto_amount: the exact amount to send
crypto_uri: useful for QR codes or wallet deep links
crypto_confirmations_needed: how many confirmations are needed before the payment can complete
status: the current Shoppex payment status

Show crypto_address in a copy field, turn crypto_uri into a QR code, display crypto_amount next to the network name, and keep the invoice uniqid to poll or re-read the payment status later.

Recommended integration pattern

use white-label crypto only for the buyer-facing payment UI
still treat the Shoppex payment or invoice state as the source of truth
listen for Shoppex webhooks for the final paid or cancelled result
use GET /dev/v1/payments/:uniqid if you need to refresh the current payment state

WHITE_LABEL is the public API label for this flow. Shoppex may still use internal processor labels behind the scenes, but those are not part of the buyer-facing contract. A typical Discord bot flow: create the payment, post the address and QR code, wait for the Shoppex webhook, then edit the message to show “Paid” when the payment completes.

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;

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/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:

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.

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. 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.

Stripe (Recommended)

Supports: Credit cards, Apple Pay, Google Pay, SEPA, Klarna, and more.

Get API Keys

Add to Shoppex

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

Configure Webhook

In Stripe Dashboard, create a webhook pointing to:

https://api.shoppex.io/v1/webhooks/stripe/{your_shop_id}

PayPal

Create REST App

Go to PayPal Developer → Create App

Add Credentials

Enter Client ID and Secret in Settings → Payments → PayPal

Cryptocurrency

Two options available:

Option	Setup	Fees
Self-hosted (BTC/LTC)	Run your own node	Network fees only
NowPayments / Cryptomus	API key only	Provider fees

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 Test Invoice

Create an invoice via dashboard or API

Complete Checkout

Pay with test card 4242 4242 4242 4242

Verify 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 product with File delivery type
Upload your file
Share your storefront or payment link
Customer pays → receives download automatically

Sell software licenses

Create product with Serials delivery type
Add license keys (one per line)
Customer pays → receives unique license key

Custom checkout in your app

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

Recurring subscription

Create product with Subscription type
Set billing interval (monthly, yearly, etc.)
Customer pays → subscription created
Renewals happen automatically

See Subscriptions Guide for details.

Next Steps

Invoices

Deep dive into invoice lifecycle and statuses

Webhooks

Set up real-time notifications

Subscriptions

Set up recurring billing

API Reference

Explore all endpoints

Getting Started

Core Concepts

Integrations

​Overview

Storefront

Payment Links

API

​The Payment Flow

​Important Integration Rule

​Method 1: Storefront (Hosted/Public)

​Method 2: Payment Links (Hosted Flow)

​Create via Dashboard

​Create via API

​Method 3: API Integration (Developer API)

​Payment vs Order

​Need to know which payment methods the shop currently accepts?

​Skip the crypto picker on hosted checkout

​White-label Crypto Checkout

​How it works

​Check access

​Create a white-label crypto payment

​What to render in your own UI

​Recommended integration pattern

​Create a Payment

​Handle the Webhook

​Dynamic Product Fulfillment

​Invoice vs Payment Link

​Payment Gateways

​Stripe (Recommended)

​PayPal

​Cryptocurrency

​Testing Payments

​Test Card Numbers

​Test Checklist

​Common Scenarios

​Next Steps

Invoices

Webhooks

Subscriptions

API Reference

Overview

The Payment Flow

Important Integration Rule

Method 1: Storefront (Hosted/Public)

Method 2: Payment Links (Hosted Flow)

Create via Dashboard

Create via API

Method 3: API Integration (Developer API)

Payment vs Order

Need to know which payment methods the shop currently accepts?

Skip the crypto picker on hosted checkout

White-label Crypto Checkout

How it works

Check access

Create a white-label crypto payment

What to render in your own UI

Recommended integration pattern

Create a Payment

Handle the Webhook

Dynamic Product Fulfillment

Invoice vs Payment Link

Payment Gateways

Stripe (Recommended)

PayPal

Cryptocurrency

Testing Payments

Test Card Numbers

Test Checklist

Common Scenarios

Next Steps