Skip to main content

​
Overview

Every payment in Shoppex starts with an invoice. Whether a customer checks out through your storefront, clicks a payment link, or your backend creates one via API — the invoice is always the central object that tracks who is paying, what they’re buying, and whether the payment succeeded.
This guide covers the Shoppex invoice model used by both hosted checkout flows and the Developer API.
An invoice can go through more than one payment attempt before it reaches its final state. A customer might try PayPal, abandon it, and come back with a credit card — it’s still the same invoice.

​
Invoice Statuses

StatusDescription
PENDINGInvoice created, awaiting payment
COMPLETEDPayment completed successfully
PARTIALPartial payment received (crypto underpayment)
VOIDEDInvoice cancelled or expired
WAITING_FOR_CONFIRMATIONSCrypto payment pending blockchain confirmations
CUSTOMER_DISPUTE_ONGOINGCustomer opened a dispute/chargeback
REVERSEDPayment reversed (chargeback won by customer)
REFUNDEDPayment was refunded

​
Creating an Invoice

​
Via Dashboard

1

Navigate to Invoices

Go to Invoices → Create Invoice
2

Select products

Select products and quantities
3

Enter customer email

Enter customer email (optional)
4

Choose payment methods

Choose allowed payment methods
5

Create the invoice

Click Create

​
Via API (Developer API)

Use the POST /payments endpoint to create an invoice programmatically: 
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 #456',
    email: '[email protected]',
    value: 29.99,
    currency: 'EUR'
  })
});

const { data } = await response.json();
// Redirect to data.url for checkout

​
Invoice Expiration

By default, Shoppex-hosted invoice payment windows expire after 24 hours. You can customize the default expiration in Settings → Invoices.
The current Dev API payment example on this page does not accept an expires_at request field. Configure a different default expiration in the dashboard instead.
Expired invoices cannot be paid. Create a new invoice for the customer if needed.

​
Partial Payments

Partial payments can occur with cryptocurrency when the customer sends slightly less than required. You can:
Mark the invoice as paid manually from the dashboard. Use this when the shortfall is negligible and you want to fulfill the order immediately.
Customer pays the difference. The invoice stays in PARTIAL status until the remaining amount is received, then transitions to COMPLETED.
Cancel and refund the partial payment. The invoice moves to VOIDED and you can create a new one if needed.

​
Webhooks

Get notified when invoice status changes: 
{
  "event": "order:paid",
  "data": {
    "uniqid": "abc123def456",
    "type": "PRODUCT",
    "status": "COMPLETED",
    "gateway": "STRIPE",
    "total": 29.99,
    "total_display": 29.99,
    "currency": "USD",
    "customer_email": "[email protected]",
    "product_id": "prod_xyz",
    "product_title": "Pro License",
    "created_at": "2026-01-15T09:10:00.000Z",
    "updated_at": "2026-01-15T09:10:50.000Z"
  },
  "created_at": 1705314650
}
See Webhooks Guide for setup instructions.

​
Integration Rule

If you sync invoices into your own system, use the Shoppex invoice status as the final source of truth. The first payment attempt might fail, the second might succeed — the invoice ends as COMPLETED regardless of how many tries it took.
React to the final invoice state via webhook events, not to individual gateway callbacks. This is the single most important integration rule in Shoppex.

​
Next Steps

Payments Guide

Learn about payment gateways, configuration, and processing.

Webhooks Guide

Set up real-time notifications for invoice status changes.