Complete or process manual-payment invoices

Shoppex custom manual gateways (Settings → Payments → Manual) support payment instructions or buyer redirects with template variables such as {{amount}}, {{currency}}, and {{invoice_id}}. There is no built-in inbound IPN URL on manual gateways today. When your own payment provider confirms a transfer, your server must call the Developer API to complete the invoice. This is the API equivalent of the dashboard’s Process Invoice action.

This pattern works for storefront and payment-link invoices, not only for POST /dev/v1/payments. Use POST /dev/v1/invoices/{uniqid}/complete.

End-to-end flow

Buyer starts manual checkout → invoice moves to PENDING_PAYMENT / awaiting merchant confirmation.
Shoppex can notify you with order:manual_payment_pending (configure under Settings → Webhooks).
Your external gateway sends its own webhook when money arrives.
Your adapter calls POST /dev/v1/invoices/{uniqid}/complete with your Shoppex API key.
Shoppex runs the normal completion pipeline (delivery, emails, order:paid).

Always verify the provider webhook on your server before calling Shoppex. Never expose your shx_* API key to the browser or to the payment provider’s client-side SDK.

Prerequisites

Requirement	Details
API key	Dashboard → Settings → Developer API. Scope: `invoices.write` (or `*`).
Invoice status	`PENDING` or `PENDING_PAYMENT`
Invoice ID	UUID from checkout URL (`/invoice/{uniqid}`) or `order:manual_payment_pending` payload (`data.uniqid`)

Complete an invoice (minimal)

curl -X POST "https://api.shoppex.io/dev/v1/invoices/INVOICE_UUID/complete" \
  -H "Authorization: Bearer shx_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: complete-INVOICE_UUID" \
  -d '{
    "note": "Paid via my local gateway",
    "suppress_emails": false
  }'

import { Shoppex } from '@shoppexio/sdk';

const shoppex = new Shoppex({ apiKey: process.env.SHOPPEX_API_KEY! });

await shoppex.invoices.complete(invoiceUniqid, {
  note: 'Paid via my local gateway',
});

import os
import requests

response = requests.post(
    f"https://api.shoppex.io/dev/v1/invoices/{invoice_uniqid}/complete",
    headers={
        "Authorization": f"Bearer {os.environ['SHOPPEX_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": f"complete-{invoice_uniqid}",
    },
    json={"note": "Paid via my local gateway"},
    timeout=30,
)
response.raise_for_status()

Success: 200 with a stable completion result:

{
  "data": {
    "uniqid": "33333333-3333-4333-8333-333333333333",
    "status": "COMPLETED",
    "message": "Invoice completed successfully."
  }
}

Call GET /dev/v1/invoices/{uniqid} afterwards if you need the current full invoice representation. Common errors:

HTTP	Meaning
`401`	Invalid or missing API key
`404`	Invoice not found for your shop
`422`	Invoice already `COMPLETED`, or status is not completable

The Idempotency-Key header is required so that a retry after a network drop does not apply the same side effect twice. If you do not pass a key, the Shoppex SDK creates the same key every time for the same request.

Listen for `order:manual_payment_pending`

Register a shop webhook (Settings → Webhooks) for order:manual_payment_pending. When a buyer submits manual payment instructions, Shoppex POSTs a signed payload to your URL. Extract the invoice UUID from data.uniqid and store it with your gateway’s pending-payment record if needed. Verify signatures with X-Shoppex-Signature-V2. See Webhooks.

Cloudflare Worker adapter (copy-paste)

This worker receives a generic JSON webhook from your payment provider, optionally checks a shared secret, then completes the Shoppex invoice. Worker secrets (Wrangler):

SHOPPEX_API_KEY — your shx_* key with invoices.write
PROVIDER_WEBHOOK_SECRET — shared secret your gateway sends (header or HMAC). Omit checks only in local dev

Expected provider JSON shape (customize to your PSP):

{
  "invoice_id": "4ea04c92-5cc3-4ea8-845c-cd3c7085796c",
  "status": "paid",
  "amount": "49.99",
  "currency": "USD"
}

worker.ts

interface ProviderWebhook {
  invoice_id?: string;
  status?: string;
  amount?: string | number;
  currency?: string;
}

const SHOPPEX_API = 'https://api.shoppex.io';

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    if (request.method !== 'POST') {
      return new Response('Method Not Allowed', { status: 405 });
    }

    const sharedSecret = request.headers.get('x-provider-secret');
    if (!env.PROVIDER_WEBHOOK_SECRET || sharedSecret !== env.PROVIDER_WEBHOOK_SECRET) {
      return new Response('Unauthorized', { status: 401 });
    }

    let payload: ProviderWebhook;
    try {
      payload = await request.json() as ProviderWebhook;
    } catch {
      return new Response('Bad Request', { status: 400 });
    }

    const invoiceUniqid = payload.invoice_id?.trim().toLowerCase();
    if (!invoiceUniqid) {
      return new Response('Missing invoice_id', { status: 400 });
    }

    if (payload.status?.toLowerCase() !== 'paid') {
      return new Response('Ignored', { status: 200 });
    }

    const completeResponse = await fetch(
      `${SHOPPEX_API}/dev/v1/invoices/${invoiceUniqid}/complete`,
      {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${env.SHOPPEX_API_KEY}`,
          'Content-Type': 'application/json',
          'Idempotency-Key': `complete-${invoiceUniqid}`,
        },
        body: JSON.stringify({
          note: `Auto-completed from provider webhook (amount=${payload.amount ?? 'n/a'} ${payload.currency ?? ''})`.trim(),
        }),
      },
    );

    if (completeResponse.status === 422) {
      const body = await completeResponse.text();
      if (/already completed/i.test(body)) {
        return new Response('Already completed', { status: 200 });
      }
      return new Response(body, { status: 422 });
    }

    if (!completeResponse.ok) {
      const body = await completeResponse.text();
      return new Response(body, { status: 502 });
    }

    return new Response('OK', { status: 200 });
  },
};

interface Env {
  SHOPPEX_API_KEY: string;
  PROVIDER_WEBHOOK_SECRET: string;
}

Deploy with Wrangler, then point your gateway’s webhook URL at the worker. Pass {{invoice_id}} in your manual gateway redirect URL or instructions so the provider echoes it back.

For redirect manual gateways, include {{invoice_id}} in the external checkout URL query string so your PSP webhook can return the same ID.

Redirect manual gateway example

Redirect URL in dashboard:

https://pay.example.com/checkout?amount={{amount}}&currency={{currency}}&reference={{invoice_id}}&email={{customer_email}}

When reference comes back on the provider webhook, map it to invoice_id in the worker above.

Security checklist

Verify provider signatures or shared secrets before calling Shoppex.
Optionally re-fetch the invoice with GET /dev/v1/invoices/{uniqid} and compare total / currency to the provider amount before completing.
Keep shx_* keys server-side only.
Use Idempotency-Key on every completion call.
Return 200 to your provider only after Shoppex accepts the completion (or the invoice is already completed).

Manual confirmation in the dashboard

If you do not automate completion, open the invoice in the dashboard when status is Awaiting Manual Confirmation, then Confirm Payment → Process Invoice. The Dev API complete call runs the same backend pipeline.

Payments guide

Hosted checkout and Developer API overview

Webhooks

Verify order:manual_payment_pending and order:paid

Developer API

Full API reference including POST /dev/v1/invoices/{uniqid}/complete

Payment gateways

Connect Stripe, PayPal, Cash App, and manual methods

Start here

Invoices and payments

Webhooks

Headless commerce

Storefront SDK

Checkout embeds

Integrations

Resellers

Email marketing

Tutorials

Complete or process manual-payment invoices

End-to-end flow

Prerequisites

Complete an invoice (minimal)

Listen for `order:manual_payment_pending`

Cloudflare Worker adapter (copy-paste)

Redirect manual gateway example

Security checklist

Manual confirmation in the dashboard

Payments guide

Webhooks

Developer API

Payment gateways

​End-to-end flow

​Prerequisites

​Complete an invoice (minimal)

​Listen for order:manual_payment_pending

​Cloudflare Worker adapter (copy-paste)

​Redirect manual gateway example

​Security checklist

​Manual confirmation in the dashboard

​Related docs

Payments guide

Webhooks

Developer API

Payment gateways

End-to-end flow

Prerequisites

Complete an invoice (minimal)

Listen for `order:manual_payment_pending`

Cloudflare Worker adapter (copy-paste)

Redirect manual gateway example

Security checklist

Manual confirmation in the dashboard

Related docs