DEV Community: kevin.s

Build a Cross-Border Crypto Payment Stack for Digital Sellers

kevin.s — Sun, 26 Jul 2026 08:59:01 +0000

A customer in another country buys a software license.

The checkout displays a price in USD. The customer pays with crypto on a supported network. The payment reaches paid, but the license is never delivered.

Another customer sends funds after a white-label payment address expires.

A third customer pays twice because the first transaction remains in the paying state longer than expected.

The seller accepts international payments.

The international selling workflow does not work reliably.

This is the difference between adding a crypto payment button and building a cross-border payment stack.

A Cross-Border Crypto Payment Stack connects:

Product pricing
-> International checkout
-> Crypto payment
-> Payment verification
-> Digital fulfillment
-> Customer visibility
-> Support
-> Reporting
-> Recovery

This article uses OxaPay as the payment infrastructure reference and a software license seller as the main implementation example.

The architecture is provider-agnostic and can also support digital downloads, courses, SaaS plans, memberships, research products, and remote service packages.

This article is part of 10 Crypto Payment Products Developers Can Build for Merchants.

Cross-border is more than buyer location

A payment does not become cross-border merely because the buyer and seller are in different countries.

A cross-border system must handle differences in:

language
pricing currency
payment asset
blockchain network
time zone
payment instructions
regional availability
refund and delivery policies
support expectations
financial reporting

Consider this order:

Product price: 49 USD
Buyer locale: de-DE
Buyer pays: USDT
Network: Tron
Seller reporting currency: EUR
Product: One-year software license
Delivery: Automatic

These values describe different parts of the transaction.

Do not compress them into one currency field.

What this product is

A Cross-Border Crypto Payment Stack is a merchant-facing system for selling digital products to international buyers.

It can include:

localized product and checkout pages
hosted or branded crypto checkout
immutable order pricing
configurable currencies and networks
verified payment events
automatic digital fulfillment
buyer-facing payment status
late-payment handling
support investigation
reconciliation
finance exports
optional partner payouts

The product is not:

a new blockchain
a crypto exchange
a custodial wallet
a legal or tax service
a method for bypassing regional rules
a guarantee that every buyer can pay from every country

The merchant remains responsible for determining where and under what conditions the product can be offered.

The developer provides the technical control layer.

How this differs from PaymentOps

A Crypto PaymentOps Service manages the internal operational lifecycle of payments.

This product packages that operational core for international digital selling.

Its cross-border responsibilities include:

Localized checkout
International buyer instructions
Pricing and payment currency separation
Regional merchant policies
Digital delivery
Buyer self-service status
Cross-border reporting fields

PaymentOps is the operational foundation.

The Cross-Border Stack is the complete merchant and buyer experience built on top of it.

Choose one digital seller niche

Do not begin by building for every kind of digital business.

The workflow for a software license seller is different from the workflow for a course creator or consulting business.

This article uses:

Software license seller

The complete outcome is:

Customer selects license
-> Order price is locked
-> Crypto invoice is created
-> Customer pays
-> Payment is verified
-> One license is assigned
-> Customer receives delivery
-> Seller receives an operational record

The same core can later support other fulfillment adapters.

Examples:

Digital download
-> Generate signed download entitlement

Online course
-> Create enrollment

SaaS plan
-> Grant subscription term

Premium community
-> Grant membership access

Remote service
-> Create project and intake workflow

Build one complete workflow before adding more product types.

Define the commercial transaction

Before creating a payment, create an authoritative local order.

The order should record:

merchant
customer
product
product version
product price
pricing currency
checkout locale
billing country when collected
accepted terms version
delivery type
refund policy version
timestamp

This creates a commercial snapshot.

A product price may change after checkout begins.

The existing order should not change with it.

Product catalog price today: 59 USD
Order price created yesterday: 49 USD

The customer pays the order price, not the latest catalog price.

Separate the currency concepts

A cross-border payment stack may involve several currency values.

Pricing currency

The currency used to price the product.

49 USD

Payment asset

The cryptocurrency sent by the customer.

USDT
BTC
LTC

Payment network

The blockchain network used to send the asset.

Tron
Ethereum
Polygon
Solana

Received asset

The asset recorded by the payment provider for the merchant payment.

Reporting currency

The currency the seller uses for internal reports.

USD
EUR
GBP

Do not assume these are identical.

A practical order record may look like:

{
  "order_value": "49.00",
  "pricing_currency": "USD",
  "payment_asset": "USDT",
  "payment_network": "Tron",
  "received_amount": "49.00",
  "reporting_currency": "EUR"
}

The reporting conversion should use a documented merchant policy and a stored rate snapshot.

Do not recalculate historical reports using today's rate.

Recommended architecture

+-------------------------+
| International Storefront|
+------------+------------+
             |
             | Product and locale
             v
+-------------------------+
| Order Service           |
+------------+------------+
             |
             | Locked commercial order
             v
+-------------------------+
| Checkout Service        |
+------------+------------+
             |
             | Generate payment
             v
+-------------------------+
| OxaPay                  |
+------------+------------+
             |
             | Signed callback
             v
+-------------------------+
| Webhook Receiver        |
+------------+------------+
             |
             | Verify and persist
             v
+-------------------------+
| Event Store + Outbox    |
+------------+------------+
             |
             v
+-------------------------+
| Payment Worker          |
+------------+------------+
             |
             | Verify latest state
             v
+-------------------------+
| Fulfillment Adapter     |
+------------+------------+
             |
       +-----+-------------------+
       |                         |
       v                         v
 License Delivery         Manual Review
       |
       v
Customer Status / Support / Reporting

The webhook request should not deliver the product directly.

It should validate and persist the event, create asynchronous work, and return quickly.

A cross-border data model

CREATE TABLE merchants (
  id UUID PRIMARY KEY,
  name TEXT NOT NULL,
  reporting_currency TEXT NOT NULL,
  default_locale TEXT NOT NULL DEFAULT 'en-US',
  timezone TEXT NOT NULL DEFAULT 'UTC',
  support_email TEXT,
  created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE TABLE products (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  sku TEXT NOT NULL,
  name TEXT NOT NULL,
  product_type TEXT NOT NULL,
  fulfillment_type TEXT NOT NULL,
  price NUMERIC(20, 8) NOT NULL,
  pricing_currency TEXT NOT NULL,
  active BOOLEAN NOT NULL DEFAULT TRUE,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (merchant_id, sku)
);

CREATE TABLE customers (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  email TEXT,
  name TEXT,
  locale TEXT,
  billing_country TEXT,
  created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE TABLE orders (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  customer_id UUID REFERENCES customers(id),
  product_id UUID NOT NULL REFERENCES products(id),
  order_number TEXT NOT NULL,
  product_name_snapshot TEXT NOT NULL,
  product_version_snapshot TEXT,
  order_value NUMERIC(20, 8) NOT NULL,
  pricing_currency TEXT NOT NULL,
  checkout_locale TEXT NOT NULL,
  billing_country TEXT,
  fulfillment_type TEXT NOT NULL,
  terms_version TEXT,
  refund_policy_version TEXT,
  order_status TEXT NOT NULL DEFAULT 'pending_payment',
  fulfillment_status TEXT NOT NULL DEFAULT 'not_started',
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  paid_at TIMESTAMP,
  fulfilled_at TIMESTAMP,
  UNIQUE (merchant_id, order_number)
);

CREATE TABLE payment_sessions (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  order_id UUID NOT NULL REFERENCES orders(id),
  provider TEXT NOT NULL DEFAULT 'oxapay',
  provider_order_id TEXT NOT NULL,
  provider_track_id TEXT,
  checkout_mode TEXT NOT NULL,
  provider_status TEXT,
  internal_status TEXT NOT NULL DEFAULT 'created',
  requested_amount NUMERIC(20, 8) NOT NULL,
  pricing_currency TEXT NOT NULL,
  payment_asset TEXT,
  payment_network TEXT,
  received_amount NUMERIC(36, 18),
  payment_url TEXT,
  expires_at TIMESTAMP,
  paid_at TIMESTAMP,
  raw_provider_response JSONB,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (provider, provider_track_id),
  UNIQUE (provider_order_id)
);

CREATE TABLE payment_events (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  payment_session_id UUID REFERENCES payment_sessions(id),
  provider TEXT NOT NULL,
  payload_hash TEXT NOT NULL,
  provider_track_id TEXT,
  provider_status TEXT,
  raw_payload JSONB NOT NULL,
  signature_valid BOOLEAN NOT NULL,
  source TEXT NOT NULL,
  received_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (merchant_id, payload_hash)
);

CREATE TABLE fulfillment_jobs (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  order_id UUID NOT NULL REFERENCES orders(id),
  payment_session_id UUID NOT NULL REFERENCES payment_sessions(id),
  fulfillment_type TEXT NOT NULL,
  idempotency_key TEXT NOT NULL UNIQUE,
  status TEXT NOT NULL DEFAULT 'queued',
  attempt_count INTEGER NOT NULL DEFAULT 0,
  last_error TEXT,
  next_attempt_at TIMESTAMP,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  completed_at TIMESTAMP
);

CREATE TABLE delivery_entitlements (
  id UUID PRIMARY KEY,
  order_id UUID NOT NULL REFERENCES orders(id),
  payment_session_id UUID NOT NULL REFERENCES payment_sessions(id),
  entitlement_type TEXT NOT NULL,
  entitlement_reference TEXT,
  status TEXT NOT NULL,
  expires_at TIMESTAMP,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (payment_session_id)
);

CREATE TABLE reporting_snapshots (
  id UUID PRIMARY KEY,
  order_id UUID NOT NULL REFERENCES orders(id),
  payment_session_id UUID NOT NULL REFERENCES payment_sessions(id),
  order_value NUMERIC(20, 8) NOT NULL,
  pricing_currency TEXT NOT NULL,
  received_amount NUMERIC(36, 18),
  received_asset TEXT,
  reporting_currency TEXT NOT NULL,
  reporting_value NUMERIC(20, 8),
  conversion_rate NUMERIC(36, 18),
  rate_source TEXT,
  rate_timestamp TIMESTAMP,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (payment_session_id)
);

CREATE TABLE operational_cases (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  order_id UUID REFERENCES orders(id),
  payment_session_id UUID REFERENCES payment_sessions(id),
  case_type TEXT NOT NULL,
  severity TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'open',
  summary TEXT NOT NULL,
  recommended_action TEXT,
  evidence JSONB,
  resolution_note TEXT,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  resolved_at TIMESTAMP
);

CREATE TABLE outbox_jobs (
  id UUID PRIMARY KEY,
  topic TEXT NOT NULL,
  payload JSONB NOT NULL,
  status TEXT NOT NULL DEFAULT 'pending',
  attempt_count INTEGER NOT NULL DEFAULT 0,
  available_at TIMESTAMP NOT NULL DEFAULT NOW(),
  published_at TIMESTAMP,
  created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

The separation between:

Order
Payment session
Payment event
Fulfillment job
Delivery entitlement
Reporting snapshot

is essential.

Each represents a different business fact.

Create the order before the invoice

Never let the browser submit an authoritative price.

Load the product and price from your own database.

import crypto from "node:crypto";

export async function createDigitalOrder({
  merchantId,
  customer,
  productId,
  locale,
  billingCountry,
  acceptedTermsVersion,
}) {
  const product = await db.product.findFirst({
    where: {
      id: productId,
      merchantId,
      active: true,
    },
  });

  if (!product) {
    throw new Error("Product is unavailable");
  }

  await assertMerchantCanSell({
    merchantId,
    billingCountry,
    product,
  });

  return db.order.create({
    data: {
      merchantId,
      customerId: customer.id,
      productId: product.id,
      orderNumber: createOrderNumber(),
      productNameSnapshot: product.name,
      productVersionSnapshot:
        product.currentVersion ?? null,
      orderValue: product.price,
      pricingCurrency:
        product.pricingCurrency,
      checkoutLocale: locale,
      billingCountry,
      fulfillmentType:
        product.fulfillmentType,
      termsVersion: acceptedTermsVersion,
      refundPolicyVersion:
        product.refundPolicyVersion,
      orderStatus: "pending_payment",
      fulfillmentStatus: "not_started",
    },
  });
}

function createOrderNumber() {
  return `ORD-${crypto
    .randomUUID()
    .replaceAll("-", "")
    .slice(0, 12)
    .toUpperCase()}`;
}

assertMerchantCanSell applies merchant-configured regional and product policies.

It should not pretend to make a legal determination automatically.

Create an OxaPay hosted invoice

For the first version, hosted invoices are usually the safer option.

const OXAPAY_API =
  "https://api.oxapay.com/v1";

export async function createHostedPayment({
  merchant,
  order,
  customer,
}) {
  const providerOrderId =
    `digital_${order.id}`;

  const session =
    await db.paymentSession.create({
      data: {
        merchantId: merchant.id,
        orderId: order.id,
        provider: "oxapay",
        providerOrderId,
        checkoutMode: "invoice",
        internalStatus: "created",
        requestedAmount: order.orderValue,
        pricingCurrency:
          order.pricingCurrency,
      },
    });

  try {
    const merchantApiKey =
      await decryptSecret(
        merchant.oxapayMerchantApiKeyEncrypted,
      );

    const response = await fetch(
      `${OXAPAY_API}/payment/invoice`,
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          merchant_api_key: merchantApiKey,
        },
        body: JSON.stringify({
          amount: order.orderValue,
          currency: order.pricingCurrency,
          order_id: providerOrderId,
          email: customer.email,
          description:
            `Digital order ${order.orderNumber}`,
          callback_url:
            `${process.env.APP_URL}/webhooks/oxapay/${merchant.webhookEndpointId}`,
          return_url:
            `${process.env.APP_URL}/orders/${order.orderNumber}/status`,
          lifetime: 60,
          sandbox:
            process.env.NODE_ENV !==
            "production",
        }),
      },
    );

    const payload = await response.json();

    if (!response.ok) {
      throw new Error(
        payload?.error?.message ??
          `Invoice creation failed with ${response.status}`,
      );
    }

    const payment = payload.data;

    return db.paymentSession.update({
      where: { id: session.id },
      data: {
        providerTrackId:
          String(payment.track_id),
        providerStatus: "new",
        internalStatus:
          "invoice_created",
        paymentUrl: payment.payment_url,
        expiresAt: payment.expired_at
          ? new Date(
              Number(payment.expired_at) *
                1000,
            )
          : null,
        rawProviderResponse: payload,
      },
    });
  } catch (error) {
    await db.paymentSession.update({
      where: { id: session.id },
      data: {
        internalStatus:
          "creation_failed",
      },
    });

    throw error;
  }
}

The buyer returning to the return_url does not prove payment.

Only a verified payment event or a verified Payment Information lookup should move the order toward fulfillment.

Hosted invoice or white-label?

Use hosted invoices when

launch speed matters
the merchant accepts a redirect
the main value is fulfillment and operations
the seller wants less frontend complexity
the first version is still validating demand

Use white-label when

payment must remain inside the seller's interface
localized instructions are essential
the merchant needs more branding control
the checkout includes product-specific guidance
the payment state page is part of the product

White-label checkout requires additional care.

The page must clearly display:

payment asset
network
exact amount
address
QR code
expiration time
current payment state
late-payment warning

OxaPay white-label addresses are valid only for their configured lifetime. The checkout must treat expiration as a hard boundary.

Do not encourage a customer to send funds after expiry.

Configure payment methods dynamically

Do not hardcode currency and network combinations.

OxaPay provides a Supported Currencies endpoint that returns cryptocurrency and network information.

A merchant configuration can define:

{
  "preferred_methods": [
    {
      "currency": "USDT",
      "networks": ["Tron", "Polygon"]
    },
    {
      "currency": "LTC",
      "networks": ["Litecoin"]
    }
  ],
  "hidden_methods": [],
  "stablecoin_first": true
}

Validate the merchant configuration against current provider-supported methods.

The checkout should not display a network combination the provider no longer supports.

Stablecoin-first is a UX policy

Some digital sellers prefer to present stablecoins first because the product itself is priced in fiat terms.

That can make the payment amount easier for buyers to understand.

It does not make the transaction risk-free.

The product should not claim:

Guaranteed value
Zero settlement risk
Universal availability

Stablecoins still introduce network, issuer, liquidity, operational, and regional considerations.

Treat stablecoin-first as a configurable checkout preference.

Validate OxaPay callbacks

OxaPay signs payment callbacks using HMAC SHA-512 over the raw request body.

Use a merchant-specific webhook endpoint so the server knows which Merchant API Key should validate the request.

import crypto from "node:crypto";
import express from "express";

const app = express();

app.post(
  "/webhooks/oxapay/:endpointId",
  express.raw({
    type: "application/json",
  }),
  async (req, res) => {
    const merchant =
      await db.merchant.findUnique({
        where: {
          webhookEndpointId:
            req.params.endpointId,
        },
      });

    if (!merchant) {
      return res
        .status(404)
        .send("unknown endpoint");
    }

    const rawBody = req.body;
    const receivedHmac =
      req.get("HMAC");

    const merchantApiKey =
      await decryptSecret(
        merchant
          .oxapayMerchantApiKeyEncrypted,
      );

    const expectedHmac = crypto
      .createHmac(
        "sha512",
        merchantApiKey,
      )
      .update(rawBody)
      .digest("hex");

    if (
      !safeEqualSha512(
        receivedHmac,
        expectedHmac,
      )
    ) {
      await recordRejectedCallback({
        merchantId: merchant.id,
        reason: "invalid_hmac",
      });

      return res
        .status(401)
        .send("invalid signature");
    }

    let payload;

    try {
      payload = JSON.parse(
        rawBody.toString("utf8"),
      );
    } catch {
      return res
        .status(400)
        .send("invalid json");
    }

    const payloadHash = crypto
      .createHash("sha256")
      .update(rawBody)
      .digest("hex");

    try {
      await persistEventAndOutbox({
        merchant,
        payload,
        payloadHash,
      });

      return res
        .status(200)
        .send("ok");
    } catch (error) {
      console.error(
        "Payment event persistence failed",
        error,
      );

      return res
        .status(500)
        .send("failed");
    }
  },
);

function safeEqualSha512(
  received,
  expected,
) {
  const sha512Hex =
    /^[a-f0-9]{128}$/i;

  if (
    !received ||
    !expected ||
    !sha512Hex.test(received) ||
    !sha512Hex.test(expected)
  ) {
    return false;
  }

  return crypto.timingSafeEqual(
    Buffer.from(received, "hex"),
    Buffer.from(expected, "hex"),
  );
}

The payment event and outbox job should be written inside one database transaction.

Store event
+
Create processing job
+
Commit

If the queue is temporarily unavailable, the outbox dispatcher can retry publishing later.

Do not fulfill on `paying`

OxaPay payment callbacks may first report:

paying

Then later:

paid

Map these states into buyer-facing language.

function mapPaymentStatus(status) {
  const normalized = String(
    status ?? "",
  )
    .trim()
    .toLowerCase();

  const statuses = {
    new: "created",
    waiting: "waiting",
    paying: "confirming",
    paid: "paid",
    manual_accept:
      "manually_accepted",
    underpaid: "underpaid",
    expired: "expired",
    refunding:
      "refund_in_progress",
    refunded: "refunded",
  };

  return statuses[normalized] ??
    "unknown";
}

For paying, show:

Payment detected. Waiting for completion.
Do not send another payment.

Do not deliver the product yet.

For paid, the fulfillment worker can begin after verifying the order and provider state.

Verify before digital delivery

Before assigning an irreversible entitlement, retrieve Payment Information.

async function fetchOxaPayPayment({
  merchantApiKey,
  trackId,
}) {
  const response = await fetch(
    `${OXAPAY_API}/payment/${encodeURIComponent(trackId)}`,
    {
      method: "GET",
      headers: {
        "Content-Type":
          "application/json",
        merchant_api_key:
          merchantApiKey,
      },
    },
  );

  const payload = await response.json();

  if (!response.ok) {
    throw new Error(
      payload?.error?.message ??
        `Payment lookup failed with ${response.status}`,
    );
  }

  return payload.data;
}

function assertPaymentMatchesOrder({
  payment,
  session,
  order,
}) {
  if (
    String(payment.status)
      .toLowerCase() !== "paid"
  ) {
    throw new PermanentDeliveryError(
      "Payment is not paid",
    );
  }

  if (
    String(payment.order_id) !==
    String(session.providerOrderId)
  ) {
    throw new PermanentDeliveryError(
      "Provider order_id mismatch",
    );
  }

  if (
    decimal(payment.amount).lessThan(
      decimal(order.orderValue),
    )
  ) {
    throw new PermanentDeliveryError(
      "Payment amount does not satisfy order",
    );
  }
}

Use decimal arithmetic for payment values.

Do not use ordinary floating-point comparisons.

Deliver a software license exactly once

The same payment must not assign two licenses.

export async function fulfillLicenseOrder({
  orderId,
  paymentSessionId,
}) {
  const idempotencyKey = [
    orderId,
    paymentSessionId,
    "assign_license",
  ].join(":");

  const existingJob =
    await db.fulfillmentJob.findUnique({
      where: { idempotencyKey },
    });

  if (
    existingJob?.status === "completed"
  ) {
    return existingJob;
  }

  const job =
    existingJob ??
    (await db.fulfillmentJob.create({
      data: {
        merchantId:
          order.merchantId,
        orderId,
        paymentSessionId,
        fulfillmentType:
          "software_license",
        idempotencyKey,
        status: "running",
        attemptCount: 1,
      },
    }));

  try {
    const license =
      await reserveLicenseKey({
        productId: order.productId,
        orderId,
        idempotencyKey,
      });

    const entitlement =
      await db.deliveryEntitlement.upsert({
        where: {
          paymentSessionId,
        },
        create: {
          orderId,
          paymentSessionId,
          entitlementType:
            "software_license",
          entitlementReference:
            license.id,
          status: "active",
        },
        update: {},
      });

    await sendLicenseDelivery({
      customerEmail:
        order.customer.email,
      orderNumber:
        order.orderNumber,
      licenseKey: license.key,
      locale:
        order.checkoutLocale,
      idempotencyKey:
        `${idempotencyKey}:email`,
    });

    await db.$transaction([
      db.order.update({
        where: { id: orderId },
        data: {
          orderStatus: "completed",
          fulfillmentStatus:
            "delivered",
          fulfilledAt: new Date(),
        },
      }),

      db.fulfillmentJob.update({
        where: { id: job.id },
        data: {
          status: "completed",
          completedAt: new Date(),
        },
      }),
    ]);

    return entitlement;
  } catch (error) {
    await recordFulfillmentFailure({
      jobId: job.id,
      error,
    });

    throw error;
  }
}

Separate license assignment from email delivery.

If the email provider fails, retry the email.

Do not assign another license.

Other fulfillment adapters

Use a shared adapter interface.

const fulfillmentAdapters = {
  software_license:
    fulfillLicenseOrder,
  digital_download:
    fulfillDownloadOrder,
  course_access:
    fulfillCourseOrder,
  saas_plan:
    fulfillSaaSOrder,
  community_access:
    fulfillCommunityOrder,
  manual_service:
    fulfillServiceOrder,
};

Each adapter should define:

required input
idempotency key
success evidence
retryable failures
permanent failures
customer message
support escalation

A generic fulfilled = true field is not enough.

Make delivery links temporary

For downloadable products, do not email a permanent public file URL.

Create a delivery entitlement and generate short-lived signed links.

Payment confirmed
-> Download entitlement created
-> Customer opens status page
-> Signed link generated
-> Link expires
-> Entitlement remains valid under merchant policy

This allows the seller to:

limit link lifetime
regenerate links
track downloads
revoke access after a refund
avoid exposing storage URLs

The entitlement is the durable access record.

The signed URL is temporary delivery infrastructure.

Build a localized customer status page

Give every order a persistent status page:

/orders/ORD-2026-1042/status

Show:

product name
order number
order value
pricing currency
selected payment asset and network
invoice expiry
payment state
delivery state
support contact
next customer action

Useful states include:

Waiting for payment

Complete the payment before the displayed expiration time.

Payment detected

We detected payment activity. Do not send another payment while it is being processed.

Payment confirmed

Your payment is confirmed. We are preparing your product.

Delivered

Your product is ready. Check your email or use the secure delivery option below.

Expired

This payment session has expired. Do not send funds using the expired payment details.

Under review

We found a payment issue that requires review. You do not need to send another payment.

Translate business meaning, not raw provider terminology.

Localize the high-friction content first

A complete multilingual application is not necessary for the MVP.

Start with the text most likely to cause payment problems:

checkout instructions
network warnings
expiry warning
payment-detected message
delivery expectations
refund policy
support instructions

Do not rely only on machine translation for legal or policy text.

Store which policy version and locale the customer saw.

terms_version = 2026-07-en
refund_policy_version = 2026-06-de

This creates a clearer operational record.

Use UTC internally

Store operational timestamps in UTC:

order creation
invoice expiration
payment detection
payment confirmation
fulfillment
refund
support actions

Display them in the customer's or merchant's selected time zone.

Do not store ambiguous local timestamps without an offset.

Cross-border support becomes much harder when three systems show different local times.

Apply regional policies before creating payment

A merchant may need to disable:

specific billing countries
specific products in some regions
selected payment methods
selected networks
fulfillment types
manual-service orders

Implement merchant-configurable rules.

async function assertMerchantCanSell({
  merchantId,
  billingCountry,
  product,
}) {
  const policy =
    await loadRegionalPolicy({
      merchantId,
      billingCountry,
      productId: product.id,
    });

  if (policy?.salesDisabled) {
    throw new CheckoutPolicyError(
      "This product is unavailable for the selected region",
    );
  }
}

This is an enforcement mechanism for merchant policy.

It is not a substitute for legal review.

Do not market IP blocking as complete compliance.

IP location can be inaccurate and should not be the only business signal.

Treat late payments as exceptions

Late payments create one of the hardest buyer-support scenarios.

Possible sequence:

Invoice expires
-> Customer sends payment using old details
-> New invoice is created
-> Customer may now have two payment attempts

The system should:

Preserve the expired session.
Keep the order unresolved.
Prevent automatic duplicate fulfillment.
Search Payment Information and Payment History.
Create a late-payment case.
Let an authorized operator decide the outcome.
Record the decision.

Never tell a customer to pay again before checking an existing payment claim.

For white-label payment addresses, the customer must be clearly warned not to send funds after expiration.

Handle duplicate payments deliberately

A buyer may pay two sessions for the same order.

Do not automatically deliver twice.

Create a case:

duplicate_payment_for_order

Evidence should include:

both track_id values
paid amounts
payment assets
networks
transaction hashes
creation times
payment times
fulfillment state

The merchant policy may allow:

refund review
account credit
second entitlement
manual resolution

The software should expose the duplicate.

It should not invent the merchant decision.

Recover missed events with Payment History

Webhooks are the real-time path.

They should not be the only path.

A recovery job can query OxaPay Payment History using an overlapping time window.

export async function backfillRecentPayments({
  merchant,
  fromDate,
  toDate,
}) {
  const merchantApiKey =
    await decryptSecret(
      merchant.oxapayMerchantApiKeyEncrypted,
    );

  const params = new URLSearchParams({
    from_date: String(
      Math.floor(
        fromDate.getTime() / 1000,
      ),
    ),
    to_date: String(
      Math.floor(
        toDate.getTime() / 1000,
      ),
    ),
    page: "1",
    size: "100",
  });

  const response = await fetch(
    `${OXAPAY_API}/payment?${params}`,
    {
      method: "GET",
      headers: {
        "Content-Type":
          "application/json",
        merchant_api_key:
          merchantApiKey,
      },
    },
  );

  const payload = await response.json();

  if (!response.ok) {
    throw new Error(
      payload?.error?.message ??
        `Payment history failed with ${response.status}`,
    );
  }

  for (
    const payment of
      extractPaymentItems(payload)
  ) {
    await reconcileProviderPayment({
      merchant,
      payment,
      source:
        "payment_history_backfill",
    });
  }
}

The exact response object should be mapped from the current API response and stored as raw evidence.

Use overlapping windows because jobs can fail or provider records can appear later.

Reconcile business outcomes

The Cross-Border Stack does not need to duplicate the full Payment Reconciliation Tool.

It should integrate the core checks required for digital selling.

Examples:

Provider payment paid
Order still pending

Order paid
Delivery not completed

Delivery completed
No confirmed provider payment

Payment paid
Reporting snapshot missing

Payment paid twice
One order

Expired white-label session
Customer claims payment

Refunded payment
License still active

The main operational view should be:

Needs attention

not another long transaction table.

Build support around evidence

A Crypto Payment Support Desk can provide the complete agent interface.

The Cross-Border Stack should at minimum let support search by:

order number
customer email
track_id
transaction hash
product
payment asset
network
payment status
delivery status
creation date

A readable timeline might show:

12:01 UTC  Order created
12:01 UTC  Invoice generated
12:05 UTC  Payment detected
12:07 UTC  Payment confirmed
12:07 UTC  License allocation started
12:08 UTC  License assigned
12:08 UTC  Delivery email failed
12:09 UTC  Retry scheduled
12:12 UTC  Email delivered

This tells support whether the issue belongs to:

checkout
payment
order matching
fulfillment
email delivery
customer action

Use customer-safe support templates

Payment detected

We detected payment activity for your order. The payment is still being processed, so please do not send another transaction.

Paid but not delivered

Your payment has been confirmed. Product delivery did not complete automatically, and our team is reviewing the order. You do not need to pay again.

Expired payment session

This payment session has expired. Do not send funds using the expired payment details. Create a new payment request or contact support if you already sent a transaction.

Payment cannot be matched

We could not safely match the available information to your order. Please send the transaction hash, payment asset, network, amount, and approximate payment time.

Do not tell a customer that funds are lost, recoverable, or refundable until the evidence and merchant policy support that conclusion.

Build reporting records at payment time

Finance reports should not reconstruct historical facts from live product data.

Create a reporting snapshot when the payment is accepted.

Record:

order value
pricing currency
payment amount
payment asset
network
provider track_id
transaction hash
reporting currency
conversion rate
conversion source
rate timestamp
customer billing country when collected
product and SKU
refund state
fulfillment state

The reporting snapshot is not a tax return.

It is a clean operational export that the merchant can provide to its accounting process.

Optional payouts belong in a separate module

Some digital sellers pay:

affiliates
contractors
instructors
creators
referral partners

Do not trigger payouts directly from the customer payment webhook.

Use:

Confirmed revenue
-> Ledger entry
-> Partner balance
-> Payout request
-> Approval
-> OxaPay Payout API
-> Payout status tracking

The Revenue Split and Payout System covers this architecture in more depth.

Payouts require:

separate Payout API Key
destination controls
approval permissions
immutable ledger entries
payout limits
audit history
reconciliation

The first Cross-Border Stack MVP does not need payout automation.

Security baseline

Before selling the stack, implement:

HTTPS-only callbacks
HMAC validation over the raw body
timing-safe signature comparison
encrypted Merchant API Keys
separate Payout API Keys
strict tenant isolation
event deduplication
action-level idempotency
transactional outbox
background fulfillment jobs
decimal financial calculations
signed download links
encrypted or masked license data
role-based admin access
audit logs for manual actions
secret masking in logs
rate-limited status and support endpoints
Payment Information verification
Payment History recovery
alerting for paid-but-not-delivered orders

Payment success without delivery success must create a visible incident.

Compliance and policy boundaries

Do not position the product as:

Payments without rules
Guaranteed global availability
A way around payment restrictions
Risk-free stablecoin settlement
Automatic legal compliance

A responsible product can provide:

merchant-configurable regional rules
disabled-country settings
product availability controls
policy-version tracking
consent records
refund-policy display
manual-review flags
exports
audit logs
customer-support records

The merchant and qualified professionals determine the applicable tax, legal, sanctions, consumer-protection, and refund requirements.

Your system enforces the resulting technical policies.

The MVP

Build one complete flow for one digital seller niche.

For a software license seller:

Product selected
-> Authoritative order created
-> Hosted OxaPay invoice generated
-> Payment callback verified
-> Payment Information checked
-> One license assigned
-> Delivery email sent
-> Customer status updated
-> Reporting snapshot created

The MVP should include:

one merchant
product catalog
localized checkout copy
local order creation
hosted OxaPay invoice
payment-session storage
HMAC-validated webhook
event and outbox storage
Payment Information verification
idempotent license assignment
customer status page
support search
needs-attention queue
Payment History backfill
CSV export

Do not include in version one:

every digital product niche
dozens of languages
automated partner payouts
multiple payment providers
full accounting
tax calculation
complex discount engines
custom treasury management
visual automation builders

Prove the payment-to-delivery workflow first.

Production expansion

After the first seller proves demand, add:

white-label checkout
payment-method controls
additional locales
additional fulfillment adapters
static-address prepaid balances
agency merchant workspaces
finance integrations
configurable refund workflows
team permissions
incident alerts
SLA reporting
partner payout module
merchant-facing API
Make or n8n integrations

Expansion should follow repeated merchant requirements.

Do not add features because they sound like part of a payment platform.

Product positioning

Weak positioning:

Accept crypto payments internationally.

Better positioning:

Crypto checkout for digital sellers.

Stronger positioning:

A cross-border crypto payment stack that connects international checkout to verified digital delivery, customer status, support, recovery, and finance-ready records.

Niche-specific positioning is even stronger:

Cross-border crypto checkout for software license sellers, with verified payment events, one-time license delivery, localized buyer instructions, and paid-but-not-delivered recovery.

The merchant is not purchasing access to an endpoint.

They are purchasing a reliable international order outcome.

What makes this a real product?

A basic integration says:

Create crypto invoice
-> Wait for paid
-> Send product

A production Cross-Border Stack says:

Create authoritative commercial order
-> Preserve pricing and policy snapshot
-> Apply merchant regional rules
-> Generate supported payment session
-> Explain asset, network, and expiry
-> Validate signed callback
-> Preserve payment evidence
-> Verify latest provider state
-> Deliver product idempotently
-> Expose customer status
-> Recover missed events
-> Reconcile payment and delivery
-> Create historical reporting record
-> Surface every unresolved exception

That is the difference between a payment button and international digital commerce infrastructure.

Final takeaway

Digital sellers do not only need a way to receive crypto from another country.

They need a reliable path from international buyer intent to completed product delivery.

OxaPay provides the payment primitives:

hosted invoices
white-label payment details
static addresses
unique track_id references
Merchant order_id references
HMAC-signed payment callbacks
Payment Information
Payment History
supported currency and network data
optional payout APIs

The developer builds the cross-border operating layer:

localized checkout
authoritative orders
currency separation
network instructions
regional merchant policies
verified fulfillment
customer visibility
support evidence
reconciliation
finance-ready records

Start with one seller type.

Price one product clearly.

Accept one verified payment.

Deliver one digital entitlement exactly once.

Make every exception visible.

That is how international crypto checkout becomes a merchant product rather than another API integration.

Which niche would you start with: software licenses, digital downloads, courses, SaaS products, or remote services?

References

OxaPay

Build a Crypto Payment Support Desk

kevin.s — Thu, 23 Jul 2026 06:39:13 +0000

A customer opens a support ticket:

I paid 20 minutes ago, but my order is still pending.

The support agent can see the order, but not the payment.

The payment provider shows activity, but the merchant application did not update. A webhook may have failed. Fulfillment may have crashed. The invoice may have expired before the transaction arrived.

The agent now has two options:

Ask a developer to investigate.
Give the customer a vague answer and wait.

Neither option scales.

A Crypto Payment Support Desk gives support teams the evidence, context, and controlled actions they need to investigate payment cases without searching raw logs or interrupting developers.

It is not another payment dashboard.

It is the operational interface between payment infrastructure, merchant systems, and customer support.

This article uses OxaPay as the payment infrastructure reference, but the architecture is provider-agnostic.

The problem is not payment status

A single status does not explain what happened.

Consider this state:

Payment: paid
Order: paid
Fulfillment: failed

The customer paid successfully, but the merchant still owes them a product or service.

Now consider this:

Payment: paying
Order: paid
Fulfillment: completed

The merchant delivered before the payment reached the approved paid state.

Both cases require support attention, but for completely different reasons.

An agent needs more than:

status = paid

They need to know:

which order belongs to the payment
when the payment session was created
which status changes occurred
whether the webhook was received and verified
whether the merchant application processed it
whether fulfillment started
whether fulfillment completed
whether a reconciliation mismatch exists
what action is safe
what the customer should be told

The support product is built around this context.

Where the Support Desk fits

A Crypto PaymentOps service manages the broader payment lifecycle.

A crypto payment reconciliation tool detects disagreements between payments, orders, fulfillment, and finance records.

The Support Desk has a narrower role:

Turn payment evidence and operational exceptions into cases that a support agent can understand and resolve safely.

The reconciliation engine may detect:

Provider payment is paid
Local order is pending

The Support Desk should then show the agent:

the affected customer
the order and payment identifiers
the event timeline
the evidence behind the mismatch
the recommended action
the actions the agent is authorized to perform
a safe response to send to the customer

Reconciliation finds the problem.

The Support Desk helps a person handle it.

Design around support questions

Start with the questions agents receive most often.

Typical tickets include:

I paid, but my order is still pending.
My invoice expired after I sent the payment.
I sent less than the requested amount.
The payment is still confirming.
My payment is complete, but I did not receive the product.
I paid using an old invoice.
I cannot find the transaction in my account.
I used a different network or currency.
My subscription was not activated.
My payment was refunded, but the account state is unclear.

Each question should map to a defined case type, evidence checklist, escalation path, and customer response.

Without that structure, the product becomes another log viewer.

The case workspace

Every support case should open into one workspace.

The agent should not need to switch between the merchant store, payment provider, webhook logs, fulfillment system, and support tool.

A useful workspace has five areas.

Customer and order context

Show:

customer name or email
merchant order ID
product or plan
expected amount
expected currency
order status
fulfillment status
account or subscription status

Payment context

Show:

OxaPay track_id
payment type
requested amount
paid amount
payment currency
selected network
current provider status
invoice creation time
expiry time
transaction hash when available
latest provider verification time

Evidence timeline

Combine payment and merchant events into one chronological view.

10:03:12  Merchant order created
10:03:13  OxaPay invoice created
10:03:13  track_id linked to order
10:04:42  Webhook received: paying
10:04:42  HMAC signature verified
10:05:11  Webhook received: paid
10:05:12  Order marked paid
10:05:12  Fulfillment job queued
10:05:18  Fulfillment failed
10:10:00  Support case created

Diagnosis

Show:

case type
priority
likely failure layer
supporting evidence
missing evidence
recommended action
escalation owner

Safe actions

Only show actions the current agent can perform.

Examples:

refresh payment information
resend a customer-safe message
retry an idempotent fulfillment job
assign the case
request developer review
request finance review
close the case with a resolution note

Do not expose unrestricted payment overrides to ordinary support agents.

Add support-specific tables

Your PaymentOps database may already contain orders, payment sessions, payment events, and fulfillment jobs.

The Support Desk should add support-specific records instead of duplicating the entire payment model.

CREATE TABLE support_cases (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL,
  order_id UUID,
  payment_session_id UUID,
  reconciliation_case_id UUID,
  case_type TEXT NOT NULL,
  priority TEXT NOT NULL DEFAULT 'normal',
  status TEXT NOT NULL DEFAULT 'open',
  assigned_to UUID,
  summary TEXT NOT NULL,
  recommended_action TEXT,
  customer_message_key TEXT,
  opened_by TEXT NOT NULL,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
  resolved_at TIMESTAMP
);

CREATE TABLE support_case_notes (
  id UUID PRIMARY KEY,
  case_id UUID NOT NULL REFERENCES support_cases(id),
  author_id UUID,
  author_role TEXT NOT NULL,
  visibility TEXT NOT NULL DEFAULT 'internal',
  note TEXT NOT NULL,
  created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE TABLE support_actions (
  id UUID PRIMARY KEY,
  case_id UUID NOT NULL REFERENCES support_cases(id),
  actor_id UUID NOT NULL,
  actor_role TEXT NOT NULL,
  action_type TEXT NOT NULL,
  idempotency_key TEXT,
  status TEXT NOT NULL,
  request_data JSONB,
  result_data JSONB,
  error_message TEXT,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  completed_at TIMESTAMP,
  UNIQUE (idempotency_key)
);

CREATE TABLE provider_snapshots (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL,
  payment_session_id UUID,
  provider TEXT NOT NULL,
  provider_track_id TEXT NOT NULL,
  source TEXT NOT NULL,
  raw_response JSONB NOT NULL,
  fetched_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE TABLE timeline_events (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL,
  order_id UUID,
  payment_session_id UUID,
  support_case_id UUID,
  source TEXT NOT NULL,
  event_type TEXT NOT NULL,
  title TEXT NOT NULL,
  details JSONB,
  occurred_at TIMESTAMP NOT NULL,
  recorded_at TIMESTAMP NOT NULL DEFAULT NOW()
);

The timeline_events table is especially useful.

Instead of asking the UI to combine several raw tables on every request, your services can write normalized events into a shared timeline.

Possible sources include:

merchant_order
oxapay_webhook
provider_lookup
fulfillment_worker
reconciliation_engine
support_agent
finance_system

Raw provider payloads can remain available to authorized developers, while support agents see readable timeline events.

Build a support case snapshot

The frontend should request one normalized case object.

It should not call five backend services directly.

export async function buildSupportCaseSnapshot(caseId, actor) {
  const supportCase = await db.supportCase.findUnique({
    where: { id: caseId },
  });

  if (!supportCase) {
    throw new Error("Support case not found");
  }

  assertMerchantAccess(actor, supportCase.merchantId);

  const [
    order,
    payment,
    timeline,
    notes,
    reconciliationCase,
  ] = await Promise.all([
    supportCase.orderId
      ? db.order.findUnique({
          where: { id: supportCase.orderId },
        })
      : null,

    supportCase.paymentSessionId
      ? db.paymentSession.findUnique({
          where: { id: supportCase.paymentSessionId },
          include: {
            transactions: true,
            fulfillmentJobs: true,
          },
        })
      : null,

    db.timelineEvent.findMany({
      where: { supportCaseId: caseId },
      orderBy: { occurredAt: "asc" },
    }),

    db.supportCaseNote.findMany({
      where: {
        caseId,
        visibility: actor.isCustomer ? "customer" : undefined,
      },
      orderBy: { createdAt: "asc" },
    }),

    supportCase.reconciliationCaseId
      ? db.reconciliationCase.findUnique({
          where: { id: supportCase.reconciliationCaseId },
        })
      : null,
  ]);

  return {
    case: supportCase,
    customer: buildCustomerSafeIdentity(order),
    order: summarizeOrder(order),
    payment: summarizePayment(payment, actor.role),
    diagnosis: buildDiagnosis({
      supportCase,
      order,
      payment,
      reconciliationCase,
    }),
    timeline: timeline.map(toReadableTimelineEvent),
    notes,
    availableActions: getAvailableActions({
      actor,
      supportCase,
      order,
      payment,
    }),
  };
}

The response should be role-aware.

A support agent may see the transaction hash and payment status.

A developer may also see payload hashes, processing errors, and callback metadata.

A customer should see only a limited, public-safe status.

Classify cases automatically

The classification engine turns operational state into support work.

It should produce:

case type
priority
diagnosis
recommended action
customer message key
escalation owner

export function classifySupportCase({
  payment,
  order,
  fulfillment,
  webhookHealth,
  customerClaim,
}) {
  if (!payment) {
    return {
      type: "payment_not_found",
      priority: "high",
      diagnosis:
        "No payment session could be matched to the supplied order or customer evidence.",
      recommendedAction:
        "Request the transaction hash, currency, network, amount, and approximate payment time.",
      customerMessageKey: "payment_not_found",
      escalationOwner: "support",
    };
  }

  if (
    payment.internalStatus === "paid_confirmed" &&
    fulfillment.status !== "completed"
  ) {
    return {
      type: "paid_not_fulfilled",
      priority: "high",
      diagnosis:
        "The provider confirmed payment, but the merchant fulfillment process did not complete.",
      recommendedAction:
        "Inspect the fulfillment job and retry it only through an idempotent action.",
      customerMessageKey: "paid_not_fulfilled",
      escalationOwner: "operations",
    };
  }

  if (payment.internalStatus === "confirming") {
    return {
      type: "payment_detected_not_final",
      priority: "normal",
      diagnosis:
        "Payment activity has been detected, but the payment has not reached the final paid state.",
      recommendedAction:
        "Do not fulfill yet. Refresh the provider status or wait for the paid callback.",
      customerMessageKey: "payment_detected_not_final",
      escalationOwner: "support",
    };
  }

  if (payment.internalStatus === "underpaid_review") {
    return {
      type: "underpaid_payment",
      priority: "normal",
      diagnosis:
        "The amount received does not satisfy the requested payment amount.",
      recommendedAction:
        "Apply the merchant policy for completing, manually accepting, or rejecting an underpayment.",
      customerMessageKey: "underpaid_payment",
      escalationOwner: "operations",
    };
  }

  if (
    payment.internalStatus === "expired" &&
    customerClaim?.claimsPayment
  ) {
    return {
      type: "expired_with_payment_claim",
      priority: "high",
      diagnosis:
        "The invoice expired, but the customer reports that funds were sent.",
      recommendedAction:
        "Refresh Payment Information and search provider history before issuing a replacement invoice.",
      customerMessageKey: "expired_payment_review",
      escalationOwner: "support",
    };
  }

  if (
    payment.internalStatus === "paid_confirmed" &&
    order.paymentStatus !== "paid"
  ) {
    return {
      type: "provider_paid_local_pending",
      priority: "high",
      diagnosis:
        "The provider confirms payment, but the merchant order remains pending.",
      recommendedAction:
        "Verify the exact order mapping and escalate the local state mismatch.",
      customerMessageKey: "payment_confirmed_order_pending",
      escalationOwner: "operations",
    };
  }

  if (
    webhookHealth.lastProviderStatus === "paid" &&
    !webhookHealth.localPaidEventFound
  ) {
    return {
      type: "paid_webhook_missing",
      priority: "high",
      diagnosis:
        "The provider reports a paid payment, but no corresponding paid webhook exists locally.",
      recommendedAction:
        "Create a verified recovery event and investigate callback delivery health.",
      customerMessageKey: "payment_under_review",
      escalationOwner: "developer",
    };
  }

  return {
    type: "general_payment_review",
    priority: "normal",
    diagnosis:
      "The available evidence does not match a known automated support case.",
    recommendedAction:
      "Review the timeline and collect any missing customer evidence.",
    customerMessageKey: "payment_under_review",
    escalationOwner: "support",
  };
}

Do not guess that a customer used the wrong network unless the evidence supports that conclusion.

If the payment cannot be matched, the correct classification is usually:

unmatched customer claim

The agent can then request:

transaction hash
sent amount
currency
network
approximate payment time
sender address when appropriate

The system should separate confirmed evidence from customer-provided claims.

Use an evidence-based case taxonomy

Start with a small set of cases.

Case type	What it means	Default action
`paid_not_fulfilled`	Payment is confirmed, delivery failed	Retry or escalate fulfillment
`payment_detected_not_final`	Activity exists, payment is not final	Wait and refresh
`underpaid_payment`	Received amount is insufficient	Apply underpayment policy
`expired_with_payment_claim`	Invoice expired, customer says funds were sent	Verify provider records
`provider_paid_local_pending`	Provider and merchant order disagree	Repair or escalate local state
`paid_webhook_missing`	Provider shows paid, local event is missing	Recover and inspect webhook health
`payment_not_found`	No safe payment match exists	Request transaction evidence
`refunded_access_active`	Refund exists, service remains active	Apply refund and access policy

Every case should answer four questions:

What do we know?

What do we not know?

What is the safest next action?

Who owns that action?

That structure prevents support agents from making financial decisions based on incomplete evidence.

Treat OxaPay webhooks as evidence

OxaPay payment callbacks can include paying and paid status updates.

The merchant should wait for paid before treating the payment as ready for normal fulfillment.

OxaPay signs the raw callback body using HMAC SHA-512 with the Merchant API Key. The receiving endpoint should validate the HMAC header and return HTTP 200 with ok after successful processing.

Webhook delivery can be retried, so duplicate callbacks are normal.

The Support Desk should record:

whether the callback arrived
whether its HMAC was valid
whether the event was already stored
whether processing succeeded
which state transition it produced
whether a downstream action failed

An agent should see:

Webhook received and verified

A developer may see:

Payload hash: 4e5b...
Processing attempt: 2
Queue job: failed
Error: fulfillment adapter timeout

Do not expose raw JSON as the primary support interface.

Raw payloads are evidence for developers, not explanations for agents.

Add a provider refresh action

Support agents need a controlled way to retrieve the latest provider state.

OxaPay's Payment Information endpoint can retrieve a payment using its track_id.

export async function refreshOxaPayPayment({
  merchantApiKey,
  trackId,
}) {
  const response = await fetch(
    `https://api.oxapay.com/v1/payment/${encodeURIComponent(trackId)}`,
    {
      method: "GET",
      headers: {
        "Content-Type": "application/json",
        merchant_api_key: merchantApiKey,
      },
    },
  );

  const body = await response.json();

  if (!response.ok) {
    throw new Error(
      body?.error?.message ??
        `Payment lookup failed with status ${response.status}`,
    );
  }

  return body.data;
}

The result should be stored as a provider snapshot before updating the current local view.

await db.providerSnapshot.create({
  data: {
    merchantId,
    paymentSessionId,
    provider: "oxapay",
    providerTrackId: trackId,
    source: "support_agent_refresh",
    rawResponse: providerPayment,
    fetchedAt: new Date(),
  },
});

Do not delete previous snapshots.

They help explain what the system knew at each point in time.

Use Payment History for recovery

A customer ticket should not be the first signal that a payment was missed.

Run scheduled synchronization against OxaPay Payment History.

The job should:

retrieve recent provider payment records
upsert them by track_id
compare them with local payment sessions
identify missing webhook events
identify provider/local status mismatches
open or update support cases

Use overlapping query windows and idempotent upserts.

For example:

Run every 10 minutes
Query at least the previous 30 minutes
Upsert by provider + track_id
Compare provider and local state
Create only one open case per mismatch

The wider window protects against delayed records and temporary job failures.

Make support actions safe

A support action should be:

authorized
explicit
auditable
idempotent where possible
restricted by payment state
linked to a case

const ACTION_PERMISSIONS = {
  support_agent: [
    "refresh_payment",
    "add_note",
    "assign_case",
    "send_customer_message",
    "escalate_case",
  ],
  operations_manager: [
    "refresh_payment",
    "add_note",
    "assign_case",
    "send_customer_message",
    "escalate_case",
    "retry_fulfillment",
    "resolve_case",
  ],
  developer_admin: [
    "refresh_payment",
    "inspect_webhook",
    "retry_event_processing",
    "view_raw_payload",
  ],
  finance_admin: [
    "view_financial_evidence",
    "export_case",
    "approve_finance_resolution",
  ],
};

function assertActionAllowed(role, actionType) {
  const actions = ACTION_PERMISSIONS[role] ?? [];

  if (!actions.includes(actionType)) {
    throw new Error(`Role ${role} cannot perform ${actionType}`);
  }
}

Do not let an ordinary support agent:

mark an unverified payment as paid
change provider evidence
initiate a payout
issue a refund
manually accept an underpayment
edit the audit history
view unmasked API credentials

A payment tool is not safer because it has fewer buttons.

It is safer because every button has a defined policy.

Retry fulfillment idempotently

A common support action is retrying fulfillment after confirmed payment.

The action must not deliver twice.

export async function retryFulfillment({
  actor,
  supportCase,
  payment,
  order,
}) {
  assertActionAllowed(actor.role, "retry_fulfillment");

  if (payment.internalStatus !== "paid_confirmed") {
    throw new Error(
      "Fulfillment cannot be retried without confirmed payment",
    );
  }

  const idempotencyKey = [
    "support-retry",
    supportCase.id,
    order.id,
    order.fulfillmentVersion,
  ].join(":");

  return db.supportAction.upsert({
    where: { idempotencyKey },
    create: {
      caseId: supportCase.id,
      actorId: actor.id,
      actorRole: actor.role,
      actionType: "retry_fulfillment",
      idempotencyKey,
      status: "queued",
      requestData: {
        orderId: order.id,
      },
    },
    update: {},
  });
}

The action record should exist before the job is published.

This creates an audit trail even if the queue or downstream fulfillment provider fails.

Give agents customer-safe responses

Support agents should not explain blockchain confirmations, webhook delivery, and internal state machines from scratch.

Provide templates based on case type.

Payment detected but not final

We can see payment activity for your invoice, but the payment has not reached its final paid status yet. Your order will update automatically after the payment is confirmed.

Paid but not fulfilled

Your payment has been confirmed. The delivery step did not complete automatically, so our team is reviewing the order now. You do not need to send another payment.

Underpaid payment

The amount received for this invoice is lower than the requested amount. Our team is reviewing the payment according to the merchant's underpayment policy and will provide the next step.

Expired invoice with payment claim

This invoice expired before the payment process completed. We are checking the transaction details before asking you to create a new invoice.

Payment not found

We could not safely match the available information to a payment yet. Please send the transaction hash, currency, network, amount, and approximate payment time.

Templates should never claim that:

a payment is confirmed when it is not
a refund is guaranteed
access will be restored before a decision
funds are lost
the customer definitely used the wrong network

The response must reflect the evidence available to the agent.

Add a customer-facing status page

Some tickets can be prevented entirely.

Give customers a limited payment status page:

/orders/ORD-1842/payment-status

It can show:

invoice created
waiting for payment
payment activity detected
payment confirmed
order being processed
order delivered
invoice expired
support review required

Do not expose:

raw webhook payloads
API responses
internal notes
developer errors
other customer records
merchant credentials
security diagnostics

A safe status page can reduce repeated tickets such as:

Has my payment arrived yet?

It also creates a consistent source of truth between the customer and the support team.

Integrate with existing help desks

Do not try to replace Zendesk, Intercom, Freshdesk, Help Scout, or the merchant's existing ticketing system in the first version.

Add crypto payment intelligence to the tools agents already use.

A practical flow looks like this:

Customer opens support ticket
          |
          v
Agent enters order ID
          |
          v
Payment Support Desk finds the payment
          |
          v
Case type and evidence are returned
          |
          v
Private note is added to the ticket
          |
          v
Agent sends an approved response

The integration can add:

a link to the payment case
current payment status
order and fulfillment status
issue classification
recommended action
customer response template
escalation owner

This keeps the payment logic in your product while the conversation remains in the merchant's existing support system.

The MVP to build

The first version should solve a small number of cases extremely well.

Build:

search by order ID and track_id
payment and order summary
combined evidence timeline
Payment Information refresh
scheduled Payment History recovery
five core case classifications
support notes
role-based actions
customer-safe response templates
case assignment and escalation
daily unresolved-case report

Start with these cases:

paid_not_fulfilled
payment_detected_not_final
underpaid_payment
expired_with_payment_claim
provider_paid_local_pending

Do not start with:

refunds
payouts
revenue splits
AI-generated financial decisions
complex multi-agent routing
a complete replacement for existing ticketing platforms

Those features can be added after the core workflow proves its value.

Metrics that prove value

The product should measure operational improvement.

Useful metrics include:

average payment-ticket handling time
percentage of cases resolved without developer escalation
paid-but-not-fulfilled cases
provider/local state mismatches
webhook processing failures
unresolved cases by age
repeated issue categories
time from paid to fulfillment
support tickets per 100 payments
cases prevented by the customer status page

These metrics help the merchant see why the support layer matters.

They also show which part of the payment workflow needs improvement.

For example, a high number of paid_not_fulfilled cases is not mainly a support problem.

It may indicate a failing fulfillment adapter.

A high number of expired-payment claims may indicate unclear checkout instructions or an invoice lifetime that does not match customer behavior.

The Support Desk should reveal systemic problems, not only close individual tickets.

How this becomes a developer product

The strongest offer is not:

I built a dashboard for OxaPay payments.

A better offer is:

I give your support team one place to investigate crypto payment issues, understand what happened, take safe actions, and respond to customers without asking a developer to inspect every case.

The same core product can be adapted for:

digital product delivery
SaaS plan activation
hosting provisioning
license issuance
paid communities
course access
international service invoices

Each vertical has different fulfillment logic, but the support questions remain similar.

That makes the Support Desk reusable without making it generic.

Final takeaway

Crypto payment support is not solved by showing agents a transaction table.

Agents need context.

They need to see how the payment, order, webhook, fulfillment process, and customer claim relate to each other.

A useful Crypto Payment Support Desk provides:

searchable payment evidence
an understandable event timeline
automatic case classification
clear escalation ownership
restricted and auditable actions
customer-safe responses
provider refresh and recovery paths

OxaPay provides the payment primitives: invoices, track_id values, signed webhooks, Payment Information, Payment History, payment statuses, and static addresses.

The developer turns those primitives into a support workflow.

The goal is not to make support agents understand payment infrastructure.

The goal is to give them enough reliable evidence to answer one question:

What happened to this customer's payment, and what is the safest next action?

What payment case would you automate first: paid but not fulfilled, underpaid invoices, expired payment claims, or missing webhooks?

References

Build a Crypto Payment Module for SaaS Apps

kevin.s — Wed, 22 Jul 2026 09:47:01 +0000

A customer pays for a SaaS plan.

The payment provider reports paid, but the workspace still has Free-plan limits.

Another customer pays for a renewal. A duplicate webhook arrives and the subscription is extended twice.

A third customer creates two renewal invoices, pays both, and receives an access period the billing system was not designed to handle.

The payment integration works.

The billing model does not.

A SaaS product does not only need a crypto payment button. It needs a module that can translate verified payments into controlled subscription terms and product entitlements.

That module must know:

who owns the subscription
which plan was purchased
what the payment is for
when the access period begins and ends
whether the payment has been verified
whether the same payment was already applied
which features should be available
what happens when renewal does not occur
how support can investigate mismatches
how missed events are recovered

This article uses OxaPay as the payment infrastructure reference, but the billing architecture is provider-agnostic.

This article is part of 10 Crypto Payment Products Developers Can Build for Merchants.

The module owns billing state

A payment provider can tell your application:

A payment session was created.

Payment activity was detected.

The payment reached paid status.

The payment expired.

The payment was refunded.

Your SaaS module must decide what those events mean for the product.

For example:

Payment paid
-> Create one subscription term
-> Activate the purchased plan
-> Apply the correct entitlements
-> Record the reason for the access change

The payment provider should not become the source of truth for:

SaaS plans
workspace ownership
subscription terms
feature limits
grace periods
access policies
upgrade rules
internal credit balances

OxaPay provides payment infrastructure.

Your module provides billing logic.

This is not card-style recurring billing

A normal card subscription may allow the merchant to charge a saved payment method automatically at the start of each billing period.

An invoice-based crypto flow usually requires new customer action.

A practical renewal lifecycle is:

Subscription approaching expiry
-> Create or offer renewal invoice
-> Notify customer
-> Customer completes payment
-> Verify paid status
-> Grant the next subscription term

If the customer does not renew:

Active term ends
-> Grace period begins
-> Account becomes past due
-> Restricted or suspended state begins

Do not describe this as automatic recurring billing unless the product actually has an authorized mechanism for collecting future payments automatically.

A more accurate product promise is:

Invoice-based crypto billing with subscription activation, renewal reminders, grace periods, and access enforcement.

Separate the five core entities

A safe SaaS billing module should not compress everything into one subscription row.

Keep these concepts separate.

Plan

The commercial offer selected by the customer.

Pro Monthly
$29
One-month term
Five team members
100,000 API calls

Checkout session

One attempt to pay for a plan, renewal, upgrade, or credit package.

A subscription can have many checkout sessions.

Payment event

Immutable evidence received from the provider or recovered through an API query.

A payment event is not the same as the current payment state.

Subscription term

One access period granted because of one accepted payment or an authorized administrative action.

August 1 to September 1
Granted by checkout session cs_1842

Entitlement

The product access created by the active plan.

Examples:

projects.max = 50
team_members.max = 5
api_calls.monthly = 100000
feature.analytics = true

This separation prevents several common billing bugs.

Payment state is not subscription state

The provider and the SaaS application operate different state machines.

Payment session states

created
waiting
confirming
paid
underpaid
expired
refunded
review_required

Subscription states

pending
active
grace_period
suspended
canceled

Entitlement states

scheduled
active
expired
revoked

A payment may expire while the existing subscription remains active.

Renewal invoice: expired
Subscription: active until August 31
Entitlements: active

An expired renewal invoice should not immediately cancel access that was already paid for.

Another valid combination is:

Payment: paid
Subscription term: not granted
Entitlements: unchanged
Operational case: open

This means the payment succeeded, but internal billing activation failed.

That incident must remain visible.

Decide who owns the subscription

Do not assume every SaaS subscription belongs directly to a user.

Billing may belong to:

an individual user
a workspace
an organization
a team
a project
an API account

Create a billing account abstraction.

type BillingOwnerType =
  | "user"
  | "workspace"
  | "organization";

type BillingAccount = {
  id: string;
  ownerType: BillingOwnerType;
  ownerId: string;
};

The checkout session should reference the billing account, not only the currently authenticated user.

This prevents problems when:

several users belong to one paid workspace
the workspace owner changes
an administrator completes payment for another team
one user belongs to several organizations
invoices are created through an internal admin flow

The payment options provided by OxaPay

OxaPay exposes several primitives that fit different SaaS billing models.

Hosted invoice

Use Generate Invoice when the application can redirect the customer to an OxaPay payment page.

This is usually the best MVP option because it reduces checkout UI complexity.

White-label payment

Use Generate White Label when the SaaS application needs to render the payment details inside its own billing interface.

The application becomes responsible for displaying the amount, currency, network, payment address, QR code, expiration time, and current payment state clearly.

Static address

Use a Static Address for account funding or repeated deposits.

Examples:

API usage credits
AI generation credits
hosting balance
proxy bandwidth balance
internal prepaid wallet

Do not use one static address as a shortcut for ordinary subscription invoices unless the application has reliable rules for connecting deposits to billing decisions.

Payment Information

Use Payment Information to retrieve the latest provider state for a specific track_id.

This is useful before sensitive activation and during support investigation.

Payment History

Use Payment History for recovery, reporting, and provider-to-local reconciliation.

Webhooks are the real-time path.

Payment Information and Payment History are recovery paths.

Recommended architecture

+----------------------+
| SaaS Billing UI      |
+----------+-----------+
           |
           | Select plan
           v
+----------------------+
| Billing Module API   |
+----------+-----------+
           |
           | Create invoice
           v
+----------------------+
| OxaPay               |
+----------+-----------+
           |
           | Payment webhook
           v
+----------------------+
| Webhook Receiver     |
+----------+-----------+
           |
           | Verify and persist
           v
+----------------------+
| Payment Event Store  |
+----------+-----------+
           |
           v
+----------------------+
| Transactional Outbox |
+----------+-----------+
           |
           v
+----------------------+
| Billing Worker       |
+----------+-----------+
           |
           | Verify payment
           v
+----------------------+
| Subscription Service |
+----------+-----------+
           |
           v
+----------------------+
| Term + Entitlements  |
+----------+-----------+
           |
           v
User UI / Admin / Support / Reconciliation

The Webhook Receiver should not activate the subscription directly.

Its responsibilities are limited:

Identify the merchant integration.
Preserve the raw request body.
validate the HMAC signature.
Store the payment event.
Create an outbox job.
Return the expected success response.

Subscription activation belongs in a background worker.

A practical data model

CREATE TABLE billing_accounts (
  id UUID PRIMARY KEY,
  owner_type TEXT NOT NULL,
  owner_id TEXT NOT NULL,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (owner_type, owner_id)
);

CREATE TABLE saas_plans (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  price NUMERIC(20, 8) NOT NULL,
  currency TEXT NOT NULL,
  billing_months INTEGER NOT NULL,
  entitlements JSONB NOT NULL,
  active BOOLEAN NOT NULL DEFAULT TRUE,
  created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE TABLE subscriptions (
  id UUID PRIMARY KEY,
  billing_account_id UUID NOT NULL
    REFERENCES billing_accounts(id),
  current_plan_id TEXT REFERENCES saas_plans(id),
  status TEXT NOT NULL DEFAULT 'pending',
  current_term_start TIMESTAMP,
  current_term_end TIMESTAMP,
  grace_until TIMESTAMP,
  cancel_at_term_end BOOLEAN NOT NULL DEFAULT FALSE,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (billing_account_id)
);

CREATE TABLE checkout_sessions (
  id UUID PRIMARY KEY,
  billing_account_id UUID NOT NULL
    REFERENCES billing_accounts(id),
  subscription_id UUID REFERENCES subscriptions(id),
  plan_id TEXT NOT NULL REFERENCES saas_plans(id),
  purpose TEXT NOT NULL,
  provider TEXT NOT NULL DEFAULT 'oxapay',
  provider_order_id TEXT NOT NULL,
  provider_track_id TEXT,
  provider_status TEXT,
  internal_status TEXT NOT NULL DEFAULT 'created',
  amount NUMERIC(20, 8) NOT NULL,
  currency TEXT NOT NULL,
  payment_url TEXT,
  expires_at TIMESTAMP,
  paid_at TIMESTAMP,
  created_by TEXT,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (provider, provider_track_id),
  UNIQUE (provider_order_id)
);

CREATE TABLE payment_events (
  id UUID PRIMARY KEY,
  billing_account_id UUID NOT NULL
    REFERENCES billing_accounts(id),
  checkout_session_id UUID REFERENCES checkout_sessions(id),
  provider TEXT NOT NULL,
  payload_hash TEXT NOT NULL,
  provider_track_id TEXT,
  provider_status TEXT,
  raw_payload JSONB NOT NULL,
  signature_valid BOOLEAN NOT NULL,
  source TEXT NOT NULL,
  received_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (billing_account_id, payload_hash)
);

CREATE TABLE subscription_terms (
  id UUID PRIMARY KEY,
  subscription_id UUID NOT NULL
    REFERENCES subscriptions(id),
  checkout_session_id UUID REFERENCES checkout_sessions(id),
  plan_id TEXT NOT NULL REFERENCES saas_plans(id),
  starts_at TIMESTAMP NOT NULL,
  ends_at TIMESTAMP NOT NULL,
  grant_type TEXT NOT NULL,
  granted_by TEXT NOT NULL,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (checkout_session_id)
);

CREATE TABLE entitlement_grants (
  id UUID PRIMARY KEY,
  subscription_term_id UUID NOT NULL
    REFERENCES subscription_terms(id),
  entitlement_key TEXT NOT NULL,
  entitlement_value JSONB NOT NULL,
  starts_at TIMESTAMP NOT NULL,
  ends_at TIMESTAMP NOT NULL,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (subscription_term_id, entitlement_key)
);

CREATE TABLE outbox_jobs (
  id UUID PRIMARY KEY,
  topic TEXT NOT NULL,
  payload JSONB NOT NULL,
  status TEXT NOT NULL DEFAULT 'pending',
  attempts INTEGER NOT NULL DEFAULT 0,
  available_at TIMESTAMP NOT NULL DEFAULT NOW(),
  published_at TIMESTAMP,
  created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE TABLE billing_cases (
  id UUID PRIMARY KEY,
  billing_account_id UUID NOT NULL
    REFERENCES billing_accounts(id),
  checkout_session_id UUID REFERENCES checkout_sessions(id),
  subscription_id UUID REFERENCES subscriptions(id),
  case_type TEXT NOT NULL,
  severity TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'open',
  summary TEXT NOT NULL,
  recommended_action TEXT,
  resolution_note TEXT,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  resolved_at TIMESTAMP
);

The most important constraint is:

UNIQUE (checkout_session_id)

on subscription_terms.

One accepted checkout session can grant only one subscription term.

A duplicate webhook cannot extend the subscription twice.

Create the local checkout first

Create a local checkout session before calling the provider.

This gives the module an internal identifier even if the provider request times out or returns an error.

import crypto from "node:crypto";

const OXAPAY_API = "https://api.oxapay.com/v1";

export async function createPlanCheckout({
  billingAccountId,
  planId,
  purpose = "new_subscription",
  customerEmail,
}) {
  const plan = await db.saasPlan.findUnique({
    where: { id: planId },
  });

  if (!plan || !plan.active) {
    throw new Error("Plan is not available");
  }

  const checkoutId = crypto.randomUUID();
  const providerOrderId = `saas_${checkoutId}`;

  const checkout = await db.checkoutSession.create({
    data: {
      id: checkoutId,
      billingAccountId,
      planId: plan.id,
      purpose,
      provider: "oxapay",
      providerOrderId,
      internalStatus: "created",
      amount: plan.price,
      currency: plan.currency,
    },
  });

  try {
    const merchantApiKey = await loadMerchantApiKey();

    const response = await fetch(
      `${OXAPAY_API}/payment/invoice`,
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          merchant_api_key: merchantApiKey,
        },
        body: JSON.stringify({
          amount: plan.price,
          currency: plan.currency,
          order_id: providerOrderId,
          email: customerEmail,
          description: `${plan.name} SaaS plan`,
          callback_url:
            `${process.env.APP_URL}/webhooks/oxapay/payment`,
          return_url:
            `${process.env.APP_URL}/billing/checkouts/${checkoutId}`,
          lifetime: 60,
          sandbox: process.env.NODE_ENV !== "production",
        }),
      },
    );

    const payload = await response.json();

    if (!response.ok) {
      throw new Error(
        payload?.error?.message ??
          `Invoice request failed with ${response.status}`,
      );
    }

    const payment = payload.data;

    return db.checkoutSession.update({
      where: { id: checkout.id },
      data: {
        providerTrackId: String(payment.track_id),
        providerStatus: "new",
        internalStatus: "invoice_created",
        paymentUrl: payment.payment_url,
        expiresAt: payment.expired_at
          ? new Date(Number(payment.expired_at) * 1000)
          : null,
      },
    });
  } catch (error) {
    await db.checkoutSession.update({
      where: { id: checkout.id },
      data: {
        internalStatus: "creation_failed",
      },
    });

    throw error;
  }
}

Do not allow the frontend to submit its own price.

The backend should load the authoritative plan price from the plan catalog.

Validate OxaPay callbacks

OxaPay sends the payment signature in the HMAC header. The value is calculated using SHA-512 over the raw request body.

import crypto from "node:crypto";
import express from "express";

const app = express();

app.post(
  "/webhooks/oxapay/payment",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const rawBody = req.body;
    const receivedHmac = req.get("HMAC");
    const merchantApiKey = await loadMerchantApiKey();

    const expectedHmac = crypto
      .createHmac("sha512", merchantApiKey)
      .update(rawBody)
      .digest("hex");

    if (!safeEqualSha512(receivedHmac, expectedHmac)) {
      await recordRejectedWebhook({
        reason: "invalid_hmac",
      });

      return res.status(401).send("invalid signature");
    }

    let payload;

    try {
      payload = JSON.parse(rawBody.toString("utf8"));
    } catch {
      return res.status(400).send("invalid json");
    }

    const payloadHash = crypto
      .createHash("sha256")
      .update(rawBody)
      .digest("hex");

    try {
      await persistEventAndOutbox({
        payload,
        payloadHash,
      });

      return res.status(200).send("ok");
    } catch (error) {
      console.error("Webhook persistence failed", error);
      return res.status(500).send("failed");
    }
  },
);

function safeEqualSha512(received, expected) {
  const sha512Hex = /^[a-f0-9]{128}$/i;

  if (
    !received ||
    !expected ||
    !sha512Hex.test(received) ||
    !sha512Hex.test(expected)
  ) {
    return false;
  }

  return crypto.timingSafeEqual(
    Buffer.from(received, "hex"),
    Buffer.from(expected, "hex"),
  );
}

The payment event and outbox job should be inserted in one database transaction.

async function persistEventAndOutbox({
  payload,
  payloadHash,
}) {
  const trackId = String(payload.track_id ?? "");

  if (!trackId) {
    throw new Error("Webhook is missing track_id");
  }

  const checkout = await db.checkoutSession.findUnique({
    where: {
      provider_providerTrackId: {
        provider: "oxapay",
        providerTrackId: trackId,
      },
    },
  });

  if (!checkout) {
    await createBillingCase({
      caseType: "unknown_provider_payment",
      severity: "high",
      summary: `No checkout session matches track_id ${trackId}`,
      evidence: payload,
    });

    return;
  }

  await db.$transaction(async (tx) => {
    const event = await tx.paymentEvent.upsert({
      where: {
        billingAccountId_payloadHash: {
          billingAccountId: checkout.billingAccountId,
          payloadHash,
        },
      },
      create: {
        billingAccountId: checkout.billingAccountId,
        checkoutSessionId: checkout.id,
        provider: "oxapay",
        payloadHash,
        providerTrackId: trackId,
        providerStatus: normalizeStatus(payload.status),
        rawPayload: payload,
        signatureValid: true,
        source: "webhook",
      },
      update: {},
    });

    await tx.outboxJob.create({
      data: {
        topic: "billing.payment_event_received",
        payload: {
          paymentEventId: event.id,
        },
      },
    });
  });
}

function normalizeStatus(status) {
  return String(status ?? "").trim().toLowerCase();
}

The outbox dispatcher can publish the event to a billing queue.

The Webhook Receiver remains fast and does not perform subscription activation.

Map provider status into payment state

OxaPay payment statuses may include states such as:

new
waiting
paying
paid
manual_accept
underpaid
expired
refunding
refunded

Map them into your own model.

const STATUS_MAP = {
  new: "created",
  waiting: "waiting",
  paying: "confirming",
  paid: "paid",
  manual_accept: "manually_accepted",
  underpaid: "underpaid",
  expired: "expired",
  refunding: "refund_in_progress",
  refunded: "refunded",
};

function mapPaymentStatus(providerStatus) {
  return STATUS_MAP[providerStatus] ?? "unknown";
}

Do not activate a subscription on paying.

The user-facing UI may show:

Payment detected. Waiting for completion.

The term should normally be granted after paid.

A manually accepted payment should follow a separate merchant policy and preserve an audit record.

Verify the payment before granting access

A valid webhook proves that the callback came from the payment provider.

Before granting a subscription term, retrieve the latest Payment Information and verify the business facts.

async function fetchOxaPayPayment(trackId) {
  const merchantApiKey = await loadMerchantApiKey();

  const response = await fetch(
    `${OXAPAY_API}/payment/${encodeURIComponent(trackId)}`,
    {
      method: "GET",
      headers: {
        "Content-Type": "application/json",
        merchant_api_key: merchantApiKey,
      },
    },
  );

  const payload = await response.json();

  if (!response.ok) {
    throw new Error(
      payload?.error?.message ??
        `Payment lookup failed with ${response.status}`,
    );
  }

  return payload.data;
}

function verifyPaymentForCheckout({
  payment,
  checkout,
}) {
  if (
    normalizeStatus(payment.status) !== "paid"
  ) {
    throw new PermanentBillingError(
      "Payment is not in the paid state",
    );
  }

  if (
    String(payment.order_id) !==
    String(checkout.providerOrderId)
  ) {
    throw new PermanentBillingError(
      "Payment order_id does not match checkout",
    );
  }

  if (
    decimal(payment.amount).lessThan(
      decimal(checkout.amount),
    )
  ) {
    throw new PermanentBillingError(
      "Paid amount does not satisfy checkout",
    );
  }
}

Use decimal arithmetic for financial comparisons.

Amount handling may also require a merchant-defined currency policy.

Grant one subscription term per payment

The subscription term is the durable business result of the payment.

import { addMonths } from "date-fns";

export async function applyPaidCheckout(
  checkoutId,
) {
  return db.$transaction(async (tx) => {
    const checkout =
      await tx.checkoutSession.findUnique({
        where: { id: checkoutId },
      });

    if (!checkout) {
      throw new PermanentBillingError(
        "Checkout session not found",
      );
    }

    const existingTerm =
      await tx.subscriptionTerm.findUnique({
        where: {
          checkoutSessionId: checkout.id,
        },
      });

    if (existingTerm) {
      return existingTerm;
    }

    const plan = await tx.saasPlan.findUnique({
      where: { id: checkout.planId },
    });

    if (!plan || !plan.active) {
      throw new PermanentBillingError(
        "Purchased plan is unavailable",
      );
    }

    let subscription =
      await tx.subscription.findUnique({
        where: {
          billingAccountId:
            checkout.billingAccountId,
        },
      });

    const now = new Date();

    if (!subscription) {
      subscription = await tx.subscription.create({
        data: {
          billingAccountId:
            checkout.billingAccountId,
          currentPlanId: plan.id,
          status: "pending",
        },
      });
    }

    const startsAt =
      subscription.currentTermEnd &&
      subscription.currentTermEnd > now
        ? subscription.currentTermEnd
        : now;

    const endsAt = addMonths(
      startsAt,
      plan.billingMonths,
    );

    const term =
      await tx.subscriptionTerm.create({
        data: {
          subscriptionId: subscription.id,
          checkoutSessionId: checkout.id,
          planId: plan.id,
          startsAt,
          endsAt,
          grantType: checkout.purpose,
          grantedBy: "verified_payment",
        },
      });

    for (const [key, value] of Object.entries(
      plan.entitlements,
    )) {
      await tx.entitlementGrant.create({
        data: {
          subscriptionTermId: term.id,
          entitlementKey: key,
          entitlementValue: value,
          startsAt,
          endsAt,
        },
      });
    }

    await tx.subscription.update({
      where: { id: subscription.id },
      data: {
        currentPlanId: plan.id,
        status: "active",
        currentTermStart: startsAt,
        currentTermEnd: endsAt,
        graceUntil: null,
      },
    });

    await tx.checkoutSession.update({
      where: { id: checkout.id },
      data: {
        providerStatus: "paid",
        internalStatus: "applied",
        paidAt: now,
      },
    });

    return term;
  });
}

The unique constraint on checkout_session_id makes this operation idempotent.

If the same paid transition is processed again, the existing term is returned.

Do not hide plan-change policy

Renewal is straightforward when the customer buys the same plan for another term.

Upgrades and downgrades need explicit rules.

Questions include:

Does an upgrade begin immediately?
Is unused time converted into credit?
Does the new term start after the current term?
Are remaining quotas reset?
Does a downgrade begin immediately or at term end?
Can a workspace have overlapping entitlement grants?

Do not bury these decisions inside a generic activation function.

A safe first version can support:

New subscription
Renewal of the same plan

Then add plan changes as explicit operations.

Scheduled downgrade

Current plan remains active
-> Downgrade stored as pending
-> Lower plan begins at current term end

Immediate upgrade

Upgrade invoice paid
-> Existing term closed or adjusted
-> Upgrade policy applied
-> New entitlement set activated
-> Adjustment recorded in audit history

There is no universally correct upgrade model.

The module should make the policy configurable and visible.

Renewal should create another checkout

A renewal job should not extend access on its own.

It should identify subscriptions approaching expiration and create or offer a renewal payment session.

export async function prepareRenewals() {
  const reminderBoundary = addDays(
    new Date(),
    5,
  );

  const subscriptions =
    await db.subscription.findMany({
      where: {
        status: "active",
        cancelAtTermEnd: false,
        currentTermEnd: {
          lte: reminderBoundary,
        },
      },
    });

  for (const subscription of subscriptions) {
    const existingCheckout =
      await db.checkoutSession.findFirst({
        where: {
          subscriptionId: subscription.id,
          purpose: "renewal",
          internalStatus: {
            in: [
              "created",
              "invoice_created",
              "waiting",
              "confirming",
            ],
          },
        },
      });

    if (existingCheckout) {
      continue;
    }

    await createRenewalCheckout(subscription);
  }
}

The renewal lifecycle can be:

Five days before expiry:
Create or offer renewal checkout

Three days before expiry:
Send reminder

At term end:
Enter grace period

At grace end:
Suspend protected features

Do not create a new invoice every time the scheduled job runs.

Use one open renewal checkout per subscription and renewal window.

Model grace periods explicitly

A grace period is not an extension granted by payment.

It is a merchant policy.

export async function updateExpiredTerms() {
  const now = new Date();

  const endedSubscriptions =
    await db.subscription.findMany({
      where: {
        status: "active",
        currentTermEnd: {
          lte: now,
        },
      },
    });

  for (const subscription of endedSubscriptions) {
    const graceUntil = addDays(now, 3);

    await db.subscription.update({
      where: { id: subscription.id },
      data: {
        status: "grace_period",
        graceUntil,
      },
    });
  }

  const expiredGracePeriods =
    await db.subscription.findMany({
      where: {
        status: "grace_period",
        graceUntil: {
          lte: now,
        },
      },
    });

  for (const subscription of expiredGracePeriods) {
    await db.subscription.update({
      where: { id: subscription.id },
      data: {
        status: "suspended",
      },
    });
  }
}

Decide which features remain available during grace.

For example:

Read existing data: allowed
Create new projects: blocked
Use paid API quota: limited
Export data: allowed
Invite team members: blocked

A complete account lock may not be the best product experience.

Enforce entitlements inside the product

Payment integration is incomplete until the application actually enforces the purchased plan.

export function requireEntitlement(
  entitlementKey,
) {
  return async function entitlementMiddleware(
    req,
    res,
    next,
  ) {
    const billingAccountId =
      req.billingAccount.id;

    const subscription =
      await billing.getSubscription(
        billingAccountId,
      );

    if (
      !subscription ||
      !["active", "grace_period"].includes(
        subscription.status,
      )
    ) {
      return res.status(402).json({
        error: "active_subscription_required",
      });
    }

    const entitlement =
      await billing.getActiveEntitlement({
        subscriptionId: subscription.id,
        key: entitlementKey,
        at: new Date(),
      });

    if (!entitlement) {
      return res.status(403).json({
        error: "entitlement_not_available",
      });
    }

    req.entitlement = entitlement;
    return next();
  };
}

For numeric limits, the application can compare usage against the active entitlement.

team_members.max = 5
api_calls.monthly = 100000
projects.max = 50

The module should expose billing decisions through a clean interface.

The rest of the SaaS application should not query raw payment tables.

Keep credits separate from subscriptions

Some SaaS products sell both time-based access and usage credits.

For example:

Pro Monthly subscription
+
10,000 additional AI credits

These need separate models.

Subscription

Controls time-based access and feature availability.

Credit ledger

Controls consumable units.

A credit system should use an append-only ledger:

+10,000  Purchased credit package
-25      Image generation
-100     Video generation
+500     Manual adjustment

Do not store only:

credit_balance = 10375

without recording how the balance changed.

Static addresses can support repeated account deposits, but every incoming transaction still needs:

account ownership mapping
unique transaction handling
currency conversion policy
credit calculation
ledger entry
audit evidence
reversal policy

Start with invoice-based credit packages unless repeated deposits are a proven requirement.

Recover missed events

A production module should not assume every webhook is delivered and processed correctly.

Use Payment History periodically.

A recovery job can detect:

provider payment is paid, local checkout is not applied
provider payment expired, local checkout remains waiting
provider payment exists without a local session
checkout is paid, but no subscription term exists
subscription term exists, but entitlements are missing
several open renewal sessions exist for one subscription

A practical schedule:

Every 10 minutes:
- retrieve an overlapping recent payment window
- upsert provider records by track_id
- compare provider and local states
- create recovery events
- create cases for unsafe mismatches

Every night:
- compare paid checkouts with subscription terms
- compare active terms with entitlement grants
- report unresolved billing cases

Recovered events should be labeled:

source = payment_history_backfill

Do not present them as original webhook deliveries.

Create operational cases

Do not silently repair every inconsistency.

Useful case types include:

Case	Meaning
`paid_not_applied`	Provider confirms payment, but no term was granted
`unknown_payment`	Provider payment has no matching checkout
`amount_mismatch`	Payment does not satisfy the checkout
`duplicate_renewal_payment`	More than one accepted renewal exists for the same intended period
`term_without_entitlements`	Subscription term exists, but access grants are incomplete
`refunded_but_active`	Payment was refunded while paid access remains active
`expired_with_customer_claim`	Checkout expired, but the customer reports sending funds
`invalid_webhook`	Callback failed HMAC validation

Every case should contain:

billing account
checkout session
provider track_id
plan
expected amount
provider state
local state
evidence
recommended action
assigned owner
resolution note

This is where the module connects to payment reconciliation and the Crypto Payment Support Desk.

Build user-facing billing states

The billing UI should explain what the customer needs to do.

No active subscription

Choose a plan to continue.

Waiting for payment

Your payment session is ready. Complete the payment before it expires.

Payment detected

We detected payment activity. Do not send another payment while it is being processed.

Payment confirmed, activation pending

Your payment is confirmed. We are activating your plan.

Active

Your Pro plan is active until September 1.

Grace period

Your paid term has ended. Renew before September 4 to avoid service suspension.

Suspended

Your subscription is suspended. Complete a renewal payment to restore paid access.

The customer should not need to interpret provider-specific statuses.

Build an admin billing workspace

A real SaaS operator needs more than a payment log.

Useful admin views include:

Billing account

owner type and ID
current plan
subscription status
current term
grace deadline
active entitlements
scheduled plan change

Checkout sessions

purpose
plan
expected amount
provider track_id
payment status
expiration
applied term
payment source

Subscription timeline

August 1  Checkout created
August 1  Payment confirmed
August 1  Pro Monthly term granted
August 1  Entitlements activated
August 26 Renewal invoice created
September 1 Grace period started
September 2 Renewal payment confirmed
September 2 Next term granted

Needs attention

paid but not activated
unknown payments
amount mismatches
expired payment claims
invalid callbacks
refunded payments with active access
entitlement projection failures

Safe actions

refresh Payment Information
send renewal reminder
create replacement checkout
retry billing activation
assign case
add internal note
apply authorized manual grant
suspend or restore access under policy

Every manual grant or override needs an audit record.

Define the module API

A SaaS developer should not need to understand every OxaPay endpoint.

Expose a billing-oriented interface.

type CreateCheckoutInput = {
  billingAccountId: string;
  planId: string;
  purpose:
    | "new_subscription"
    | "renewal"
    | "upgrade";
  customerEmail?: string;
};

type BillingModule = {
  createCheckout(
    input: CreateCheckoutInput
  ): Promise<{
    checkoutId: string;
    paymentUrl: string;
    providerTrackId: string;
    expiresAt: Date | null;
  }>;

  getSubscription(
    billingAccountId: string
  ): Promise<{
    status: string;
    planId: string | null;
    currentTermEnd: Date | null;
    graceUntil: Date | null;
  }>;

  getEntitlement(input: {
    billingAccountId: string;
    key: string;
  }): Promise<unknown | null>;

  createRenewal(
    billingAccountId: string
  ): Promise<{
    checkoutId: string;
    paymentUrl: string;
  }>;

  refreshPayment(
    checkoutId: string
  ): Promise<void>;
};

OxaPay remains behind this interface.

The SaaS application works with:

Checkout
Subscription
Term
Entitlement
Renewal

That is the product developers buy.

Package it for one framework first

Do not launch Laravel, Node.js, Django, and Next.js versions simultaneously.

Choose one ecosystem.

Laravel package

A useful package can provide:

migrations
OxaPay configuration
billing-account contract
webhook route
queue jobs
subscription and term models
entitlement middleware
Artisan renewal commands
admin components

Possible developer interface:

$checkout = $workspace
    ->cryptoBilling()
    ->checkout('pro_monthly');

$workspace
    ->cryptoBilling()
    ->hasEntitlement('analytics');

Node.js module

A Node.js package can provide:

OxaPay client
webhook verifier
event normalizer
database adapter contract
billing service
renewal scheduler
Express or Fastify middleware
React billing components

Django app

A Django package can provide:

models and migrations
webhook view
Celery jobs
Django Admin integration
subscription services
entitlement decorators

Next.js starter

A Next.js product can include:

Prisma models
checkout API route
Webhook Route Handler
billing portal
admin payment page
cron endpoint
entitlement helpers
deployment guide

Framework specificity makes the product easier to install, document, and sell.

The MVP

The first version should solve one complete use case:

A workspace buys one monthly SaaS plan with crypto and receives the correct access exactly once.

Build:

billing account model
plan catalog
subscription table
checkout sessions
hosted OxaPay invoices
HMAC-validated webhooks
event and outbox storage
Payment Information verification
idempotent subscription-term grants
entitlement checks
renewal reminder
grace and suspension states
user billing page
admin payment timeline
paid-but-not-activated case detection
Payment History recovery

Do not include in the first version:

prorated upgrades
tax calculation
coupons
affiliate payouts
automatic payouts
several payment providers
advanced usage metering
full accounting
visual billing workflow builders

A smaller reliable module is more valuable than a broad billing system with unclear state transitions.

Production safeguards

Before selling the module, implement:

HMAC validation over the raw callback body
timing-safe signature comparison
encrypted Merchant API Key storage
strict tenant isolation
unique payment and term constraints
asynchronous event processing
transactional outbox delivery
decimal financial arithmetic
explicit payment and subscription states
retry classification
Payment Information verification
Payment History recovery
manual-action audit logs
role-based admin permissions
raw payload retention rules
secret masking in logs
alerting for paid-but-not-activated cases

Test at least:

Valid paid payment creates one term

Duplicate paid webhook does not create another term

Different duplicate payloads do not grant access twice

Confirming payment does not activate access

Expired renewal does not cancel the current active term

Late renewal restores access under policy

Unknown track_id creates a case

Paid payment with wrong order_id is rejected

Provider paid, local pending is recovered

Active term has the expected entitlements

Refund creates an operational review

These tests are part of the product, not optional engineering polish.

How to position the module

Weak positioning:

Add OxaPay payments to your SaaS.

Better positioning:

Add invoice-based crypto billing to your SaaS.

Stronger positioning:

A crypto billing module that connects verified OxaPay payments to subscription terms, workspace entitlements, renewals, grace periods, and support-ready billing records.

A framework-specific offer can be even clearer:

Crypto billing for Laravel SaaS applications, including hosted invoices, verified webhooks, subscription terms, entitlement middleware, renewal reminders, and admin payment visibility.

The buyer is not purchasing an API wrapper.

They are purchasing the billing behavior that sits behind the API.

What makes this a real product?

A normal checkout integration says:

Create invoice
-> Receive paid webhook
-> Set user.plan = pro

A production SaaS payment module says:

Create authoritative local checkout
-> Generate payment session
-> Validate callback
-> Preserve payment evidence
-> Verify provider state
-> Match billing account and plan
-> Grant one immutable subscription term
-> Activate term-scoped entitlements
-> Prevent duplicate activation
-> Prepare invoice-based renewal
-> Apply grace and suspension policy
-> Recover missed events
-> Surface unsafe mismatches

That is the difference between payment integration and billing infrastructure.

Final takeaway

A Crypto Payment Module for SaaS Apps is not a payment button and not a thin API wrapper.

It is a billing-state system.

OxaPay provides the payment primitives:

hosted invoices
white-label payment details
static addresses
unique track_id references
HMAC-signed webhooks
Payment Information
Payment History
PHP, Python, and Laravel SDKs

The module provides the SaaS logic:

billing ownership
plan definitions
checkout purpose
subscription terms
entitlements
renewal invoices
grace periods
access enforcement
support visibility
reconciliation
recovery

Start with one framework.

Support one plan-purchase flow.

Make every payment grant access exactly once.

Make every access change explainable.

Make every failure visible.

That is how a crypto payment integration becomes reusable SaaS billing infrastructure.

Would you build the first version for Laravel, Node.js, Django, or Next.js?

References

Build a Merchant Crypto Launch Kit for Agencies

kevin.s — Mon, 20 Jul 2026 07:05:34 +0000

An agency launches crypto payments for three merchant clients.

The first client uses WooCommerce and only needs a standard checkout plugin.

The second runs a custom SaaS product and needs payment-triggered account activation.

The third wants a branded payment interface, customer status page, support timeline, and finance export.

The agency treats all three projects as the same integration.

It installs some code, confirms that an invoice can be created, and marks the work complete.

Then production problems begin.

One merchant cannot explain a paying payment to a customer.

Another receives duplicate callbacks and fulfills the same order twice.

A third has no idea who owns the API credentials or who should investigate a missed payment.

The payment integration technically exists.

The delivery system does not.

A Merchant Crypto Launch Kit gives agencies a repeatable way to scope, build, verify, document, hand off, and support crypto payment projects for merchant clients.

It is not only reusable code.

It is an agency operating system for crypto payment delivery.

This article uses OxaPay as the payment infrastructure reference, but the agency model is provider-agnostic.

This article is part of 10 Crypto Payment Products Developers Can Build for Merchants.

What the agency is selling

A weak agency offer is:

We can integrate a crypto payment gateway into your website.

That sounds like a one-time technical task.

A stronger offer is:

We launch a complete crypto payment workflow for your business, including checkout, verified payment updates, order activation, support procedures, recovery, testing, and team handoff.

The merchant is not only buying an API connection.

The merchant is buying a controlled launch.

The agency is buying repeatability.

The developer building the Launch Kit creates the reusable system behind both.

What a Launch Kit actually contains

A Merchant Crypto Launch Kit should include four categories of assets.

Delivery assets

These are used to implement the payment workflow:

plugin deployment guides
hosted invoice module
white-label checkout module
static address module
webhook receiver
payment state mapping
fulfillment adapters
Payment Information lookup
Payment History recovery
dashboard starter

Decision assets

These help the agency choose the correct architecture:

discovery questionnaire
integration decision tree
scope calculator
risk classification
supported-platform matrix
responsibility matrix

Verification assets

These prove that the implementation works:

acceptance-test plan
test data
duplicate-event tests
payment-state tests
fulfillment tests
recovery tests
security checklist
signed launch report

Handoff assets

These allow the merchant to operate the integration:

payment-flow overview
support procedures
escalation contacts
credential ownership record
customer-response templates
dashboard instructions
incident checklist
post-launch monitoring agreement

A GitHub repository may contain part of the kit.

It is not the complete product.

Where this product fits

A Crypto PaymentOps Service provides the operational foundation for an individual merchant.

The Launch Kit packages repeatable parts of that foundation so an agency can deploy them across several clients.

The difference is ownership and distribution.

PaymentOps product
-> Operates one merchant payment environment

Agency Launch Kit
-> Standardizes how several merchant environments are delivered

The Launch Kit must answer questions that a normal integration article does not:

Which implementation path fits this client?

What is included in scope?

Who owns each system?

What evidence proves launch readiness?

What does the merchant operate after handoff?

What remains the agency's responsibility?

How are future changes deployed safely?

The launch lifecycle

The kit should standardize seven stages.

Qualification
-> Discovery
-> Architecture
-> Implementation
-> Verification
-> Handoff
-> Post-launch operations

Each stage produces a specific output.

Stage	Required output
Qualification	Client fit decision
Discovery	Approved requirements
Architecture	Selected integration track
Implementation	Configured payment workflow
Verification	Acceptance-test evidence
Handoff	Merchant operations package
Post-launch	Monitoring and ownership plan

A project should not move to the next stage because someone says it “looks ready.”

It should move because the required output exists.

Qualify the merchant first

Not every merchant request should become a custom crypto payment project.

The agency should first determine whether the client:

already sells online
has a defined order or billing system
has a real customer demand for crypto
knows what should happen after payment
has someone responsible for payment support
can provide an HTTPS callback endpoint or use a managed service
can define refund and late-payment policies
can identify who owns production credentials
can participate in acceptance testing

A client that says:

Just add a wallet address to the checkout.

may not yet understand the operational requirements.

The agency should not turn an unclear request into an unclear implementation.

The discovery questionnaire

The Launch Kit should include a structured discovery form.

Business model

What does the merchant sell?

Is the purchase one-time, renewable, prepaid, or account-based?

Does successful payment trigger immediate fulfillment?

Can fulfillment be reversed?

Does the merchant sell digital or physical products?

Does the merchant have international customers?

Current platform

Which ecommerce, billing, CMS, or application platform is used?

Is there an existing OxaPay plugin for that platform?

Is the application custom-built?

Which backend language and database are used?

Who controls deployment?

Checkout requirements

Can the customer leave the merchant website?

Is a branded payment interface required?

Does the merchant need asset or network selection?

Is a reusable deposit address required?

Does the checkout need localization?

Operational requirements

Who investigates payment incidents?

Who receives payment alerts?

Does the merchant need a customer status page?

Does finance require CSV or accounting exports?

How should underpayments and late payments be handled?

What happens when payment succeeds but fulfillment fails?

Security and ownership

Who owns the OxaPay account?

Who generates the Merchant API Key?

Where will credentials be stored?

Which agency staff can access production?

Who rotates credentials after handoff?

Who approves manual payment decisions?

The completed discovery document becomes part of the project record.

Do not rely on meeting memory.

Choose one implementation track

The Launch Kit should provide clear delivery tracks.

Track one: Plugin deployment

Use a supported plugin when:

the merchant uses a compatible platform
standard checkout behavior is sufficient
no custom fulfillment layer is required
the merchant prefers lower implementation complexity
the plugin supports the required order states

Possible platform categories include ecommerce, hosting billing, memberships, digital downloads, forms, and other supported systems.

The agency still needs to provide:

plugin compatibility review
installation
API credential configuration
status mapping verification
test payment
customer checkout review
support procedure
handoff documentation
launch monitoring

Installing the plugin is not the whole service.

Track two: Hosted invoice

Use OxaPay Generate Invoice when:

fast implementation matters
the customer can use a hosted payment page
the important workflow happens after payment
the merchant does not need full checkout UI ownership

The flow is:

Merchant order
-> Local payment session
-> OxaPay hosted invoice
-> Customer payment
-> Signed callback
-> Merchant order update
-> Fulfillment

This is usually the best custom-development starting point.

Track three: White-label checkout

Use a white-label payment when:

payment must remain inside the client interface
the client requires branded checkout
network-specific instructions are important
the merchant needs a custom payment status experience
checkout design is part of the commercial value

The agency becomes responsible for displaying:

payment asset
network
amount
payment address
QR code
expiration
payment state
late-payment warnings
customer instructions

White-label checkout is not only a different API endpoint.

It is a larger UX and support scope.

Track four: Static address account funding

Use static addresses for account-based deposits such as:

prepaid hosting balance
customer wallet balance
reseller credit
usage credits
repeated account funding

Do not use static addresses merely because the merchant wants customers to “pay anytime.”

The implementation also needs:

customer-to-address ownership
deposit deduplication
internal balance ledger
callback processing
address lifecycle management
reconciliation
support search
crediting policy

Static address projects should usually be scoped separately from ordinary checkout.

The decision matrix

Requirement	Recommended track
Supported platform and standard checkout	Plugin
Fast custom payment launch	Hosted invoice
Branded embedded payment UX	White-label
Reusable customer funding address	Static address
Payment-triggered business workflows	Invoice or white-label plus webhook
Historical recovery and reports	Payment Information and Payment History
Contractor or partner payouts	Separate payout module

The decision should be recorded in the client architecture document.

It should not remain an undocumented developer preference.

Define the project boundary

Agency projects often fail because the word “integration” hides several responsibilities.

A Launch Kit should convert the project into explicit deliverables.

Example scope:

Included:
- OxaPay hosted invoice creation
- payment-to-order mapping
- HMAC-validated webhook endpoint
- paid-order activation
- customer payment status page
- support search by order ID and track_id
- Payment History recovery
- launch testing
- merchant handoff

Not included:
- refunds
- accounting
- tax calculation
- automatic payouts
- custom treasury management
- legal review
- 24/7 operational support

The client should approve this boundary before implementation.

Use an implementation manifest

Every client deployment should have a machine-readable manifest.

client:
  id: merchant_acme
  name: Acme Software
  platform: custom_node
  environment: production

integration:
  provider: oxapay
  mode: hosted_invoice
  payment_owner: merchant
  credential_owner: merchant
  deployment_owner: agency

payment:
  pricing_currency: USD
  allowed_assets:
    - USDT
    - LTC
  callback_endpoint_id: cb_acme_7f21
  fulfill_on:
    - paid

order:
  external_id_field: order_id
  fulfillment_adapter: license_delivery

operations:
  payment_information_refresh: true
  payment_history_backfill_minutes: 10
  customer_status_page: true
  support_search: true

handoff:
  merchant_admin: ops@acme.example
  agency_support: support@agency.example
  monitoring_days: 14

This manifest can be used to:

generate configuration
validate required fields
produce handoff documents
build test cases
track differences between clients
audit configuration changes

Do not hide critical client configuration in developer notes or chat history.

Organize the Launch Kit repository

A useful repository structure could look like:

merchant-crypto-launch-kit/
├── discovery/
│   ├── questionnaire.md
│   ├── qualification-scorecard.md
│   └── scope-template.md
├── architecture/
│   ├── decision-tree.md
│   ├── responsibility-matrix.md
│   └── threat-model.md
├── runtime/
│   ├── invoice/
│   ├── white-label/
│   ├── static-address/
│   ├── webhook/
│   ├── recovery/
│   └── fulfillment/
├── adapters/
│   ├── woocommerce/
│   ├── whmcs/
│   ├── node/
│   └── laravel/
├── qa/
│   ├── acceptance-tests.md
│   ├── security-tests.md
│   └── launch-report-template.md
├── handoff/
│   ├── merchant-guide.md
│   ├── support-sop.md
│   ├── incident-template.md
│   └── credential-register.md
└── examples/
    ├── plugin-client/
    ├── hosted-invoice-client/
    └── white-label-client/

This communicates that the product includes more than runtime code.

Keep merchant environments isolated

An agency may manage several clients.

Do not reuse one Merchant API Key across unrelated merchants.

Each merchant deployment should have:

its own OxaPay merchant configuration
its own public webhook endpoint identifier
separate encrypted credentials
tenant-isolated records
separate dashboards or filtered access
independent test and production environments
documented credential owner

A shared agency platform may route callbacks through:

/webhooks/oxapay/{endpoint_id}

The endpoint ID identifies the merchant configuration before the request body is trusted.

It must not contain the actual API key or provide administrative access.

A practical data model

CREATE TABLE agencies (
  id UUID PRIMARY KEY,
  name TEXT NOT NULL,
  created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE TABLE merchants (
  id UUID PRIMARY KEY,
  agency_id UUID NOT NULL REFERENCES agencies(id),
  name TEXT NOT NULL,
  platform TEXT NOT NULL,
  environment TEXT NOT NULL,
  webhook_endpoint_id TEXT NOT NULL UNIQUE,
  oxapay_merchant_api_key_encrypted TEXT NOT NULL,
  active BOOLEAN NOT NULL DEFAULT TRUE,
  created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE TABLE deployment_manifests (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  version INTEGER NOT NULL,
  manifest JSONB NOT NULL,
  approved_by TEXT,
  approved_at TIMESTAMP,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (merchant_id, version)
);

CREATE TABLE payment_sessions (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  provider TEXT NOT NULL DEFAULT 'oxapay',
  provider_order_id TEXT NOT NULL,
  provider_track_id TEXT,
  integration_mode TEXT NOT NULL,
  requested_amount NUMERIC(20, 8) NOT NULL,
  pricing_currency TEXT NOT NULL,
  provider_status TEXT,
  internal_status TEXT NOT NULL DEFAULT 'created',
  payment_url TEXT,
  expires_at TIMESTAMP,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (merchant_id, provider_order_id),
  UNIQUE (provider, provider_track_id)
);

CREATE TABLE payment_events (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  payment_session_id UUID REFERENCES payment_sessions(id),
  payload_hash TEXT NOT NULL,
  provider_status TEXT,
  raw_payload JSONB NOT NULL,
  signature_valid BOOLEAN NOT NULL,
  source TEXT NOT NULL,
  received_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (merchant_id, payload_hash)
);

CREATE TABLE fulfillment_actions (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  payment_session_id UUID NOT NULL REFERENCES payment_sessions(id),
  action_type TEXT NOT NULL,
  idempotency_key TEXT NOT NULL UNIQUE,
  status TEXT NOT NULL,
  attempt_count INTEGER NOT NULL DEFAULT 0,
  last_error TEXT,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  completed_at TIMESTAMP
);

CREATE TABLE launch_checks (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  check_key TEXT NOT NULL,
  status TEXT NOT NULL,
  evidence JSONB,
  checked_by TEXT,
  checked_at TIMESTAMP,
  UNIQUE (merchant_id, check_key)
);

CREATE TABLE operational_cases (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  payment_session_id UUID REFERENCES payment_sessions(id),
  case_type TEXT NOT NULL,
  severity TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'open',
  owner_type TEXT NOT NULL,
  summary TEXT NOT NULL,
  resolution_note TEXT,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  resolved_at TIMESTAMP
);

The deployment manifest and launch checks are agency-specific additions.

They are not normally part of a basic merchant integration.

Create the local payment session first

The agency implementation should create an authoritative local session before calling OxaPay.

import crypto from "node:crypto";

const OXAPAY_API = "https://api.oxapay.com/v1";

export async function createMerchantInvoice({
  merchant,
  order,
}) {
  const providerOrderId =
    `order_${merchant.id}_${order.id}`;

  const session =
    await db.paymentSession.create({
      data: {
        merchantId: merchant.id,
        provider: "oxapay",
        providerOrderId,
        integrationMode: "hosted_invoice",
        requestedAmount: order.amount,
        pricingCurrency: order.currency,
        internalStatus: "created",
      },
    });

  try {
    const merchantApiKey = await decryptSecret(
      merchant.oxapayMerchantApiKeyEncrypted,
    );

    const response = await fetch(
      `${OXAPAY_API}/payment/invoice`,
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          merchant_api_key: merchantApiKey,
        },
        body: JSON.stringify({
          amount: order.amount,
          currency: order.currency,
          order_id: providerOrderId,
          email: order.customerEmail,
          description: `Payment for order ${order.number}`,
          callback_url:
            `${process.env.APP_URL}/webhooks/oxapay/${merchant.webhookEndpointId}`,
          return_url:
            `${order.merchantBaseUrl}/orders/${order.id}/status`,
          lifetime: 60,
          sandbox:
            merchant.environment !== "production",
        }),
      },
    );

    const payload = await response.json();

    if (!response.ok) {
      throw new Error(
        payload?.error?.message ??
          `Invoice creation failed with ${response.status}`,
      );
    }

    const payment = payload.data;

    return db.paymentSession.update({
      where: {
        id: session.id,
      },
      data: {
        providerTrackId: String(payment.track_id),
        providerStatus: "new",
        internalStatus: "invoice_created",
        paymentUrl: payment.payment_url,
        expiresAt: payment.expired_at
          ? new Date(Number(payment.expired_at) * 1000)
          : null,
      },
    });
  } catch (error) {
    await db.paymentSession.update({
      where: {
        id: session.id,
      },
      data: {
        internalStatus: "creation_failed",
      },
    });

    throw error;
  }
}

The agency should adapt the order adapter to the merchant platform.

The core payment module should remain consistent.

Use a standard webhook module

OxaPay signs payment callbacks with HMAC SHA-512 over the raw request body using the Merchant API Key.

import crypto from "node:crypto";
import express from "express";

const app = express();

app.post(
  "/webhooks/oxapay/:endpointId",
  express.raw({
    type: "application/json",
  }),
  async (req, res) => {
    const merchant = await db.merchant.findUnique({
      where: {
        webhookEndpointId: req.params.endpointId,
      },
    });

    if (!merchant || !merchant.active) {
      return res.status(404).send("unknown endpoint");
    }

    const rawBody = req.body;
    const receivedHmac = req.get("HMAC");

    const merchantApiKey = await decryptSecret(
      merchant.oxapayMerchantApiKeyEncrypted,
    );

    const expectedHmac = crypto
      .createHmac("sha512", merchantApiKey)
      .update(rawBody)
      .digest("hex");

    if (!safeEqualSha512(receivedHmac, expectedHmac)) {
      await recordRejectedCallback({
        merchantId: merchant.id,
        reason: "invalid_hmac",
      });

      return res.status(401).send("invalid signature");
    }

    let payload;

    try {
      payload = JSON.parse(
        rawBody.toString("utf8"),
      );
    } catch {
      return res.status(400).send("invalid json");
    }

    const payloadHash = crypto
      .createHash("sha256")
      .update(rawBody)
      .digest("hex");

    try {
      const stored = await persistEventAndOutboxOnce({
        merchant,
        payload,
        payloadHash,
      });

      if (!stored) {
        return res.status(200).send("ok");
      }

      return res.status(200).send("ok");
    } catch (error) {
      console.error(
        "Webhook persistence failed",
        error,
      );

      return res.status(500).send("failed");
    }
  },
);

function safeEqualSha512(received, expected) {
  const sha512Hex = /^[a-f0-9]{128}$/i;

  if (
    !received ||
    !expected ||
    !sha512Hex.test(received) ||
    !sha512Hex.test(expected)
  ) {
    return false;
  }

  return crypto.timingSafeEqual(
    Buffer.from(received, "hex"),
    Buffer.from(expected, "hex"),
  );
}

persistEventAndOutboxOnce should use one database transaction:

Insert payment event
+
Insert processing job
+
Commit

If the event already exists, return successfully without creating another job.

The callback endpoint should not call the merchant fulfillment system directly.

Standardize payment status mapping

const PAYMENT_STATUS_MAP = {
  new: "created",
  waiting: "waiting",
  paying: "confirming",
  paid: "paid",
  manual_accept: "manual_review",
  underpaid: "underpaid",
  expired: "expired",
  refunding: "refund_in_progress",
  refunded: "refunded",
};

export function mapPaymentStatus(status) {
  const normalized = String(status ?? "")
    .trim()
    .toLowerCase();

  return PAYMENT_STATUS_MAP[normalized] ?? "unknown";
}

The merchant workflow should normally fulfill on:

paid

not:

paying

The agency acceptance test should explicitly verify this behavior.

Use merchant adapters

Do not copy the full webhook handler for every platform.

Build adapters behind a shared contract.

type MerchantAdapter = {
  findOrder(
    externalOrderId: string
  ): Promise<MerchantOrder | null>;

  markPaymentDetected(
    order: MerchantOrder
  ): Promise<void>;

  markPaid(
    order: MerchantOrder
  ): Promise<void>;

  fulfill(
    order: MerchantOrder,
    idempotencyKey: string
  ): Promise<FulfillmentResult>;

  verifyFulfillment(
    order: MerchantOrder
  ): Promise<boolean>;
};

Possible adapters include:

WooCommerce
WHMCS
Laravel application
Node.js application
Digital download store
SaaS billing system
Telegram membership system

The payment runtime stays stable.

The adapter translates provider events into platform-specific actions.

Make fulfillment idempotent

A stable fulfillment key can include:

merchant_id
+ provider_track_id
+ fulfillment_action

async function fulfillOrderOnce({
  merchant,
  session,
  adapter,
}) {
  const idempotencyKey = [
    merchant.id,
    session.providerTrackId,
    "fulfill_order",
  ].join(":");

  const existing =
    await db.fulfillmentAction.findUnique({
      where: {
        idempotencyKey,
      },
    });

  if (existing?.status === "completed") {
    return existing;
  }

  const order = await adapter.findOrder(
    session.providerOrderId,
  );

  if (!order) {
    throw new PermanentLaunchError(
      "Merchant order not found",
    );
  }

  const action =
    existing ??
    (await db.fulfillmentAction.create({
      data: {
        merchantId: merchant.id,
        paymentSessionId: session.id,
        actionType: "fulfill_order",
        idempotencyKey,
        status: "running",
        attemptCount: 1,
      },
    }));

  try {
    await adapter.markPaid(order);

    const result = await adapter.fulfill(
      order,
      idempotencyKey,
    );

    const verified =
      await adapter.verifyFulfillment(order);

    if (!verified) {
      throw new TransientLaunchError(
        "Fulfillment outcome could not be verified",
      );
    }

    await db.fulfillmentAction.update({
      where: {
        id: action.id,
      },
      data: {
        status: "completed",
        completedAt: new Date(),
      },
    });

    return result;
  } catch (error) {
    await recordFulfillmentFailure({
      actionId: action.id,
      error,
    });

    throw error;
  }
}

A callback duplicate should not create a second product delivery or service extension.

Add recovery by default

The Launch Kit should not offer Payment History recovery as an optional afterthought.

A production deployment should include it by default.

A scheduled task can:

Retrieve recent OxaPay payments
-> Match by track_id or order_id
-> Update local provider state
-> Detect missed callbacks
-> Detect paid but unfulfilled orders
-> Create operational cases

OxaPay Payment History is currently available through:

GET /v1/payment

Payment Information retrieves one payment through:

GET /v1/payment/{track_id}

A practical schedule is:

Every 10 minutes:
- query an overlapping recent time window
- upsert provider records
- identify missing local events
- retry safe processing

Every night:
- compare paid payments with merchant fulfillment
- generate unresolved-case report

The recovery job should identify its source:

source = payment_history_backfill

Do not make recovered records look like original callbacks.

The agency acceptance-test matrix

Testing should cover more than one successful payment.

Test	Expected result
Invoice creation	Local session and provider `track_id` stored
Invalid HMAC	Request rejected and no business state changed
`paying` callback	Payment detected, fulfillment not started
`paid` callback	Fulfillment queued once
Duplicate `paid` callback	No duplicate fulfillment
Unknown `track_id`	Operational case created
Provider timeout	Local failure visible and retry policy applied
Fulfillment failure	Payment remains paid and case is opened
Missed callback	Payment History recovery finds payment
Expired invoice	Order remains unresolved under merchant policy
Customer status page	Displays correct business state
Merchant export	Includes expected identifiers and amounts
Credential rotation	New key works and old access is removed

Each result should have evidence.

Evidence can include:

screenshot
database record
event ID
test order
sanitized API response
log reference
fulfillment record

“Tested successfully” without evidence is not a professional launch report.

Generate a launch report

The kit should generate a client-specific report.

launch:
  merchant: Acme Software
  environment: production
  completed_at: 2026-07-28T09:30:00Z

integration:
  mode: hosted_invoice
  webhook_endpoint: configured
  hmac_validation: passed
  payment_history_recovery: enabled

acceptance_tests:
  invoice_creation: passed
  paying_does_not_fulfill: passed
  paid_fulfills_once: passed
  duplicate_callback: passed
  recovery_job: passed
  customer_status_page: passed

credentials:
  owner: merchant
  stored_in: managed_secret_vault
  agency_access_expires: 2026-08-11

handoff:
  merchant_admin_trained: true
  support_sop_delivered: true
  escalation_contacts_confirmed: true

This report protects both the merchant and the agency.

Build the handoff package

The merchant should receive a package containing:

Payment-flow summary

Customer creates order
-> OxaPay invoice created
-> Customer pays
-> Payment callback verified
-> Order marked paid
-> Fulfillment begins

Dashboard guide

Explain:

how to find an order
how to search by track_id
how to identify paying, paid, and expired
how to find a failed fulfillment
how to export records

Support SOP

Cover at least:

customer says payment was sent
payment is still confirming
invoice expired
payment is underpaid
payment is paid but order is pending
fulfillment failed
customer paid twice
payment cannot be found

Credential register

Record:

account owner
Merchant API Key owner
storage location
agency access
rotation process
emergency revocation process

Do not include raw credentials in the handoff document.

Responsibility matrix

Activity	Merchant	Agency	Payment provider
OxaPay account ownership	Responsible	Consulted	Support
Merchant API Key creation	Responsible	Consulted	Provides system
Integration deployment	Consulted	Responsible	Not responsible
Customer-order support	Responsible	Escalation support	Payment evidence
Application fulfillment	Accountable	Implementation support	Not responsible
Callback delivery	Informed	Monitors endpoint	Responsible for sending
Recovery job	Informed	Responsible during contract	Provides API
Refund policy	Responsible	Not legal owner	Executes supported operations

Ownership should be agreed before launch.

Define post-launch support

Every launch should have a monitoring window.

For example:

Launch day:
Review real transaction and callback health

First 72 hours:
Daily unresolved-case review

First 14 days:
Monitor webhook errors, fulfillment failures, and support issues

After monitoring period:
Move to merchant operation or maintenance plan

The agency contract should state:

monitoring duration
support hours
incident channels
response targets
included changes
excluded changes
credential-access expiry
maintenance price

Without this boundary, a one-time launch project can become unlimited operational support.

Version client configurations

Merchant requirements change.

A client may:

add another currency
change checkout mode
add a new fulfillment adapter
rotate credentials
change callback domains
update support ownership

Do not edit production configuration without version history.

Manifest version 1
-> Hosted invoice and email delivery

Manifest version 2
-> Add customer status page

Manifest version 3
-> Add white-label checkout

Every change should record:

requester
approver
implementation date
test evidence
rollback plan

The Launch Kit should standardize change management, not only initial deployment.

Build the agency portal later

The first version can be a repository, templates, and a managed implementation process.

An agency portal becomes useful after several deployments share the same needs.

Possible portal features:

merchant onboarding
manifest management
encrypted credential storage
integration-track selection
launch-check progress
webhook-health monitoring
client-specific dashboards
support-case routing
report generation
handoff-package generation
configuration versioning
agency staff permissions

Do not build the portal before the delivery process is proven manually.

Software should automate a stable process, not hide an undefined one.

Product packaging

Plugin Launch

For merchants using supported platforms.

Includes:

compatibility review
plugin installation
API configuration
checkout test
order-status test
support guide
handoff
short monitoring period

Custom Invoice Launch

For custom stores, SaaS apps, and client portals.

Includes:

local payment session
hosted invoice
signed webhook processing
order adapter
Payment Information refresh
Payment History recovery
status page
acceptance testing

White-Label Launch

For premium branded checkout.

Includes everything in Custom Invoice Launch plus:

embedded payment UI
network instructions
QR and address display
expiry handling
custom payment states
UX testing

Agency Platform

For agencies with several merchant clients.

Includes:

multi-client configuration
tenant isolation
webhook monitoring
reusable adapters
launch reports
handoff generation
role-based access
maintenance workflow

The commercial value increases with operational responsibility, not only code quantity.

The MVP

The first version of the Launch Kit should support two tracks:

Plugin deployment
Hosted invoice deployment

Build:

client qualification scorecard
discovery questionnaire
decision tree
implementation manifest
one plugin deployment guide
one custom invoice module
merchant-specific webhook endpoint
HMAC validation
payment-event storage
idempotent fulfillment adapter
Payment Information refresh
Payment History recovery
acceptance-test matrix
launch report
support SOP
merchant handoff template
14-day monitoring plan

Do not include initially:

every OxaPay plugin
every programming framework
custom payout systems
full agency SaaS portal
advanced accounting
legal or tax automation
unlimited merchant customization
dozens of dashboard roles

Prove that the same delivery system can launch two similar clients successfully.

Common mistakes

Selling only code

Agencies need scope, testing, documentation, and support boundaries.

Rebuilding a plugin unnecessarily

Use an existing plugin when it fully satisfies the merchant workflow.

Treating every merchant the same

Hosted checkout, white-label checkout, and account funding have different risks and scopes.

Starting implementation before discovery

Undefined fulfillment and support ownership create production incidents later.

Fulfilling inside the callback request

Persist the event and execute business actions asynchronously.

Returning success before durable storage

Do not acknowledge a callback that can disappear before processing.

Testing only the happy path

Duplicate events, invalid signatures, missed callbacks, and fulfillment failures are normal production concerns.

Giving the agency permanent credential access

Define who owns credentials and when agency access should end.

Handing over without support procedures

The merchant will otherwise send every payment question back to the agency.

Offering unlimited customization

Keep the core stable and charge separately for client-specific adapters.

Security baseline

Every custom deployment should include:

HTTPS callbacks
raw-body HMAC validation
timing-safe comparison
merchant-specific credentials
encrypted secret storage
tenant isolation
test and production separation
payment-event deduplication
fulfillment idempotency
transactional outbox
Payment Information verification
Payment History recovery
role-based dashboard access
manual-action audit logs
credential-rotation process
secret masking
post-handoff access review
incident alerting

The agency should be able to prove these controls were tested.

What makes this a real developer product?

A normal integration project says:

Connect API
-> Create payment
-> Receive webhook
-> Update order

A Merchant Crypto Launch Kit says:

Qualify merchant
-> Discover operational requirements
-> Select correct implementation track
-> Approve project boundary
-> Configure versioned deployment manifest
-> Deploy reusable runtime
-> Test payment and failure paths
-> Capture launch evidence
-> Train merchant team
-> Transfer ownership
-> Monitor production
-> Manage future changes safely

That is the difference between performing integrations and building an agency delivery product.

Final takeaway

Agencies do not need another collection of payment snippets.

They need a repeatable system for delivering crypto payment projects without recreating decisions, code, testing, documentation, and support processes for every client.

OxaPay provides the payment primitives:

hosted invoices
white-label payments
static addresses
unique track_id references
signed callbacks
Payment Information
Payment History
plugins
SDKs
automation integrations
optional payout APIs

The Launch Kit provides the agency layer:

qualification
discovery
architecture selection
reusable implementation
merchant adapters
acceptance testing
launch evidence
handoff
responsibility assignment
production monitoring
change management

Start with one agency type.

Support two implementation tracks.

Launch one client through a plugin.

Launch another through a custom hosted invoice.

Document every decision.

Test every failure path.

Make ownership explicit.

That is how one-off crypto payment work becomes a repeatable agency product.

Which agency would you build for first: ecommerce, hosting, SaaS, digital products, or creator communities?

References

OxaPay API

OxaPay integrations

Build a Payment Automation Studio for Crypto Merchants

kevin.s — Thu, 16 Jul 2026 07:30:20 +0000

The payment succeeded.

The customer still has no access.

OxaPay reports the invoice as paid, but the SaaS plan remains inactive. The payment callback reached the merchant's server, yet the downstream account service timed out.

The payment system worked.

The automation around it failed.

This distinction matters because payment is rarely the final business outcome.

A confirmed payment may need to:

deliver a digital product
activate a SaaS plan
provision a hosting account
assign a software license
grant Telegram or Discord access
update an order
update a CRM
notify a finance team
create a support case
write a reporting record
call a merchant-owned API

A Payment Automation Studio turns verified payment events into controlled business actions.

It is not a webhook relay.

It is not a collection of if status === "paid" statements.

It is an execution system that can prove:

which event arrived
whether the event was authentic
which workflow version matched
which conditions passed
which actions were attempted
which actions completed
which actions failed
whether an action was retried
whether approval was required
whether the final business outcome was verified
whether a human must intervene

This article uses OxaPay as the payment infrastructure reference, but the automation architecture is provider-agnostic.

This article is part of 10 Crypto Payment Products Developers Can Build for Merchants.

The real automation model

The simplest payment automation looks like this:

Payment paid
-> Activate SaaS plan

That works in a demo.

A production workflow needs more stages:

Payment event
-> Verify authenticity
-> Preserve evidence
-> Normalize event
-> Validate state transition
-> Match published workflow
-> Evaluate conditions
-> Verify current provider state
-> Execute actions idempotently
-> Verify outcomes
-> Retry or escalate
-> Record final result

The reliable model is:

Verified event
-> Versioned policy
-> Controlled actions
-> Verified outcome

The difference between a webhook script and an automation product is everything around the action.

Do not promise exactly-once delivery

Payment callbacks, queues, and distributed workers normally behave with at-least-once delivery.

That means:

the same callback may arrive twice
the same queue job may run twice
a worker may crash after completing an external action
the response to an external API may be lost
a recovery job may rediscover an earlier payment

The system should not pretend these events happen exactly once.

Instead, design for effectively-once business execution:

At-least-once event delivery
+
Event deduplication
+
Business-transition deduplication
+
Action-level idempotency
+
Outcome reconciliation
=
Effectively-once merchant outcome

For example, a callback may be processed several times, but the customer must receive only one license.

Where the Automation Studio fits

A Crypto PaymentOps Service manages the broader operational payment lifecycle.

A Crypto Payment Reconciliation Tool detects disagreements between payment, order, fulfillment, and finance records.

A Crypto Payment Support Desk helps agents investigate and resolve incidents.

The Automation Studio has a narrower responsibility:

Convert verified payment events into repeatable business actions.

For example:

OxaPay payment becomes paid
-> Verify order
-> Activate subscription
-> Send confirmation
-> Update CRM
-> Notify merchant

Reconciliation may later detect that activation did not happen.

The Support Desk may help resolve the incident.

The Automation Studio owns the workflow execution itself.

It is not an n8n clone

A useful Payment Automation Studio does not need to compete with every general automation platform.

Its advantage is payment-specific control.

It understands:

payment states
track_id
merchant order_id
amount verification
confirmation policy
underpayments
expired sessions
refunds
fulfillment idempotency
payment recovery
paid-but-not-completed incidents

A generic automation tool can connect APIs.

A payment-specific product can understand whether a business action is safe.

Separate the control plane from the execution plane

The product has two major areas.

Control plane

The control plane lets merchants and operators:

create workflows
configure triggers
define conditions
select actions
connect credentials
validate definitions
run simulations
publish versions
pause workflows
review execution history
approve sensitive actions
replay failed executions

Execution plane

The execution plane:

receives events
validates signatures
stores evidence
matches published workflows
creates executions
claims action jobs
calls connectors
retries failures
verifies outcomes
opens operational cases

Do not let workflow-editing requests execute business actions directly.

Publishing and execution should remain separate.

Define workflows as data

A workflow should not exist only as hardcoded application logic.

Represent it as a versioned definition.

name: Deliver license after confirmed payment
version: 4

trigger:
  source: oxapay
  type: payment.status_changed
  transition: paid

conditions:
  all:
    - field: event.order_id
      operator: exists

    - field: event.status
      operator: equals
      value: paid

    - field: order.status
      operator: not_in
      value:
        - canceled
        - refunded

actions:
  - id: load_order
    type: internal.get_order
    input:
      order_id: "{{ event.order_id }}"

  - id: verify_payment
    type: oxapay.verify_payment
    depends_on:
      - load_order
    input:
      track_id: "{{ event.track_id }}"
      expected_order_id: "{{ order.external_order_id }}"
      expected_amount: "{{ order.total }}"

  - id: assign_license
    type: license.assign
    depends_on:
      - verify_payment
    input:
      product_id: "{{ order.product_id }}"
      order_id: "{{ order.id }}"
      customer_email: "{{ order.customer_email }}"

  - id: send_delivery
    type: email.send
    depends_on:
      - assign_license
    input:
      to: "{{ order.customer_email }}"
      template: license_delivery
      license_key: "{{ actions.assign_license.license_key }}"

  - id: notify_merchant
    type: telegram.send_message
    depends_on:
      - assign_license
    input:
      chat_id: "{{ merchant.telegram_chat_id }}"
      message: "Order {{ order.id }} was paid and delivered."

retry_policy:
  max_attempts: 5
  strategy: exponential

failure_policy:
  create_case: true
  notify_merchant: true

This definition contains:

Trigger
Conditions
Action graph
Dependencies
Retry policy
Failure policy

A merchant can understand the business flow.

A developer can validate, version, test, and audit it.

Use an explicit workflow lifecycle

A workflow should move through controlled states.

draft
-> validated
-> published
-> paused
-> retired

Draft

The merchant can edit the workflow.

It cannot process live events.

Validated

The workflow has passed structural and security checks.

Published

An immutable version can process new events.

Paused

The version remains available for investigation, but no new execution starts.

Retired

The workflow is no longer available for new events.

Existing executions still reference it.

Do not allow an editable draft to become production logic automatically.

Validate workflows before publishing

Validation should check:

trigger type is supported
all action IDs are unique
dependencies reference valid actions
the action graph has no cycles
required connector credentials exist
condition operators are permitted
template variables are valid
sensitive actions include approval policy
retry limits are within platform bounds
generic HTTP destinations satisfy security rules
the workflow has at least one terminal outcome

export function validateWorkflowDefinition(
  definition,
) {
  const errors = [];

  if (!definition.trigger?.type) {
    errors.push("Workflow trigger is required");
  }

  const actionIds = new Set();

  for (const action of definition.actions ?? []) {
    if (!action.id) {
      errors.push("Every action requires an id");
      continue;
    }

    if (actionIds.has(action.id)) {
      errors.push(
        `Duplicate action id: ${action.id}`,
      );
    }

    actionIds.add(action.id);
  }

  for (const action of definition.actions ?? []) {
    for (const dependency of action.depends_on ?? []) {
      if (!actionIds.has(dependency)) {
        errors.push(
          `Action ${action.id} depends on unknown action ${dependency}`,
        );
      }
    }
  }

  if (containsDependencyCycle(definition.actions ?? [])) {
    errors.push("Workflow contains a dependency cycle");
  }

  if (errors.length > 0) {
    throw new WorkflowValidationError(errors);
  }
}

The published version should be immutable.

Editing creates a new draft version.

Pin every execution to one version

Suppose a merchant edits a workflow after an incident.

The historical execution must still show the exact logic used at that time.

Workflow: Deliver License
Published version: 4

Execution: EX-1042
Workflow version: 3
Payment event: EVT-5508

The execution stays attached to version 3.

Without immutable versions, the dashboard may display today's workflow while explaining an event processed under yesterday's rules.

The production architecture

+----------------------+
| Merchant Checkout    |
+----------+-----------+
           |
           | Create payment
           v
+----------------------+
| OxaPay API           |
+----------+-----------+
           |
           | Signed callback
           v
+----------------------+
| Webhook Gateway      |
+----------+-----------+
           |
           | Validate and persist
           v
+----------------------+
| Event Inbox          |
+----------+-----------+
           |
           v
+----------------------+
| Transactional Outbox |
+----------+-----------+
           |
           v
+----------------------+
| Event Normalizer     |
+----------+-----------+
           |
           v
+----------------------+
| Workflow Matcher     |
+----------+-----------+
           |
           v
+----------------------+
| Execution Planner    |
+----------+-----------+
           |
           v
+----------------------+
| Action Queue         |
+----------+-----------+
           |
      +----+------------------+
      |                       |
      v                       v
Connector Workers       Approval Queue
      |                       |
      +-----------+-----------+
                  |
                  v
+----------------------+
| Outcome Verification |
+----------+-----------+
           |
           v
Retry / Replay / Review / Metrics

The webhook endpoint should not:

activate subscriptions
assign licenses
provision servers
send customer emails
update CRMs
initiate payouts

Its job is limited:

Identify the merchant endpoint.
Preserve the raw request body.
validate the HMAC signature.
Persist the event durably.
Create an outbox record.
Return the required response.

Slow and failure-prone work belongs in workers.

Use a tenant-specific webhook endpoint

A multi-merchant system needs the correct Merchant API Key before it can validate an OxaPay payment callback.

Do not trust an unverified payload to select that key.

Use a merchant-specific public endpoint identifier:

https://studio.example.com/webhooks/oxapay/{endpoint_id}

The endpoint ID:

identifies the merchant integration
is not the Merchant API Key
provides no dashboard access
can be rotated independently
should be difficult to guess

The backend uses it to load the encrypted Merchant API Key before validating the request.

Receive OxaPay callbacks safely

OxaPay payment callbacks include an HMAC header calculated with SHA-512 over the raw request body.

The Merchant API Key is used to validate payment callbacks.

import crypto from "node:crypto";
import express from "express";

const app = express();

app.post(
  "/webhooks/oxapay/:endpointId",
  express.raw({
    type: "application/json",
    limit: "256kb",
  }),
  async (req, res) => {
    const endpoint =
      await db.webhookEndpoint.findUnique({
        where: {
          publicId: req.params.endpointId,
        },
        include: {
          merchant: true,
        },
      });

    if (!endpoint || !endpoint.enabled) {
      return res.status(404).send("unknown endpoint");
    }

    const rawBody = req.body;
    const receivedHmac = req.get("HMAC");

    const merchantApiKey = await decryptSecret(
      endpoint.merchant
        .oxapayMerchantApiKeyEncrypted,
    );

    const expectedHmac = crypto
      .createHmac("sha512", merchantApiKey)
      .update(rawBody)
      .digest("hex");

    if (!safeEqualSha512(receivedHmac, expectedHmac)) {
      await recordRejectedWebhook({
        merchantId: endpoint.merchantId,
        endpointId: endpoint.id,
        reason: "invalid_hmac",
        receivedAt: new Date(),
      });

      return res.status(401).send("invalid signature");
    }

    let payload;

    try {
      payload = JSON.parse(
        rawBody.toString("utf8"),
      );
    } catch {
      return res.status(400).send("invalid json");
    }

    const payloadHash = crypto
      .createHash("sha256")
      .update(rawBody)
      .digest("hex");

    try {
      await persistEventAndOutbox({
        merchantId: endpoint.merchantId,
        endpointId: endpoint.id,
        provider: "oxapay",
        payloadHash,
        rawPayload: payload,
        receivedAt: new Date(),
      });

      return res.status(200).send("ok");
    } catch (error) {
      console.error(
        "Webhook persistence failed",
        error,
      );

      return res.status(500).send("failed");
    }
  },
);

function safeEqualSha512(received, expected) {
  const sha512Hex = /^[a-f0-9]{128}$/i;

  if (
    !received ||
    !expected ||
    !sha512Hex.test(received) ||
    !sha512Hex.test(expected)
  ) {
    return false;
  }

  return crypto.timingSafeEqual(
    Buffer.from(received, "hex"),
    Buffer.from(expected, "hex"),
  );
}

Do not parse the body with normal JSON middleware before HMAC verification.

The exact raw bytes must remain available.

Use a transactional outbox

Consider this sequence:

1. Store payment event
2. Publish queue message

The database write succeeds.

The queue becomes unavailable before step 2.

The event exists, but no workflow will process it.

Use one database transaction:

Insert event
+
Insert outbox record
+
Commit

A separate dispatcher publishes pending outbox records.

async function persistEventAndOutbox({
  merchantId,
  endpointId,
  provider,
  payloadHash,
  rawPayload,
  receivedAt,
}) {
  return db.$transaction(async (tx) => {
    const existing =
      await tx.paymentEvent.findUnique({
        where: {
          merchantId_payloadHash: {
            merchantId,
            payloadHash,
          },
        },
      });

    if (existing) {
      return existing;
    }

    const event = await tx.paymentEvent.create({
      data: {
        merchantId,
        endpointId,
        provider,
        source: "webhook",
        payloadHash,
        rawPayload,
        signatureValid: true,
        receivedAt,
      },
    });

    await tx.outboxJob.create({
      data: {
        merchantId,
        topic: "payment.event_received",
        payload: {
          paymentEventId: event.id,
        },
      },
    });

    return event;
  });
}

The queue dispatcher can retry without losing the original event.

Use a normalized event envelope

Do not let provider-specific payloads spread across workflow definitions.

Create an internal event envelope.

import crypto from "node:crypto";

export function normalizeOxaPayEvent({
  merchantId,
  paymentEventId,
  payload,
  source,
}) {
  return {
    eventId: crypto.randomUUID(),
    storedEventId: paymentEventId,
    merchantId,
    provider: "oxapay",
    type: "payment.status_changed",
    source,
    correlationId:
      String(payload.track_id ?? paymentEventId),
    causationId: paymentEventId,
    causationDepth: 0,
    occurredAt: payload.date
      ? new Date(payload.date)
      : new Date(),
    data: {
      trackId: String(payload.track_id ?? ""),
      orderId: payload.order_id
        ? String(payload.order_id)
        : null,
      status: String(payload.status ?? "")
        .trim()
        .toLowerCase(),
      amount: payload.amount ?? null,
      currency: payload.currency ?? null,
      network: payload.network ?? null,
      transactionHash:
        payload.tx_hash ??
        payload.transaction_hash ??
        null,
    },
    providerPayload: payload,
  };
}

Workflow conditions then evaluate:

event.data.status
event.data.orderId
event.data.amount
event.data.currency

instead of using provider-specific fields throughout the codebase.

Use correlation and causation IDs

Payment automation can create new events.

For example:

Payment paid
-> Activate subscription
-> Subscription activated event
-> Send onboarding email

Without causation tracking, one workflow may trigger another workflow that recreates the original event.

This can produce an automation loop.

Every internal event should record:

correlationId: groups events belonging to one business process
causationId: identifies the event or action that created this event
causationDepth: limits how far an event chain can continue

Example:

Payment event EVT-1
correlation_id = track_8182
causation_id = webhook_5508
depth = 0

Subscription event EVT-2
correlation_id = track_8182
causation_id = action_activate_subscription
depth = 1

Prevent workflow loops

A workflow should not trigger itself indefinitely.

Use several controls:

maximum causation depth
workflow execution deduplication
action-generated event metadata
trigger filters
suppression of identical transitions
merchant-configured loop rules

function assertEventChainAllowed(event) {
  const MAX_CAUSATION_DEPTH = 10;

  if (
    event.causationDepth >
    MAX_CAUSATION_DEPTH
  ) {
    throw new PermanentWorkflowError(
      "Maximum automation chain depth exceeded",
    );
  }
}

Also prevent one workflow version from processing the same business transition twice:

workflow_version_id
+
provider_track_id
+
normalized_transition

Separate three forms of deduplication

Exact event deduplication

The same raw callback arrives more than once.

merchant_id + payload_hash

Business-transition deduplication

Different payloads represent the same transition.

merchant_id
+ provider
+ track_id
+ transition_to_paid

Action idempotency

The same business transition attempts the same action again.

merchant_id
+ workflow_version_id
+ track_id
+ transition
+ action_id

Example:

m_42:wf_9_v4:track_8182:paid:assign_license

All three are necessary.

A raw-body hash alone cannot prevent two different paid payloads from assigning two licenses.

A practical data model

CREATE TABLE payment_events (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL,
  endpoint_id UUID,
  provider TEXT NOT NULL,
  source TEXT NOT NULL,
  payload_hash TEXT NOT NULL,
  provider_track_id TEXT,
  provider_order_id TEXT,
  provider_status TEXT,
  normalized_status TEXT,
  correlation_id TEXT,
  causation_id TEXT,
  raw_payload JSONB NOT NULL,
  signature_valid BOOLEAN NOT NULL,
  received_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (merchant_id, payload_hash)
);

CREATE TABLE business_transitions (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL,
  provider TEXT NOT NULL,
  provider_track_id TEXT NOT NULL,
  transition_key TEXT NOT NULL,
  payment_event_id UUID NOT NULL REFERENCES payment_events(id),
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (
    merchant_id,
    provider,
    provider_track_id,
    transition_key
  )
);

CREATE TABLE workflows (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL,
  name TEXT NOT NULL,
  lifecycle_status TEXT NOT NULL DEFAULT 'draft',
  current_draft_version INTEGER,
  published_version INTEGER,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE TABLE workflow_versions (
  id UUID PRIMARY KEY,
  workflow_id UUID NOT NULL REFERENCES workflows(id),
  version INTEGER NOT NULL,
  definition JSONB NOT NULL,
  definition_hash TEXT NOT NULL,
  lifecycle_status TEXT NOT NULL,
  created_by UUID,
  published_by UUID,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  published_at TIMESTAMP,
  UNIQUE (workflow_id, version)
);

CREATE TABLE workflow_executions (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL,
  workflow_version_id UUID NOT NULL REFERENCES workflow_versions(id),
  payment_event_id UUID NOT NULL REFERENCES payment_events(id),
  business_transition_id UUID REFERENCES business_transitions(id),
  correlation_id TEXT NOT NULL,
  causation_id TEXT,
  status TEXT NOT NULL,
  context JSONB NOT NULL,
  started_at TIMESTAMP,
  completed_at TIMESTAMP,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (
    workflow_version_id,
    business_transition_id
  )
);

CREATE TABLE action_executions (
  id UUID PRIMARY KEY,
  workflow_execution_id UUID NOT NULL REFERENCES workflow_executions(id),
  action_id TEXT NOT NULL,
  action_type TEXT NOT NULL,
  idempotency_key TEXT NOT NULL UNIQUE,
  status TEXT NOT NULL,
  attempt_count INTEGER NOT NULL DEFAULT 0,
  lease_owner TEXT,
  lease_expires_at TIMESTAMP,
  request_data JSONB,
  result_data JSONB,
  outcome_verified BOOLEAN NOT NULL DEFAULT FALSE,
  last_error TEXT,
  next_attempt_at TIMESTAMP,
  started_at TIMESTAMP,
  completed_at TIMESTAMP,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (workflow_execution_id, action_id)
);

CREATE TABLE connector_credentials (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL,
  connector_type TEXT NOT NULL,
  display_name TEXT NOT NULL,
  encrypted_secret JSONB NOT NULL,
  status TEXT NOT NULL DEFAULT 'active',
  last_verified_at TIMESTAMP,
  rotated_at TIMESTAMP,
  created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE TABLE approval_requests (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL,
  workflow_execution_id UUID NOT NULL REFERENCES workflow_executions(id),
  action_execution_id UUID NOT NULL REFERENCES action_executions(id),
  approval_type TEXT NOT NULL,
  snapshot_hash TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'pending',
  requested_at TIMESTAMP NOT NULL DEFAULT NOW(),
  decided_at TIMESTAMP,
  decided_by UUID,
  decision_reason TEXT
);

CREATE TABLE execution_cases (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL,
  workflow_execution_id UUID REFERENCES workflow_executions(id),
  action_execution_id UUID REFERENCES action_executions(id),
  case_type TEXT NOT NULL,
  severity TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'open',
  summary TEXT NOT NULL,
  evidence JSONB,
  recommended_action TEXT,
  resolution_note TEXT,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  resolved_at TIMESTAMP
);

CREATE TABLE outbox_jobs (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL,
  topic TEXT NOT NULL,
  payload JSONB NOT NULL,
  status TEXT NOT NULL DEFAULT 'pending',
  attempt_count INTEGER NOT NULL DEFAULT 0,
  available_at TIMESTAMP NOT NULL DEFAULT NOW(),
  published_at TIMESTAMP,
  created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

The schema separates:

Evidence
Business transition
Workflow definition
Workflow execution
Action execution
Credential
Approval
Operational case

That separation makes investigation and replay possible.

Prevent invalid payment-state regression

Distributed events may arrive late or out of order.

The local payment state should not move silently from a stronger state back to a weaker state.

For example:

paid -> paying

should normally be rejected.

However:

paid -> refunding -> refunded

may be valid.

const ALLOWED_TRANSITIONS = {
  new: new Set([
    "waiting",
    "paying",
    "paid",
    "underpaid",
    "expired",
  ]),

  waiting: new Set([
    "paying",
    "paid",
    "underpaid",
    "expired",
  ]),

  paying: new Set([
    "paid",
    "underpaid",
    "expired",
  ]),

  paid: new Set([
    "refunding",
    "refunded",
  ]),

  underpaid: new Set([
    "manual_accept",
    "paid",
    "expired",
  ]),

  manual_accept: new Set([
    "refunding",
    "refunded",
  ]),

  refunding: new Set([
    "refunded",
  ]),

  refunded: new Set(),
  expired: new Set(),
};

export function canTransition(
  currentStatus,
  nextStatus,
) {
  if (
    !currentStatus ||
    currentStatus === nextStatus
  ) {
    return true;
  }

  return (
    ALLOWED_TRANSITIONS[
      currentStatus
    ]?.has(nextStatus) ?? false
  );
}

Merchant policy may require additional transitions.

The important point is that late events must not silently reverse business state.

Use a restricted condition language

Do not execute arbitrary merchant JavaScript inside the workflow engine.

Allow a small set of operators:

equals
not_equals
exists
not_exists
greater_than
less_than
in
not_in
starts_with
contains

const CONDITION_OPERATORS = {
  equals: (actual, expected) =>
    actual === expected,

  not_equals: (actual, expected) =>
    actual !== expected,

  exists: (actual) =>
    actual !== null &&
    actual !== undefined,

  in: (actual, expected) =>
    Array.isArray(expected) &&
    expected.includes(actual),

  greater_than: (actual, expected) =>
    decimal(actual).greaterThan(
      decimal(expected),
    ),
};

Validate field paths and operators when the workflow is published.

Do not let merchants access arbitrary process memory, environment variables, or internal database fields.

Add dry runs before live execution

A merchant should be able to test a workflow without sending real emails, assigning real licenses, or changing a production account.

Dry run mode should:

load a sample event
evaluate triggers
evaluate conditions
render action inputs
validate credentials
show which actions would run
replace side effects with simulated results
report missing data
report policy violations

Example result:

Workflow: Deliver License
Version: Draft 5

Trigger matched: yes
Conditions passed: 3 of 3

Action load_order:
Would execute

Action verify_payment:
Would execute

Action assign_license:
Simulation only

Action send_delivery:
Simulation only

Warnings:
Customer email is missing

A dry run tests one event.

Historical simulation tests many.

Simulate against historical events

Before publishing a changed workflow, run it against previous payment events.

Example:

Simulation period: Last 30 days
Events tested: 1,842
Would match: 1,730
Would skip: 112
Would create permanent failure: 18
Would require approval: 4
Potential duplicate action keys: 0

Historical simulation helps detect:

overbroad conditions
missing fields
unintended matches
newly blocked actions
changes in action volume
possible automation loops

The simulation must not call production connectors.

Match only published workflow versions

The matcher should load published versions for the merchant and trigger type.

export async function findMatchingWorkflows({
  merchantId,
  event,
}) {
  const versions =
    await db.workflowVersion.findMany({
      where: {
        lifecycleStatus: "published",
        workflow: {
          merchantId,
          lifecycleStatus: "published",
        },
      },
      include: {
        workflow: true,
      },
    });

  return versions.filter((version) => {
    const definition = version.definition;

    return (
      triggerMatches(
        definition.trigger,
        event,
      ) &&
      conditionsPass(
        definition.conditions,
        {
          event,
        },
      )
    );
  });
}

For higher volume, index workflows by:

merchant_id
+ trigger_source
+ trigger_type
+ transition

Do not scan every workflow for every event.

Verify sensitive actions before execution

A valid webhook proves that OxaPay sent the callback.

Before an irreversible action, retrieve the latest Payment Information.

Examples of sensitive actions include:

assigning a software license
granting long-term access
provisioning paid infrastructure
increasing an internal customer balance
creating a partner earning
preparing a payout

async function getOxaPayPayment({
  merchantApiKey,
  trackId,
}) {
  const response = await fetch(
    `https://api.oxapay.com/v1/payment/${encodeURIComponent(trackId)}`,
    {
      method: "GET",
      headers: {
        "Content-Type": "application/json",
        merchant_api_key: merchantApiKey,
      },
    },
  );

  const payload = await response.json();

  if (!response.ok) {
    throw new TransientWorkflowError(
      payload?.error?.message ??
        `Payment lookup failed with ${response.status}`,
    );
  }

  return payload.data;
}

Then verify the business facts:

function assertPaymentCanFulfill({
  payment,
  order,
}) {
  if (
    String(payment.status)
      .toLowerCase() !== "paid"
  ) {
    throw new PermanentWorkflowError(
      "Payment is not in the paid state",
    );
  }

  if (
    String(payment.order_id) !==
    String(order.externalOrderId)
  ) {
    throw new PermanentWorkflowError(
      "Payment order_id does not match the order",
    );
  }

  if (
    decimal(payment.amount).lessThan(
      decimal(order.total),
    )
  ) {
    throw new PermanentWorkflowError(
      "Paid amount does not satisfy the order",
    );
  }
}

Use decimal arithmetic for financial comparisons.

Do not use JavaScript floating-point arithmetic for payment decisions.

Plan actions as a dependency graph

A workflow may include independent and dependent actions.

Verify payment
      |
      v
Assign license
   |       |
   v       v
Email   Notify merchant

send_delivery depends on assign_license.

notify_merchant may also depend on assign_license.

The planner should create an action execution only when all dependencies are complete.

function isActionReady({
  action,
  completedActionIds,
}) {
  return (
    action.depends_on ?? []
  ).every((dependencyId) =>
    completedActionIds.has(
      dependencyId,
    ),
  );
}

Do not force every workflow into one long sequential process when actions can safely run in parallel.

Claim actions with a worker lease

Several workers may attempt to execute the same action.

Use a database claim or lease.

export async function claimActionExecution({
  actionExecutionId,
  workerId,
}) {
  const now = new Date();
  const leaseExpiresAt = new Date(
    now.getTime() + 60_000,
  );

  return db.actionExecution.updateMany({
    where: {
      id: actionExecutionId,
      status: {
        in: [
          "queued",
          "retry_scheduled",
        ],
      },
      OR: [
        {
          leaseExpiresAt: null,
        },
        {
          leaseExpiresAt: {
            lt: now,
          },
        },
      ],
    },
    data: {
      status: "running",
      leaseOwner: workerId,
      leaseExpiresAt,
      startedAt: now,
      attemptCount: {
        increment: 1,
      },
    },
  });
}

Only the worker that successfully claims the action should execute it.

The idempotency key remains necessary because a worker may crash after completing an external action but before updating the database.

Execute each action idempotently

export async function executeActionOnce({
  execution,
  action,
  context,
}) {
  const idempotencyKey = [
    execution.merchantId,
    execution.workflowVersionId,
    context.event.data.trackId,
    context.event.data.status,
    action.id,
  ].join(":");

  const existing =
    await db.actionExecution.findUnique({
      where: {
        idempotencyKey,
      },
    });

  if (
    existing?.status === "completed"
  ) {
    return existing.resultData;
  }

  const record =
    existing ??
    (await db.actionExecution.create({
      data: {
        workflowExecutionId:
          execution.id,
        actionId: action.id,
        actionType: action.type,
        idempotencyKey,
        status: "running",
        attemptCount: 1,
        requestData: renderInput(
          action.input,
          context,
        ),
        startedAt: new Date(),
      },
    }));

  try {
    const result =
      await runConnectorAction({
        type: action.type,
        input: record.requestData,
        context,
        idempotencyKey,
      });

    await db.actionExecution.update({
      where: {
        id: record.id,
      },
      data: {
        status: "accepted",
        resultData:
          sanitizeConnectorResult(
            result,
          ),
      },
    });

    return result;
  } catch (error) {
    await recordActionFailure({
      actionExecutionId: record.id,
      error,
    });

    throw error;
  }
}

When the downstream API supports idempotency keys, pass the same key to it.

Your local database should not be the only protection against repeated external actions.

Distinguish request acceptance from outcome verification

An HTTP 200 response does not always prove that the business outcome happened.

For important connectors, use three states:

requested
accepted
verified

Examples:

SaaS activation returned 200
-> Query account
-> Confirm plan is active

Hosting provisioning returned accepted
-> Poll service state
-> Confirm server is active

License assignment returned success
-> Verify license belongs to the order

Telegram invite created
-> Confirm expected member joined

export async function verifyActionOutcome({
  actionExecution,
  connector,
}) {
  const verification =
    await connector.verifyOutcome({
      request:
        actionExecution.requestData,
      result:
        actionExecution.resultData,
    });

  if (!verification.verified) {
    throw new TransientWorkflowError(
      verification.reason ??
        "Business outcome is not verified",
    );
  }

  await db.actionExecution.update({
    where: {
      id: actionExecution.id,
    },
    data: {
      status: "completed",
      outcomeVerified: true,
      completedAt: new Date(),
    },
  });
}

A merchant-grade automation system verifies business outcomes, not only API responses.

Build connectors behind one interface

Start with a small connector set:

internal order API
HTTP request
email
Telegram
Discord
Google Sheets
license service
SaaS account service
support case creation

const connectorActions = {
  "email.send": async ({
    input,
    idempotencyKey,
  }) => {
    return emailProvider.send({
      to: input.to,
      subject: input.subject,
      html: input.html,
      idempotencyKey,
    });
  },

  "telegram.send_message": async ({
    input,
  }) => {
    return telegramClient.sendMessage({
      chatId: input.chatId,
      text: input.message,
    });
  },

  "license.assign": async ({
    input,
    idempotencyKey,
  }) => {
    return licenseService.assign({
      productId: input.productId,
      orderId: input.orderId,
      customerEmail:
        input.customerEmail,
      idempotencyKey,
    });
  },

  "http.request": async ({
    input,
    idempotencyKey,
  }) => {
    return controlledHttpClient.request({
      url: input.url,
      method: input.method ?? "POST",
      headers: {
        ...input.headers,
        "Idempotency-Key":
          idempotencyKey,
      },
      body: input.body,
    });
  },
};

Connectors should reference stored credential IDs.

Do not embed secrets inside workflow definitions.

Protect the generic HTTP connector

A generic HTTP action can become an SSRF and secret-exfiltration tool.

Restrict:

protocols other than HTTPS
loopback addresses
private IP ranges
cloud metadata endpoints
link-local addresses
DNS rebinding
excessive redirects
large response bodies
long timeouts
merchant-controlled authorization headers
secrets in URLs
unapproved destination domains

A safer first version can require merchants to allowlist destination domains.

function assertAllowedDestination(url) {
  const parsed = new URL(url);

  if (parsed.protocol !== "https:") {
    throw new PermanentWorkflowError(
      "Only HTTPS destinations are allowed",
    );
  }

  if (
    !destinationAllowlist.has(
      parsed.hostname,
    )
  ) {
    throw new PermanentWorkflowError(
      "Destination is not allowlisted",
    );
  }
}

Run connector workers in a restricted network environment when possible.

Distinguish transient and permanent failures

Not every error should be retried.

Transient failures

Examples:

HTTP 429
temporary network timeout
provider 502 or 503
email service unavailable
CRM rate limit
database interruption

Recommended action:

Retry with backoff

Permanent failures

Examples:

order does not exist
customer email is missing
payment is not paid
amount does not match
connector credential is invalid
access plan no longer exists
destination is blocked
workflow input cannot be rendered

Recommended action:

Stop retrying
Create operational case

Ambiguous failures

Examples:

external action may have completed, but the response was lost
timeout occurred after request transmission
downstream system accepted work but did not return an operation ID

Recommended action:

Reconcile the outcome
Do not blindly retry

class TransientWorkflowError extends Error {}
class PermanentWorkflowError extends Error {}
class AmbiguousWorkflowError extends Error {}

Ambiguous failures require a stricter policy because repeating the action may duplicate fulfillment.

Use controlled retry policies

A retry policy may use exponential backoff:

Attempt 1: immediately
Attempt 2: after 30 seconds
Attempt 3: after 2 minutes
Attempt 4: after 10 minutes
Attempt 5: after 30 minutes

After the final retry:

Action: failed
Workflow: needs_attention
Merchant: notified
Operational case: created

The dashboard should show:

attempt count
last error
next retry time
error classification
completed dependencies
whether manual retry is safe
whether outcome reconciliation is required

Do not restart the entire workflow when one action fails.

Resume from the failed action when the workflow semantics allow it.

Preserve partial success

Consider:

License assigned: yes
Order updated: yes
Delivery email sent: no
CRM updated: yes

The workflow is not completely successful.

It is also not completely failed.

Represent this as:

Workflow status: partially_completed
Failed action: send_delivery
Completed actions:
- assign_license
- update_order
- update_crm

Retry only the email.

Do not assign another license.

A single automation_status = failed field cannot represent this safely.

Add approval gates for sensitive actions

Some actions should not execute automatically.

Examples:

issue refund
create payout
change customer balance
revoke long-term access
disable merchant account
send high-value credit
call a sensitive internal administrative API

A workflow can pause before the action:

- id: create_refund
  type: oxapay.refund_review
  approval:
    required: true
    role: finance_admin
    expires_after_minutes: 1440
  input:
    track_id: "{{ event.data.track_id }}"

The approval request should freeze:

workflow version
rendered action input
destination
amount
currency
reason
prior action results

Calculate a snapshot hash.

If any important field changes, invalidate the approval.

Do not let someone approve one action and execute a modified version later.

Keep payout automation outside the first MVP

Payment-triggered payouts have a larger blast radius than email or fulfillment actions.

Payout automation requires:

separate Payout API Key
verified destinations
limits
approval policy
immutable ledger
payout reconciliation
ambiguous-dispatch handling
additional audit logs

The Crypto Revenue Split and Payout System covers that architecture.

The Automation Studio can create an approved payout request in another system.

It should not send money automatically unless the product has been designed specifically for that responsibility.

Support safe replay

Replay is useful when:

a connector was unavailable
credentials were corrected
a workflow bug was fixed
a missed event was recovered
an execution was interrupted
outcome verification failed

Replay must not mean:

Run the whole workflow again

A replay operation should:

Load the original event.
Load the selected workflow version.
Inspect completed action records.
Reuse completed idempotent results.
Reconcile ambiguous actions.
Retry only eligible actions.
create a replay audit record.

The operator may choose:

Replay with original workflow version

or:

Replay with current published version

These options have different consequences.

The choice must be visible in the execution history.

Recover missed events with Payment History

Webhooks provide the real-time path.

They should not be the only path.

Callbacks may be missed because of:

server downtime
deployment errors
invalid callback responses
queue failures
database outages
incorrect endpoint configuration

Use OxaPay Payment History for recovery.

A practical schedule:

Every 10 minutes:
- query an overlapping recent period
- upsert provider records by track_id
- compare provider and local status
- create recovery events
- enqueue workflows that never started

Every night:
- compare paid payments with completed workflows
- identify paid payments with incomplete outcomes
- generate unresolved-case report

A recovered event should use:

source = payment_history_backfill

Do not make it appear as if the original webhook arrived.

The source of evidence matters during incident investigation.

A complete first workflow

The strongest first use case is software-license delivery.

Customer creates order
-> Merchant creates OxaPay invoice
-> Customer pays
-> OxaPay sends payment update
-> Studio validates callback
-> Event is stored
-> Paid transition is deduplicated
-> Published workflow matches
-> Payment Information is refreshed
-> Order ID and amount are verified
-> License is assigned idempotently
-> License assignment is verified
-> Delivery email is sent
-> Merchant is notified
-> Execution is recorded

Failure paths:

Payment is not paid
-> Do not deliver

Order not found
-> Create review case

Amount mismatch
-> Stop workflow
-> Create high-severity case

License service unavailable
-> Retry

License request timed out ambiguously
-> Check existing license assignment
-> Do not blindly assign again

Email unavailable
-> Keep assigned license
-> Retry only email

Retries exhausted
-> Notify merchant
-> Create support case

This workflow contains the core reliability problems the product must solve.

Low-code implementation with n8n or Make

A full SaaS platform is not the only starting path.

OxaPay provides an official n8n integration with operations for:

invoice generation
white-label payments
static addresses
Payment Information
payment search
payment webhook triggers
payout operations
common account operations
swaps

A practical n8n workflow can look like:

OxaPay Trigger
-> Filter status = paid
-> Get Payment Information
-> Query merchant order API
-> Verify order and amount
-> Deliver product
-> Send Telegram notification
-> Store execution result

OxaPay is also available through Make with modules for payment generation, payment lookup, searches, webhook watchers, payouts, static addresses, and other operations.

Low-code tools are useful for:

validating merchant demand
building managed workflows
testing connector requirements
serving lower-volume merchants
learning which workflow templates repeat

They do not automatically provide:

action-level idempotency
historical workflow versions
tenant isolation
approval snapshots
loop prevention
outcome verification
recovery guarantees
merchant-specific replay controls

Low-code orchestration does not remove payment-engineering responsibilities.

The execution dashboard

The dashboard should answer:

Did the event arrive?

Was it authentic?

Which workflow matched?

Which version ran?

Which actions completed?

What failed?

What requires approval?

What requires manual review?

Was the final outcome verified?

Event inbox

Show:

provider
track_id
order ID
payment status
source
HMAC validity
correlation ID
received time
matched workflows

Workflow executions

Show:

workflow name
workflow version
trigger event
execution status
start and completion time
completed actions
failed action
pending approval
retry state
replay history

Action details

Show:

action type
rendered input
masked credential
masked destination
attempt history
response summary
outcome verification
idempotency key
manual retry eligibility

Needs attention

Show:

paid payment without completed fulfillment
exhausted retries
permanent connector errors
ambiguous outcomes
missing order mapping
invalid credentials
recovered events
approval requests
possible workflow loops

Operational health

Track:

webhook acceptance rate
invalid HMAC rate
event-to-execution latency
first-attempt action success rate
retry rate
ambiguous-outcome rate
median time from paid to verified outcome
paid payments with incomplete workflows
oldest unresolved execution
duplicate events safely ignored

The product should surface failures before the customer reports them.

The MVP

Do not build Zapier for every crypto merchant.

Choose one niche and three workflows.

For a digital product seller:

Workflow one

Paid invoice
-> Verify order
-> Deliver product
-> Notify merchant

Workflow two

Expired invoice
-> Update order
-> Send safe customer message
-> Notify support for high-value orders

Workflow three

Payment History recovery
-> Find paid payment
-> Detect incomplete delivery
-> Create operational case

Start with four connectors:

internal HTTP API
email
Telegram
Google Sheets or CSV export

The first product should include:

event inbox
workflow definitions
immutable published versions
dry run
payment-event ingestion
action execution
idempotency
retries
outcome verification
needs-attention queue
Payment History recovery
audit log

It does not need:

drag-and-drop workflow design
hundreds of connectors
AI-generated workflows
template marketplace
multi-provider routing
automated payouts
advanced business intelligence
arbitrary merchant code

Reliability is more valuable than connector count.

Productize the merchant outcome

Do not sell:

OxaPay webhook integration.

Sell:

Automatic digital delivery after confirmed crypto payment, with retries, logs, and recovery.

Or:

Crypto-paid SaaS activation with payment verification and paid-but-not-activated monitoring.

Or:

Payment-to-CRM automation for international service businesses.

The merchant buys a business outcome.

The API, queue, workflow engine, and connector code are implementation details.

A practical commercial model may combine:

implementation fee
reusable workflow template
monthly monitoring
connector maintenance
execution dashboard
incident support
custom workflow changes

The recurring value comes from maintaining a business-critical workflow, not merely writing the original integration.

Security boundaries

A Payment Automation Studio stores credentials and executes merchant-authorized actions.

Minimum safeguards include:

HTTPS-only callback endpoints
HMAC validation over raw request bodies
encrypted Merchant API Keys
encrypted connector credentials
tenant-isolated storage
secrets excluded from logs
masked execution inputs and outputs
restricted expression language
workflow publish permissions
approval roles
audit logs for edits, publishing, replay, and approval
connector credential rotation
outbound request restrictions
rate limits
body-size limits
separate staging and production credentials
dead-letter handling
backup and restoration testing
operational alerting

The execution system should fail closed.

When payment evidence or action outcome is uncertain, stop and review.

Production tests

Test at least:

Invalid HMAC changes no business state

Duplicate raw webhook creates one stored event

Different paid payloads create one paid transition

Paying does not trigger fulfillment

Paid triggers one workflow execution

Duplicate queue job creates no duplicate action

Two workers cannot claim the same action simultaneously

Duplicate action attempt assigns one license

Ambiguous license timeout is reconciled before retry

Workflow version remains attached to historical execution

Draft workflow processes no live events

Historical simulation performs no external action

Dependency cycle blocks workflow publishing

Generic HTTP connector rejects private network destinations

Permanent error creates no automatic retry

Transient error follows retry policy

Partial success preserves completed actions

Approval applies to an immutable action snapshot

Causation-depth limit prevents workflow loop

Replay does not rerun completed irreversible actions

Payment History recovers a missed paid event

Paid payment without verified outcome creates a case

These tests are part of the product.

They are not optional engineering polish.

Common mistakes

Executing actions inside the webhook request

Persist first.

Execute asynchronously.

Promising exactly-once delivery

Distributed systems retry.

Build effectively-once business execution through idempotency and reconciliation.

Deduplicating events but not transitions

Different payloads may represent the same paid transition.

Deduplicating transitions but not actions

One transition may still execute an irreversible action twice.

Editing published workflows

Create a new immutable version instead.

Publishing without simulation

Test workflows against historical events before sending them to production.

Retrying every timeout

Some timeouts have ambiguous outcomes.

Reconcile before repeating an irreversible action.

Replaying the whole workflow

Reuse completed action results and replay only eligible work.

Allowing arbitrary code in conditions

Use a restricted expression language.

Ignoring automation loops

Track causation and enforce a maximum chain depth.

Hiding partial success

Record each action independently.

Treating API acceptance as business completion

Verify the final outcome.

Automating payouts too early

Use dedicated ledger, approval, destination, and reconciliation controls.

What makes this a real product?

A webhook script says:

If payment is paid, send an email.

A Payment Automation Studio says:

Receive callback
-> validate origin
-> preserve evidence
-> normalize event
-> deduplicate business transition
-> select immutable workflow version
-> evaluate restricted conditions
-> plan action dependencies
-> verify payment state
-> claim actions safely
-> execute idempotently
-> verify business outcomes
-> retry temporary failures
-> reconcile ambiguous outcomes
-> pause for approvals
-> recover missed events
-> prevent automation loops
-> show the merchant exactly what happened

That is the difference between connecting an API and operating a merchant workflow.

Final takeaway

The business opportunity is not simply accepting crypto payments.

It is controlling what happens after those payments.

Merchants need payment events to activate products, update systems, notify teams, create records, and handle failures without operational chaos.

OxaPay provides the payment primitives:

invoice generation
unique track_id references
merchant order_id references
payment callbacks
HMAC verification
Payment Information
Payment History
white-label payments
static addresses
SDKs
n8n and Make integrations

The Automation Studio provides the execution layer:

verified event ingestion
workflow definitions
immutable versions
safe conditions
action dependencies
idempotency
retries
approvals
replay
recovery
loop prevention
outcome verification
operational visibility

Start with one workflow:

Confirmed payment
-> Verified order
-> Idempotent delivery
-> Verified outcome

Then add simulation, retries, recovery, approvals, connectors, and monitoring.

Do not begin by building a large automation marketplace.

Build one payment-driven workflow that a merchant can trust with a real customer order.

That is where an automation script becomes payment infrastructure.

Which workflow would you build first: digital delivery, SaaS activation, paid community access, or merchant reporting?

References

OxaPay payment infrastructure

OxaPay automation integrations

Build a Crypto Payment Reconciliation Tool for Merchants

kevin.s — Wed, 15 Jul 2026 10:36:38 +0000

A merchant's payment provider reports a payment as paid.

The ecommerce system still shows the order as pending.

The customer has not received the product. Support is reviewing a screenshot, finance has a transaction in its export, and the developer is searching through webhook logs.

Every system contains part of the truth.

None of them agrees on what happened.

This is a reconciliation problem.

A crypto payment reconciliation tool compares provider-side payments with merchant-side orders, fulfillment records, and financial data. It detects mismatches, turns them into actionable cases, and gives the merchant a controlled way to resolve them.

This article uses OxaPay as the implementation reference, but the architecture is provider-agnostic. The same model applies whenever a business must connect asynchronous payment events to internal business records.

What payment reconciliation actually means

Reconciliation is not the same as displaying payment history.

A payment dashboard answers:

What payments did the provider record?

A reconciliation system answers:

Do the payment provider, order system, fulfillment system, and finance records describe the same business outcome?

For every order, the system should be able to prove:

which payment session belongs to it
whether the provider confirmed the payment
whether the expected amount was received
whether fulfillment happened
whether the financial record was exported
whether any mismatch still requires attention

A useful reconciliation model compares four states:

Provider payment state
Merchant order state
Fulfillment state
Finance state

For example:

Provider payment: paid
Order: pending
Fulfillment: not_started
Finance export: included

The payment exists, but the merchant workflow is incomplete.

Another example:

Provider payment: waiting
Order: paid
Fulfillment: completed
Finance export: included

This is more serious. The merchant may have delivered a product before receiving a confirmed payment.

The reconciliation tool exists to find these disagreements.

Reconciliation is one part of PaymentOps

A broader Crypto PaymentOps service manages the full operational payment lifecycle.

It may include:

payment creation
webhook ingestion
state management
fulfillment
alerts
support visibility
reporting
reconciliation

The reconciliation tool has a narrower responsibility.

It must:

Collect records from every relevant system.
Normalize those records.
Match related records.
compare their states.
Detect violations.
Create a case when the system cannot safely repair the mismatch.
preserve an audit trail of the resolution.

This distinction matters.

The reconciliation tool should not become another general merchant dashboard. Its core product is the exception queue.

The invariant behind the system

Before writing code, define the business rules that must always remain true.

Useful invariants include:

Every confirmed provider payment must map to a known merchant record.

Every fulfilled order must have an approved payment state.

Every paid order must either be fulfilled or have an open fulfillment case.

Every provider refund must be reflected in the merchant's access or order state.

Every manual resolution must have an audit record.

These invariants are more useful than asking whether a single status field is correct.

The reconciliation engine continuously tests them.

When an invariant fails, the system either repairs the state safely or creates a case for human review.

The three data sources

A production reconciliation tool should not depend on one event stream.

It needs at least three sources.

Merchant records

These include:

orders
customers
expected amounts
expected currencies
fulfillment status
subscription or access status
finance export status

Provider records

With OxaPay, relevant provider-side data can come from:

invoice creation responses
webhook payloads
Payment Information
Payment History
static address payment records

Operational records

These explain what the merchant's own system did:

webhook ingestion logs
state transitions
fulfillment jobs
retry attempts
manual overrides
support notes
exports

The reconciliation layer stores normalized references to all three sources.

Recommended architecture

Merchant Store / SaaS / Bot
          |
          | Orders and fulfillment records
          v
+-----------------------------+
| Reconciliation Database     |
+-----------------------------+
          ^
          |
          | Webhook events
          |
OxaPay Webhook Receiver
          ^
          |
          | Payment changes
          |
       OxaPay
          |
          | Payment Information / History
          v
Scheduled Provider Sync
          |
          v
+-----------------------------+
| Matching Engine             |
+-----------------------------+
          |
          v
+-----------------------------+
| Reconciliation Rules        |
+-----------------------------+
          |
          +--------------------+
          |                    |
          v                    v
 Automatic Repair       Exception Queue
                               |
                               v
                      Support / Operations

Webhook events provide the real-time path.

Scheduled API queries provide the recovery path.

Merchant imports provide the business-side truth.

The reconciliation engine compares them instead of assuming that any single source is always complete.

Build a normalized data model

Do not compare raw API responses directly with ecommerce database rows.

Create a normalized model between them.

CREATE TABLE merchant_orders (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL,
  external_order_id TEXT NOT NULL,
  customer_email TEXT,
  expected_amount NUMERIC(18, 8) NOT NULL,
  expected_currency TEXT NOT NULL,
  order_status TEXT NOT NULL,
  fulfillment_status TEXT NOT NULL DEFAULT 'not_started',
  finance_status TEXT NOT NULL DEFAULT 'not_exported',
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (merchant_id, external_order_id)
);

CREATE TABLE payment_sessions (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL,
  order_id UUID REFERENCES merchant_orders(id),
  provider TEXT NOT NULL DEFAULT 'oxapay',
  provider_track_id TEXT NOT NULL,
  provider_status TEXT NOT NULL,
  internal_status TEXT NOT NULL,
  requested_amount NUMERIC(18, 8),
  requested_currency TEXT,
  paid_amount NUMERIC(18, 8),
  paid_currency TEXT,
  expires_at TIMESTAMP,
  last_verified_at TIMESTAMP,
  raw_provider_record JSONB,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (merchant_id, provider, provider_track_id)
);

CREATE TABLE payment_transactions (
  id UUID PRIMARY KEY,
  payment_session_id UUID NOT NULL REFERENCES payment_sessions(id),
  transaction_hash TEXT,
  amount NUMERIC(18, 8),
  currency TEXT,
  network TEXT,
  address TEXT,
  confirmations INTEGER,
  raw_transaction JSONB,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (payment_session_id, transaction_hash)
);

CREATE TABLE payment_events (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL,
  provider TEXT NOT NULL DEFAULT 'oxapay',
  provider_track_id TEXT,
  payload_hash TEXT NOT NULL,
  event_status TEXT,
  hmac_valid BOOLEAN NOT NULL,
  raw_payload JSONB NOT NULL,
  received_at TIMESTAMP NOT NULL DEFAULT NOW(),
  processed_at TIMESTAMP,
  UNIQUE (merchant_id, payload_hash)
);

CREATE TABLE reconciliation_cases (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL,
  order_id UUID REFERENCES merchant_orders(id),
  payment_session_id UUID REFERENCES payment_sessions(id),
  case_key TEXT NOT NULL,
  case_type TEXT NOT NULL,
  severity TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'open',
  summary TEXT NOT NULL,
  recommended_action TEXT,
  evidence JSONB,
  assigned_to TEXT,
  resolution_type TEXT,
  resolution_note TEXT,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  resolved_at TIMESTAMP,
  UNIQUE (merchant_id, case_key)
);

The important separation is:

merchant_orders
payment_sessions
payment_transactions
payment_events
reconciliation_cases

An order is not a payment.

A payment session is not necessarily a blockchain transaction.

A payment event is not the current state.

A reconciliation case is not the same as an application error.

Each entity describes a different part of the operational history.

Normalize provider statuses

OxaPay documents payment statuses including:

new
waiting
paying
paid
manual_accept
underpaid
refunding
refunded
expired

Your internal model can map them into operational categories.

OxaPay status	Internal state	Reconciliation meaning
`new`	`created`	Payment session exists
`waiting`	`awaiting_payment`	Waiting for the customer's transfer
`paying`	`confirming`	Payment activity exists, but fulfillment is not yet approved
`paid`	`paid_confirmed`	Payment can satisfy the order
`manual_accept`	`manually_accepted`	Merchant approval requires an audit record
`underpaid`	`underpaid_review`	Amount requires a merchant decision
`expired`	`expired`	Payment session closed without normal completion
`refunding`	`refund_in_progress`	Refund workflow is active
`refunded`	`refunded`	Order, access, and finance state may need reversal

A simple mapper:

const STATUS_MAP = {
  new: "created",
  waiting: "awaiting_payment",
  paying: "confirming",
  paid: "paid_confirmed",
  manual_accept: "manually_accepted",
  underpaid: "underpaid_review",
  expired: "expired",
  refunding: "refund_in_progress",
  refunded: "refunded",
};

function normalizeProviderStatus(status) {
  return String(status ?? "").trim().toLowerCase();
}

function mapProviderStatus(status) {
  const normalized = normalizeProviderStatus(status);
  return STATUS_MAP[normalized] ?? "unknown";
}

Do not trigger fulfillment from paying.

The paid state is the normal state for approved fulfillment. A manually accepted payment should follow a separate merchant policy and preserve who approved it.

Match payments to orders

Matching is the core technical problem.

The strongest design prevents ambiguity before payment creation.

When creating an OxaPay invoice, send the merchant's internal order identifier as order_id and store the returned track_id immediately.

That creates a direct relationship:

Merchant order ID <-> OxaPay track_id

Real systems still need fallback logic because records may be imported, created manually, or received through static addresses.

Use ordered matching rules.

Recommended matching priority

Existing local relationship by track_id
Exact provider order_id
Exact external order ID stored in metadata
Customer email, amount, currency, and narrow time window
Customer-specific static address assignment
Transaction hash supplied by support
Manual review

Do not silently accept a weak match.

Return both the result and its confidence.

async function findOrderMatch({ merchantId, payment }) {
  const linkedSession = await db.paymentSession.findUnique({
    where: {
      merchantId_provider_providerTrackId: {
        merchantId,
        provider: "oxapay",
        providerTrackId: String(payment.track_id),
      },
    },
    include: {
      order: true,
    },
  });

  if (linkedSession?.order) {
    return {
      order: linkedSession.order,
      confidence: "exact",
      reason: "stored_track_id_link",
    };
  }

  if (payment.order_id) {
    const order = await db.merchantOrder.findUnique({
      where: {
        merchantId_externalOrderId: {
          merchantId,
          externalOrderId: String(payment.order_id),
        },
      },
    });

    if (order) {
      return {
        order,
        confidence: "exact",
        reason: "provider_order_id",
      };
    }
  }

  if (payment.email && payment.amount && payment.currency) {
    const createdAt = new Date(payment.created_at ?? Date.now());
    const windowStart = new Date(createdAt.getTime() - 60 * 60 * 1000);
    const windowEnd = new Date(createdAt.getTime() + 60 * 60 * 1000);

    const candidates = await db.merchantOrder.findMany({
      where: {
        merchantId,
        customerEmail: payment.email,
        expectedAmount: payment.amount,
        expectedCurrency: payment.currency,
        createdAt: {
          gte: windowStart,
          lte: windowEnd,
        },
      },
    });

    if (candidates.length === 1) {
      return {
        order: candidates[0],
        confidence: "probable",
        reason: "email_amount_currency_time",
      };
    }

    if (candidates.length > 1) {
      return {
        order: null,
        confidence: "ambiguous",
        reason: "multiple_candidate_orders",
        candidates,
      };
    }
  }

  return {
    order: null,
    confidence: "none",
    reason: "no_safe_match",
  };
}

A probable match may be useful for suggesting an order to the support agent.

It should not automatically trigger fulfillment unless the merchant has explicitly accepted that risk.

Define reconciliation rules

The engine should test explicit rules instead of relying on one large conditional function.

A rule receives normalized records and returns either:

no mismatch
automatic repair
reconciliation case

Here are the most important rules.

Paid payment without an order

Provider: paid
Order: missing

Possible causes:

missing order_id
failed local write after invoice creation
imported payment
incorrect merchant tenant
static address deposit
deleted order

Recommended action:

Search by order ID, email, amount, address, time, and transaction hash. Do not fulfill until a safe match exists.

Paid order not fulfilled

Provider: paid
Order: paid
Fulfillment: failed or not_started

The customer has paid, but the merchant still owes the product or service.

This should normally be a high-severity case.

Fulfilled order without confirmed payment

Provider: new, waiting, paying, expired, or unknown
Fulfillment: completed

This can indicate:

fulfillment triggered too early
manual override
stale local status
incorrect order mapping
automation bug

This should normally be critical.

Provider paid, local order pending

Provider: paid
Order: pending

This may be safe to repair automatically when:

the payment-to-order relationship is exact
the amount and currency satisfy the order
no refund state exists
no conflicting payment session exists

Underpaid payment

Provider: underpaid
Order: pending

The system should create a review case containing:

requested amount
paid amount
difference
currency
payment age
merchant policy

The merchant may request the remaining amount, manually accept the payment, or cancel the order.

Refunded payment with active access

Provider: refunded
Subscription or access: active

The correct action depends on the merchant's refund and access policy.

Do not revoke access silently unless that policy is defined.

Finance mismatch

Provider payment: paid
Order: paid
Finance export: missing

The payment operation succeeded, but the reporting process is incomplete.

This usually has lower immediate severity than failed fulfillment, but it matters for daily and monthly closing.

Implement the reconciliation evaluator

A focused evaluator can produce cases from one normalized record set.

function evaluateReconciliation({
  payment,
  order,
  fulfillment,
  finance,
}) {
  const findings = [];

  if (payment.internalStatus === "paid_confirmed" && !order) {
    findings.push({
      type: "paid_payment_without_order",
      severity: "high",
      summary: "A confirmed payment has no matching merchant order.",
      recommendedAction:
        "Review order_id, customer email, amount, time, address, and transaction hash.",
    });

    return findings;
  }

  if (!order) {
    return findings;
  }

  if (
    payment.internalStatus === "paid_confirmed" &&
    order.paymentStatus !== "paid"
  ) {
    findings.push({
      type: "provider_paid_local_pending",
      severity: "high",
      summary: `Provider reports payment for order ${order.externalOrderId} as paid, but the local order remains pending.`,
      recommendedAction:
        "Verify the exact order match and update local state if no conflicting payment exists.",
    });
  }

  if (
    payment.internalStatus === "paid_confirmed" &&
    fulfillment.status !== "completed"
  ) {
    findings.push({
      type: "paid_not_fulfilled",
      severity: "high",
      summary: `Order ${order.externalOrderId} is paid but not fulfilled.`,
      recommendedAction:
        "Inspect the fulfillment job and retry it idempotently.",
    });
  }

  if (
    fulfillment.status === "completed" &&
    !["paid_confirmed", "manually_accepted"].includes(
      payment.internalStatus,
    )
  ) {
    findings.push({
      type: "fulfilled_without_approved_payment",
      severity: "critical",
      summary: `Order ${order.externalOrderId} was fulfilled without an approved payment state.`,
      recommendedAction:
        "Review the fulfillment trigger, payment mapping, and manual overrides.",
    });
  }

  if (payment.internalStatus === "underpaid_review") {
    findings.push({
      type: "underpaid_payment",
      severity: "medium",
      summary: `Payment for order ${order.externalOrderId} is underpaid.`,
      recommendedAction:
        "Apply the merchant policy for remaining payment, manual acceptance, or cancellation.",
    });
  }

  if (
    payment.internalStatus === "refunded" &&
    fulfillment.accessStatus === "active"
  ) {
    findings.push({
      type: "refunded_but_access_active",
      severity: "high",
      summary: `Order ${order.externalOrderId} was refunded, but customer access remains active.`,
      recommendedAction:
        "Apply the merchant's refund and access revocation policy.",
    });
  }

  if (
    payment.internalStatus === "paid_confirmed" &&
    finance.status !== "exported"
  ) {
    findings.push({
      type: "paid_not_exported",
      severity: "low",
      summary: `Paid order ${order.externalOrderId} is missing from the finance export.`,
      recommendedAction:
        "Include the record in the next export or inspect the export job.",
    });
  }

  return findings;
}

Each finding should become a deduplicated case.

Prevent duplicate cases

A reconciliation job may run every few minutes.

Without case deduplication, the dashboard could create hundreds of identical open cases.

Generate a stable case key.

import crypto from "node:crypto";

function createCaseKey({
  merchantId,
  type,
  orderId,
  paymentSessionId,
}) {
  return crypto
    .createHash("sha256")
    .update(
      [
        merchantId,
        type,
        orderId ?? "no-order",
        paymentSessionId ?? "no-payment",
      ].join(":"),
    )
    .digest("hex");
}

Then upsert the case:

async function upsertReconciliationCase({
  merchantId,
  orderId,
  paymentSessionId,
  finding,
  evidence,
}) {
  const caseKey = createCaseKey({
    merchantId,
    type: finding.type,
    orderId,
    paymentSessionId,
  });

  return db.reconciliationCase.upsert({
    where: {
      merchantId_caseKey: {
        merchantId,
        caseKey,
      },
    },
    create: {
      merchantId,
      orderId,
      paymentSessionId,
      caseKey,
      caseType: finding.type,
      severity: finding.severity,
      status: "open",
      summary: finding.summary,
      recommendedAction: finding.recommendedAction,
      evidence,
    },
    update: {
      severity: finding.severity,
      summary: finding.summary,
      recommendedAction: finding.recommendedAction,
      evidence,
    },
  });
}

When the mismatch disappears, do not delete the case.

Mark it resolved and record whether the resolution was:

automatic
manual
caused by a corrected provider record
caused by a corrected merchant record
ignored under merchant policy

That audit history is part of the product.

Use webhooks for speed and API queries for recovery

Webhooks provide fast updates, but they should not be the only reconciliation source.

A callback may be missed because of:

server downtime
deployment failure
firewall configuration
invalid endpoint behavior
temporary database errors
application bugs

With OxaPay, the reconciliation worker can use:

Payment Information for a specific track_id
Payment History for periodic account-level backfill

A practical schedule might be:

Every 10 minutes:
- query recent provider payments
- upsert normalized payment records
- compare them with local orders
- create or resolve cases

Every night:
- reconcile the previous day
- verify paid totals
- find records missing from either side
- generate an operations report

At month-end:
- run a larger comparison window
- freeze the report inputs
- export unresolved exceptions separately

Use overlapping time windows.

For example, a job that runs at 12:00 should not query only records created after 11:50. Query a wider period and rely on idempotent upserts.

This protects the system from delayed records and temporary job failures.

Payment Information lookup

When the tool knows the track_id, it can retrieve the latest provider record directly.

async function fetchOxaPayPayment({
  merchantApiKey,
  trackId,
}) {
  const response = await fetch(
    `https://api.oxapay.com/v1/payment/${encodeURIComponent(trackId)}`,
    {
      method: "GET",
      headers: {
        merchant_api_key: merchantApiKey,
        "Content-Type": "application/json",
      },
    },
  );

  const payload = await response.json();

  if (!response.ok) {
    throw new Error(
      payload?.error?.message ??
        `Payment lookup failed with ${response.status}`,
    );
  }

  return payload.data;
}

Use this lookup when:

support investigates one payment
provider and local states disagree
a webhook references an unknown local record
an expired invoice has reported transaction activity
a case requires current evidence before manual resolution

Store the response and the verification time.

Do not overwrite earlier raw evidence. Reconciliation depends on understanding how the state changed.

Decide what can be repaired automatically

Not every mismatch requires a person.

Automatic repair is appropriate only when the evidence is strong and the action is reversible or already authorized.

A provider-paid, local-pending order may be repaired automatically when:

track_id relationship is exact
order_id matches
amount satisfies the order
currency matches policy
payment is not refunded
order is not already linked to another confirmed payment

A payment should normally require manual review when:

no exact order match exists
multiple orders are possible matches
the payment is underpaid
a manual acceptance is required
a refund conflicts with access state
the expected and paid currencies violate merchant policy
the same transaction appears against multiple records

The tool should explain why it selected automatic repair or manual review.

A silent state change is difficult to trust.

An auditable decision is a product feature.

Design the exception queue

The merchant does not need another page full of raw transactions.

The main screen should answer:

What requires attention now?

Useful columns include:

Field	Purpose
Severity	Prioritize operational risk
Case type	Explain the mismatch
Order ID	Connect to merchant workflow
Track ID	Connect to provider record
Customer	Help support investigate
Expected amount	Show the order requirement
Paid amount	Show provider evidence
Payment status	Show normalized provider state
Fulfillment status	Show delivery outcome
Case age	Surface unresolved problems
Recommended action	Tell the operator what to do
Assignee	Establish ownership

Useful filters include:

critical cases
paid but not fulfilled
fulfilled without payment
unmatched payments
underpaid payments
refund conflicts
finance export failures
cases older than one hour
manually resolved cases

Show an evidence timeline

A support agent should not reconstruct the incident from five systems.

Show one timeline.

10:03:12  Merchant order created
10:03:13  OxaPay invoice created
10:03:13  track_id linked to order
10:04:42  Webhook received: paying
10:05:11  Webhook received: paid
10:05:12  Payment session updated
10:05:12  Fulfillment job queued
10:05:18  Fulfillment failed
10:10:00  Reconciliation case created
10:12:41  Fulfillment retried
10:12:45  Product delivered
10:20:00  Reconciliation case resolved automatically

The timeline should distinguish:

provider evidence
merchant state changes
automated actions
manual actions
reconciliation decisions

This gives support a defensible answer when a customer asks what happened.

Static address reconciliation

Static address payments require different matching rules.

An invoice normally represents one expected payment for one order.

A static address may receive multiple payments over time and may represent:

a customer account
an internal balance
a deposit flow
a recurring B2B relationship

For static addresses, store:

address
network
currency
track_id
assigned customer or account
assignment date
active state
transaction hashes
credited balance records

Useful reconciliation checks include:

transaction received but account not credited
duplicate transaction hash
payment to an unassigned address
payment to an inactive address
credited amount different from received amount
payment assigned to the wrong customer
transaction stored without a finance record

Do not use static addresses as a shortcut when the merchant needs strict order-level matching.

Invoices are usually easier to reconcile for individual purchases.

What the MVP should include

A useful first version does not need advanced analytics or machine learning.

Build:

OxaPay payment session storage
webhook event ingestion
Payment Information lookup
scheduled Payment History sync
exact track_id and order_id matching
normalized payment states
five to eight reconciliation rules
deduplicated exception cases
evidence timeline
manual resolution notes
CSV export
daily unresolved-case summary

The MVP should answer:

Which confirmed payments have no order?

Which paid orders were not fulfilled?

Which fulfilled orders lack an approved payment?

Which payments are underpaid or ambiguous?

Which provider and local records disagree?

What action should the merchant take?

That is enough to solve a real operational problem.

Productize by merchant workflow

A generic reconciliation dashboard is difficult to explain.

A niche-specific result is easier to sell.

Digital product stores

Important cases:

paid but download not delivered
license key generation failed
duplicate license delivery
refund completed but license still active

Hosting providers

Important cases:

paid but service not provisioned
renewal paid but expiry date not extended
service activated before confirmed payment
refund completed but service still active

SaaS businesses

Important cases:

paid but subscription inactive
payment attached to the wrong account
duplicate subscription extension
refunded payment with active premium access

Paid communities

Important cases:

payment confirmed but role not granted
access granted without confirmed payment
renewal payment not applied
refunded member still has access

The reconciliation core remains similar.

The value comes from merchant-specific rules and recommended actions.

Production safeguards

A reconciliation product works with financial and operational evidence.

At minimum:

validate webhook HMAC signatures
preserve raw webhook bodies
process events idempotently
encrypt API keys
keep secrets out of logs
use unique transaction hash constraints
separate provider state from merchant state
record every manual resolution
restrict who can accept or override payments
run scheduled provider backfills
keep failed jobs in a dead-letter queue
log exports and administrative actions
define retention rules for raw payloads
test recovery after temporary outages

The tool should not silently hide uncertainty.

When evidence is incomplete, create a case.

What makes this a real product

A weak product says:

Here are your crypto payments.

A strong reconciliation product says:

Three provider payments have no matching orders.

Two paid orders were not fulfilled.

One order was fulfilled before payment reached an approved state.

Four payments are missing from today's finance export.

Here is the evidence and recommended action for each issue.

The value is not the number of API endpoints connected.

The value is the number of operational gaps detected and resolved before they become customer complaints or financial confusion.

Final takeaway

Crypto payment reconciliation is not a checkout feature.

It is a control system.

It compares provider payments, merchant orders, fulfillment activity, and finance records. It detects when those systems disagree and turns ambiguity into a visible, actionable case.

OxaPay provides the necessary payment primitives:

unique payment track_id values
merchant order_id references
webhook events
Payment Information
Payment History
documented payment statuses
static address records

The developer's job is to build the matching rules, reconciliation engine, exception queue, evidence timeline, and resolution workflow around those primitives.

Merchants do not need another transaction table.

They need to know:

which records agree
which records conflict
what created the mismatch
what can be repaired automatically
what requires a human decision
whether the customer received what they paid for

That is the difference between showing payment data and operating payments reliably.

References

Build a Crypto Revenue Split and Payout System for Merchants

kevin.s — Wed, 15 Jul 2026 10:36:34 +0000

A customer pays $100 for an online course.

The platform keeps $20.

The instructor earns $70.

An affiliate earns $10.

The calculation looks simple.

The operational system is not.

What happens when:

the payment webhook arrives twice
the split rule changes after the sale
the instructor updates their payout address
a refund occurs after earnings were created
the payout API times out after receiving the request
the payout is rejected
two workers create a payout for the same balance
the partner disputes the amount
finance asks why a balance changed three months later

A basic payment integration cannot answer those questions.

A Crypto Revenue Split and Payout System connects confirmed customer payments to explainable partner earnings and controlled outbound payouts.

The core flow is:

Confirmed payment
-> Immutable financial journal
-> Versioned revenue allocation
-> Pending or available earnings
-> Payout reservation
-> Approval
-> Provider payout
-> Confirmation or release
-> Reconciliation

This article uses OxaPay for payment and payout execution, but the architecture is provider-agnostic.

This article is part of 10 Crypto Payment Products Developers Can Build for Merchants.

The payout API is not the product

OxaPay can provide the infrastructure needed to:

create customer invoices
receive signed payment callbacks
retrieve Payment Information
search Payment History
create payout requests
retrieve Payout Information
search Payout History
receive signed payout callbacks

Your application still needs to decide:

which payment creates earnings
which split rule applies
which version of that rule applies
whether the allocation is based on gross or net revenue
when earnings become available
whether a reserve or holdback is required
which payout method is valid
who may approve a payout
when a rejected payout returns to the partner balance
how refunds and corrections are recorded
how every financial movement can be explained

OxaPay is the execution infrastructure.

The merchant product is the financial operations layer around it.

Payment, earnings, and payouts are different facts

Do not collapse the entire process into:

payment received
-> partner paid

A reliable model separates at least four concepts.

Customer payment

Evidence that money was received for an order.

Revenue allocation

The rule-based distribution of the allocable payment amount.

Partner payable

The amount the merchant currently owes a partner.

Provider payout

An instruction sent through OxaPay to move funds to a destination address.

These states can disagree temporarily.

Payment: paid
Partner earning: pending
Available balance: 0
Payout: none

Or:

Payment: paid
Partner earning: available
Payout: reserved
Provider status: confirming

Or:

Payment: refunded
Partner payout: already confirmed
Partner balance: negative
Operational case: open

Those are real operational states.

One balance column cannot model them safely.

Define the allocation basis

Before calculating a split, define which amount is being divided.

Possible bases include:

Gross order value

Customer order value: 100
Split basis: 100

Net received amount

Customer order value: 100
Provider and network costs: 1
Split basis: 99

Net amount after merchant deductions

Customer order value: 100
Provider costs: 1
Refund reserve: 5
Split basis: 94

There is no universal answer.

The merchant policy must define:

allocation_basis = gross_order_value

or:

allocation_basis = net_received

or another explicit model.

Do not calculate some sales using gross value and others using net value without storing that decision.

Every allocation should preserve:

original order amount
pricing currency
received asset
received amount
fee information when available
allocable amount
allocation currency
applied split-rule version
rounding policy

Use a double-entry journal

A simple table containing positive and negative partner amounts is better than an editable balance.

A balanced double-entry journal is stronger.

Each journal transaction contains lines whose total debits equal total credits in the same accounting unit.

For an allocable amount of 100 USDT:

Debit  Merchant funds control                 100 USDT

Credit Platform revenue                        20 USDT
Credit Partner payable: instructor             70 USDT
Credit Partner payable: affiliate              10 USDT

The journal answers:

Where did the value come from?

Who owns the value now?

Which payment created it?

Which rule determined it?

When an instructor payout of 70 USDT is reserved:

Debit  Partner payable: instructor             70 USDT
Credit Payouts in transit: instructor           70 USDT

When the payout is confirmed:

Debit  Payouts in transit: instructor           70 USDT
Credit Merchant funds control                   70 USDT

If the payout is rejected:

Debit  Payouts in transit: instructor           70 USDT
Credit Partner payable: instructor              70 USDT

The rejected payout returns to the payable balance through a new journal transaction.

Nothing is deleted or rewritten.

The core invariants

Define these rules before building the dashboard.

One provider payment is recognized at most once.

Every journal transaction is balanced.

Every allocation references an immutable split-rule version.

Past journal entries cannot be edited or deleted.

Corrections use reversal or adjustment transactions.

Pending earnings cannot be paid.

Reserved earnings cannot be reserved again.

Every payout item references one verified payout-method version.

Approval applies to an immutable payout snapshot.

A confirmed payout creates one settlement journal transaction.

A rejected or canceled payout releases one reservation.

Payment and payout webhooks use different API keys.

A network timeout during payout dispatch is not automatically treated as failure.

Every manual financial action records actor, time, reason, and evidence.

These invariants are the real product specification.

The architecture

+----------------------+
| Customer Checkout    |
+----------+-----------+
           |
           | Create order and invoice
           v
+----------------------+
| OxaPay Payment API   |
+----------+-----------+
           |
           | Signed payment callback
           v
+----------------------+
| Payment Webhook      |
+----------+-----------+
           |
           | Verify and persist
           v
+----------------------+
| Event Store + Outbox |
+----------+-----------+
           |
           v
+----------------------+
| Payment Worker       |
+----------+-----------+
           |
           | Verify Payment Information
           v
+----------------------+
| Ledger + Split Engine|
+----------+-----------+
           |
           | Pending / available earnings
           v
+----------------------+
| Payout Scheduler     |
+----------+-----------+
           |
           | Reserve balances
           v
+----------------------+
| Approval Workflow    |
+----------+-----------+
           |
           | Approved payout instruction
           v
+----------------------+
| OxaPay Payout API    |
+----------+-----------+
           |
           | Signed payout callback
           v
+----------------------+
| Payout Reconciliation|
+----------+-----------+
           |
           v
Partner Dashboard / Finance / Support

Payment recognition and payout execution should be separate services or processing stages.

Do not call the Payout API from the payment webhook.

OxaPay primitives used

Generate Invoice

Create the customer-facing payment session:

POST https://api.oxapay.com/v1/payment/invoice

Authenticate with:

merchant_api_key

Payment Information

Verify one payment by track_id:

GET https://api.oxapay.com/v1/payment/{track_id}

Payment History

Recover and reconcile incoming payments:

GET https://api.oxapay.com/v1/payment

Generate Payout

Create an outbound payout request:

POST https://api.oxapay.com/v1/payout

Authenticate with:

payout_api_key

Payout Information

Retrieve one payout:

GET https://api.oxapay.com/v1/payout/{track_id}

Payout History

Recover and reconcile outbound payouts:

GET https://api.oxapay.com/v1/payout

Webhooks

Payment callbacks are verified using the Merchant API Key.

Payout callbacks are verified using the Payout API Key.

Both use HMAC SHA-512 over the raw request body and send the signature in the HMAC header.

Keep payment and payout callback routes separate.

A financial data model

CREATE TABLE merchants (
  id UUID PRIMARY KEY,
  name TEXT NOT NULL,
  accounting_currency TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'active',
  created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE TABLE partners (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  partner_type TEXT NOT NULL,
  display_name TEXT NOT NULL,
  email TEXT,
  status TEXT NOT NULL DEFAULT 'active',
  payout_blocked BOOLEAN NOT NULL DEFAULT FALSE,
  created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE TABLE payout_method_versions (
  id UUID PRIMARY KEY,
  partner_id UUID NOT NULL REFERENCES partners(id),
  version INTEGER NOT NULL,
  currency TEXT NOT NULL,
  network TEXT,
  address TEXT NOT NULL,
  memo TEXT,
  status TEXT NOT NULL DEFAULT 'pending_verification',
  created_by UUID,
  verified_by UUID,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  verified_at TIMESTAMP,
  disabled_at TIMESTAMP,
  UNIQUE (partner_id, version)
);

CREATE TABLE split_rules (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  name TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'active',
  created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE TABLE split_rule_versions (
  id UUID PRIMARY KEY,
  split_rule_id UUID NOT NULL REFERENCES split_rules(id),
  version INTEGER NOT NULL,
  allocation_basis TEXT NOT NULL,
  config JSONB NOT NULL,
  effective_from TIMESTAMP NOT NULL,
  effective_until TIMESTAMP,
  created_by UUID,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (split_rule_id, version)
);

CREATE TABLE orders (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  external_order_id TEXT NOT NULL,
  split_rule_version_id UUID NOT NULL
    REFERENCES split_rule_versions(id),
  order_amount NUMERIC(36, 18) NOT NULL,
  pricing_currency TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'created',
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (merchant_id, external_order_id)
);

CREATE TABLE payments (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  order_id UUID NOT NULL REFERENCES orders(id),
  provider TEXT NOT NULL DEFAULT 'oxapay',
  provider_track_id TEXT NOT NULL,
  provider_status TEXT NOT NULL,
  internal_status TEXT NOT NULL,
  requested_amount NUMERIC(36, 18) NOT NULL,
  received_amount NUMERIC(36, 18),
  received_currency TEXT,
  network TEXT,
  paid_at TIMESTAMP,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (provider, provider_track_id)
);

CREATE TABLE provider_events (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  event_type TEXT NOT NULL,
  provider_track_id TEXT,
  payload_hash TEXT NOT NULL,
  signature_valid BOOLEAN NOT NULL,
  raw_payload JSONB NOT NULL,
  source TEXT NOT NULL,
  received_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (merchant_id, event_type, payload_hash)
);

CREATE TABLE journal_transactions (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  business_key TEXT NOT NULL,
  transaction_type TEXT NOT NULL,
  reference_type TEXT NOT NULL,
  reference_id UUID NOT NULL,
  currency TEXT NOT NULL,
  description TEXT,
  metadata JSONB,
  posted_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (merchant_id, business_key)
);

CREATE TABLE journal_lines (
  id UUID PRIMARY KEY,
  journal_transaction_id UUID NOT NULL
    REFERENCES journal_transactions(id),
  account_code TEXT NOT NULL,
  partner_id UUID REFERENCES partners(id),
  side TEXT NOT NULL CHECK (side IN ('debit', 'credit')),
  amount NUMERIC(36, 18) NOT NULL CHECK (amount > 0),
  metadata JSONB,
  created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE TABLE earning_allocations (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  payment_id UUID NOT NULL REFERENCES payments(id),
  partner_id UUID REFERENCES partners(id),
  split_rule_version_id UUID NOT NULL
    REFERENCES split_rule_versions(id),
  allocation_type TEXT NOT NULL,
  amount NUMERIC(36, 18) NOT NULL,
  currency TEXT NOT NULL,
  availability_status TEXT NOT NULL DEFAULT 'pending',
  available_at TIMESTAMP,
  reversed_at TIMESTAMP,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (payment_id, partner_id, allocation_type)
);

CREATE TABLE payout_batches (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  status TEXT NOT NULL DEFAULT 'draft',
  item_count INTEGER NOT NULL DEFAULT 0,
  total_amount NUMERIC(36, 18),
  currency TEXT,
  snapshot_hash TEXT,
  created_by UUID NOT NULL,
  approved_by UUID,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  frozen_at TIMESTAMP,
  approved_at TIMESTAMP
);

CREATE TABLE payout_items (
  id UUID PRIMARY KEY,
  batch_id UUID NOT NULL REFERENCES payout_batches(id),
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  partner_id UUID NOT NULL REFERENCES partners(id),
  payout_method_version_id UUID NOT NULL
    REFERENCES payout_method_versions(id),
  amount NUMERIC(36, 18) NOT NULL,
  currency TEXT NOT NULL,
  network TEXT,
  status TEXT NOT NULL DEFAULT 'draft',
  provider TEXT NOT NULL DEFAULT 'oxapay',
  provider_track_id TEXT,
  dispatch_attempt_key TEXT NOT NULL UNIQUE,
  last_error TEXT,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  approved_at TIMESTAMP,
  sent_at TIMESTAMP,
  confirmed_at TIMESTAMP,
  UNIQUE (provider, provider_track_id)
);

CREATE TABLE payout_reservations (
  id UUID PRIMARY KEY,
  payout_item_id UUID NOT NULL REFERENCES payout_items(id),
  earning_allocation_id UUID NOT NULL REFERENCES earning_allocations(id),
  reserved_amount NUMERIC(36, 18) NOT NULL,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (payout_item_id, earning_allocation_id)
);

CREATE TABLE approvals (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  entity_type TEXT NOT NULL,
  entity_id UUID NOT NULL,
  approval_type TEXT NOT NULL,
  actor_id UUID NOT NULL,
  snapshot_hash TEXT NOT NULL,
  decision TEXT NOT NULL,
  reason TEXT,
  created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE TABLE operational_cases (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  entity_type TEXT NOT NULL,
  entity_id UUID,
  case_type TEXT NOT NULL,
  severity TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'open',
  summary TEXT NOT NULL,
  evidence JSONB,
  recommended_action TEXT,
  resolution_note TEXT,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  resolved_at TIMESTAMP
);

CREATE TABLE outbox_jobs (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  topic TEXT NOT NULL,
  payload JSONB NOT NULL,
  status TEXT NOT NULL DEFAULT 'pending',
  attempt_count INTEGER NOT NULL DEFAULT 0,
  available_at TIMESTAMP NOT NULL DEFAULT NOW(),
  published_at TIMESTAMP,
  created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

The schema is larger than a normal checkout integration because the financial responsibilities are larger.

Freeze the split rule at order creation

Do not look up the currently active split rule after payment.

The rule may have changed since the customer created the order.

Store the exact split-rule version on the order:

Order ORD-1042
Split rule: Course Revenue
Version: 4

Suppose version 4 says:

Platform: 20%
Instructor: 70%
Affiliate: 10%

Version 5 may later change the platform fee to 25%.

Order ORD-1042 must still use version 4.

Without rule versioning, historical partner balances can change when configuration changes.

Validate the split rule

A percentage-based split must satisfy a defined total.

import Decimal from "decimal.js";

export function validatePercentageRule(
  allocations,
) {
  const total = allocations.reduce(
    (sum, allocation) =>
      sum.plus(
        new Decimal(allocation.percent),
      ),
    new Decimal(0),
  );

  if (!total.equals(100)) {
    throw new Error(
      `Split percentages must total 100. Received ${total.toString()}`,
    );
  }
}

If the product supports reserves, define whether reserve is part of the 100% allocation.

For example:

Platform revenue: 20%
Instructor payable: 65%
Affiliate payable: 10%
Reserve liability: 5%
Total: 100%

Do not allow an unexplained remainder.

Receive payment webhooks safely

Use a merchant-specific endpoint so the application can load the correct Merchant API Key before trusting the payload.

import crypto from "node:crypto";
import express from "express";

const app = express();

app.post(
  "/webhooks/oxapay/payment/:endpointId",
  express.raw({
    type: "application/json",
  }),
  async (req, res) => {
    const merchant =
      await loadMerchantByPaymentEndpoint(
        req.params.endpointId,
      );

    if (!merchant) {
      return res
        .status(404)
        .send("unknown endpoint");
    }

    const rawBody = req.body;
    const receivedHmac =
      req.get("HMAC");

    const merchantApiKey =
      await decryptSecret(
        merchant
          .oxapayMerchantApiKeyEncrypted,
      );

    const expectedHmac = crypto
      .createHmac(
        "sha512",
        merchantApiKey,
      )
      .update(rawBody)
      .digest("hex");

    if (
      !safeEqualSha512(
        receivedHmac,
        expectedHmac,
      )
    ) {
      await recordRejectedEvent({
        merchantId: merchant.id,
        eventType: "payment",
        reason: "invalid_hmac",
      });

      return res
        .status(401)
        .send("invalid signature");
    }

    let payload;

    try {
      payload = JSON.parse(
        rawBody.toString("utf8"),
      );
    } catch {
      return res
        .status(400)
        .send("invalid json");
    }

    const payloadHash = crypto
      .createHash("sha256")
      .update(rawBody)
      .digest("hex");

    try {
      await persistPaymentEventAndOutbox({
        merchant,
        payload,
        payloadHash,
      });

      return res
        .status(200)
        .send("ok");
    } catch (error) {
      console.error(
        "Payment event persistence failed",
        error,
      );

      return res
        .status(500)
        .send("failed");
    }
  },
);

function safeEqualSha512(
  received,
  expected,
) {
  const validHex =
    /^[a-f0-9]{128}$/i;

  if (
    !received ||
    !expected ||
    !validHex.test(received) ||
    !validHex.test(expected)
  ) {
    return false;
  }

  return crypto.timingSafeEqual(
    Buffer.from(received, "hex"),
    Buffer.from(expected, "hex"),
  );
}

Store the provider event and outbox job inside one database transaction.

Do not calculate splits inside the webhook request.

Recognize the payment once

Before posting financial entries:

Load the payment by track_id.
Retrieve current Payment Information.
Verify the provider status.
Verify the order mapping.
Verify the amount policy.
Load the frozen split-rule version.
Calculate allocations.
Post one balanced journal transaction.
Create earning-allocation records.
Mark the payment recognized.

export async function recognizePaidPayment({
  merchant,
  payment,
  providerPayment,
}) {
  if (
    String(providerPayment.status)
      .toLowerCase() !== "paid"
  ) {
    throw new PermanentFinanceError(
      "Provider payment is not paid",
    );
  }

  const businessKey =
    `payment-recognition:${payment.id}`;

  return db.$transaction(async (tx) => {
    const existing =
      await tx.journalTransaction.findUnique({
        where: {
          merchantId_businessKey: {
            merchantId: merchant.id,
            businessKey,
          },
        },
      });

    if (existing) {
      return existing;
    }

    const order =
      await tx.order.findUnique({
        where: { id: payment.orderId },
        include: {
          splitRuleVersion: true,
        },
      });

    if (!order) {
      throw new PermanentFinanceError(
        "Order not found",
      );
    }

    if (
      String(providerPayment.order_id) !==
      String(order.externalOrderId)
    ) {
      throw new PermanentFinanceError(
        "Payment order_id mismatch",
      );
    }

    const allocableAmount =
      calculateAllocableAmount({
        order,
        payment,
        providerPayment,
        allocationBasis:
          order.splitRuleVersion
            .allocationBasis,
      });

    const allocations =
      calculateAllocations({
        amount: allocableAmount,
        rule:
          order.splitRuleVersion.config,
      });

    assertAllocationTotal({
      allocations,
      allocableAmount,
    });

    const journal =
      await tx.journalTransaction.create({
        data: {
          merchantId: merchant.id,
          businessKey,
          transactionType:
            "revenue_allocation",
          referenceType: "payment",
          referenceId: payment.id,
          currency:
            providerPayment.currency,
          description:
            `Revenue allocation for ${order.externalOrderId}`,
          metadata: {
            splitRuleVersionId:
              order.splitRuleVersionId,
            allocationBasis:
              order.splitRuleVersion
                .allocationBasis,
            allocableAmount:
              allocableAmount.toString(),
          },
        },
      });

    await tx.journalLine.create({
      data: {
        journalTransactionId:
          journal.id,
        accountCode:
          "merchant_funds_control",
        side: "debit",
        amount:
          allocableAmount.toString(),
      },
    });

    for (const allocation of allocations) {
      await tx.journalLine.create({
        data: {
          journalTransactionId:
            journal.id,
          accountCode:
            allocation.accountCode,
          partnerId:
            allocation.partnerId ?? null,
          side: "credit",
          amount:
            allocation.amount.toString(),
          metadata: {
            allocationType:
              allocation.type,
          },
        },
      });

      if (allocation.partnerId) {
        await tx.earningAllocation.create({
          data: {
            merchantId: merchant.id,
            paymentId: payment.id,
            partnerId:
              allocation.partnerId,
            splitRuleVersionId:
              order.splitRuleVersionId,
            allocationType:
              allocation.type,
            amount:
              allocation.amount.toString(),
            currency:
              providerPayment.currency,
            availabilityStatus:
              allocation.availableAt >
              new Date()
                ? "pending"
                : "available",
            availableAt:
              allocation.availableAt,
          },
        });
      }
    }

    await tx.payment.update({
      where: { id: payment.id },
      data: {
        providerStatus: "paid",
        internalStatus:
          "revenue_recognized",
        receivedAmount:
          providerPayment.amount,
        receivedCurrency:
          providerPayment.currency,
        network:
          providerPayment.network,
        paidAt: new Date(),
      },
    });

    return journal;
  });
}

calculateAllocableAmount and calculateAllocations must use a decimal library and explicit rounding rules.

Handle rounding deliberately

Percentage calculations can produce fractional remainders.

Example:

Allocable amount: 10 USDT
Three partners: 33.33% each

The mathematical result does not divide cleanly at every precision.

Define:

calculation precision
payout precision
rounding mode
remainder account

One policy is:

Calculate all shares at supported precision.

Round each partner share down.

Allocate the final remainder to a rounding account or the platform.

The policy must be consistent and visible.

Do not let each programming language or database driver choose its own rounding behavior.

Pending, available, reserved, and paid

A partner earning should move through explicit availability states.

pending
-> available
-> reserved
-> paid

Exception states can include:

reversed
disputed
blocked

Pending

The earning exists but cannot yet be paid.

Possible reasons:

refund window
service delivery window
reserve period
fraud review
merchant policy

Available

The earning can be included in a payout batch.

Reserved

The earning has been claimed by one payout item.

It must not be included elsewhere.

Paid

The associated provider payout was confirmed.

Do not derive this lifecycle only from payout-item status.

Keep the relationship between earning allocations and payout reservations explicit.

Refunds and reversals

Never delete an original revenue allocation after a refund.

Post a reversal.

For a full reversal:

Debit  Platform revenue
Debit  Partner payable: instructor
Debit  Partner payable: affiliate

Credit Merchant funds control

The exact journal depends on whether the partner earning is:

pending
available
reserved
already paid

If the partner was already paid, the system may create:

Negative partner balance

or assign the loss according to merchant policy.

That decision is not purely technical.

Your system should expose the financial condition and require an authorized policy.

Useful cases include:

refund_before_payout

refund_after_reservation

refund_after_confirmed_payout

partial_refund

manual_revenue_adjustment

Each case should produce new journal entries and audit evidence.

Version payout methods

Do not edit a wallet address in place.

Create payout-method versions.

Partner payout method version 1
USDT / Tron / Address A
Disabled

Partner payout method version 2
USDT / Tron / Address B
Verified

Historical payout items must continue to reference the exact version they used.

A secure address-change flow can be:

Partner submits new address
-> New version created as pending
-> Existing address remains active
-> Confirmation is sent
-> Authorized reviewer verifies change
-> Cooldown begins
-> New version becomes active
-> Old version is disabled

Recommended controls:

separate submitter and verifier for high-value accounts
notification to the previous contact method
cooldown after address changes
payout block during unresolved changes
full audit trail
address and network validation
memo or destination-tag validation when required

A payout address is financial configuration.

Treat it like one.

Create payout batches from available earnings

The batch builder should:

Select available earnings.
Apply minimum thresholds.
Exclude blocked partners.
Load the verified payout-method version.
Lock selected earnings.
Create payout items.
Create reservation records.
Post reservation journal entries.
Freeze the batch snapshot.

This must happen transactionally.

export async function buildPayoutBatch({
  merchantId,
  currency,
  createdBy,
}) {
  return db.$transaction(
    async (tx) => {
      const batch =
        await tx.payoutBatch.create({
          data: {
            merchantId,
            status: "draft",
            currency,
            createdBy,
          },
        });

      const partners =
        await findEligiblePartnerBalances(
          tx,
          {
            merchantId,
            currency,
          },
        );

      for (const partner of partners) {
        if (
          partner.availableBalance.lessThan(
            partner.minimumPayout,
          )
        ) {
          continue;
        }

        const payoutMethod =
          await tx.payoutMethodVersion.findFirst({
            where: {
              partnerId: partner.id,
              currency,
              status: "verified",
              disabledAt: null,
            },
            orderBy: {
              version: "desc",
            },
          });

        if (!payoutMethod) {
          await createOperationalCaseTx(
            tx,
            {
              merchantId,
              entityType: "partner",
              entityId: partner.id,
              caseType:
                "missing_verified_payout_method",
              severity: "medium",
              summary:
                "Partner has available earnings but no verified payout method.",
            },
          );

          continue;
        }

        const allocations =
          await lockAvailableAllocations(
            tx,
            {
              partnerId: partner.id,
              currency,
              maximumAmount:
                partner.availableBalance,
            },
          );

        const payoutAmount =
          sumAllocationAmounts(
            allocations,
          );

        const payoutItem =
          await tx.payoutItem.create({
            data: {
              batchId: batch.id,
              merchantId,
              partnerId: partner.id,
              payoutMethodVersionId:
                payoutMethod.id,
              amount:
                payoutAmount.toString(),
              currency,
              network:
                payoutMethod.network,
              status: "reserved",
              dispatchAttemptKey:
                `payout:${batch.id}:${partner.id}`,
            },
          });

        for (const allocation of allocations) {
          await tx.payoutReservation.create({
            data: {
              payoutItemId:
                payoutItem.id,
              earningAllocationId:
                allocation.id,
              reservedAmount:
                allocation.amount,
            },
          });

          await tx.earningAllocation.update({
            where: {
              id: allocation.id,
            },
            data: {
              availabilityStatus:
                "reserved",
            },
          });
        }

        await postPayoutReservationJournal(
          tx,
          {
            merchantId,
            payoutItem,
            partnerId: partner.id,
            amount: payoutAmount,
            currency,
          },
        );
      }

      const summary =
        await calculateBatchSummary(
          tx,
          batch.id,
        );

      const snapshotHash =
        hashPayoutBatchSnapshot(summary);

      return tx.payoutBatch.update({
        where: { id: batch.id },
        data: {
          status: "frozen",
          itemCount:
            summary.itemCount,
          totalAmount:
            summary.totalAmount,
          snapshotHash,
          frozenAt: new Date(),
        },
      });
    },
    {
      isolationLevel: "Serializable",
    },
  );
}

The database and ORM syntax will vary.

The important requirement is that two concurrent workers cannot reserve the same earning.

Approval must apply to a frozen snapshot

An approval should not mean:

Someone clicked Approve.

It should mean:

An authorized person approved this exact collection of partners, amounts, assets, networks, and addresses.

Calculate a snapshot hash from:

batch ID
payout-item IDs
partner IDs
amounts
currencies
networks
payout-method version IDs
addresses or address hashes

When approving:

Recalculate the hash.
Compare it with the frozen hash.
Reject approval if anything changed.
Store the hash in the approval record.
Move the batch to approved.

If the batch changes, invalidate the approval and freeze a new version.

Use maker-checker controls

For sensitive payouts, the person creating the batch should not approve it.

export async function approvePayoutBatch({
  batchId,
  actor,
}) {
  const batch =
    await loadFrozenBatch(batchId);

  if (batch.createdBy === actor.id) {
    throw new Error(
      "Batch creator cannot approve this batch",
    );
  }

  assertRoleAllowed(
    actor,
    "approve_payout_batch",
  );

  const currentSnapshot =
    await calculateBatchSnapshot(
      batch.id,
    );

  const currentHash =
    hashPayoutBatchSnapshot(
      currentSnapshot,
    );

  if (
    currentHash !== batch.snapshotHash
  ) {
    throw new Error(
      "Batch changed after it was frozen",
    );
  }

  await db.$transaction([
    db.approval.create({
      data: {
        merchantId:
          batch.merchantId,
        entityType:
          "payout_batch",
        entityId: batch.id,
        approvalType:
          "financial_approval",
        actorId: actor.id,
        snapshotHash:
          currentHash,
        decision: "approved",
      },
    }),

    db.payoutBatch.update({
      where: { id: batch.id },
      data: {
        status: "approved",
        approvedBy: actor.id,
        approvedAt: new Date(),
      },
    }),

    db.payoutItem.updateMany({
      where: {
        batchId: batch.id,
        status: "reserved",
      },
      data: {
        status: "approved",
        approvedAt: new Date(),
      },
    }),
  ]);
}

Additional controls can include:

two approvals above a threshold
daily merchant payout limit
per-partner limit
batch-size limit
payout blackout after address change
blocked partner list
high-value manual review
separate finance and operations roles

Dispatch payouts from a worker

Never execute payouts in the browser or directly from an approval request.

The worker should load an approved payout item and its verified payout-method version.

const OXAPAY_API =
  "https://api.oxapay.com/v1";

export async function dispatchPayoutItem({
  payoutItemId,
}) {
  const item =
    await lockApprovedPayoutItem(
      payoutItemId,
    );

  if (!item) {
    return;
  }

  if (item.providerTrackId) {
    return item;
  }

  const merchant =
    await loadMerchant(item.merchantId);

  const payoutMethod =
    await loadPayoutMethodVersion(
      item.payoutMethodVersionId,
    );

  assertPayoutMethodUsable({
    partner: item.partner,
    payoutMethod,
    payoutItem: item,
  });

  await db.payoutItem.update({
    where: { id: item.id },
    data: {
      status: "dispatching",
    },
  });

  const payoutApiKey =
    await decryptSecret(
      merchant
        .oxapayPayoutApiKeyEncrypted,
    );

  try {
    const response = await fetch(
      `${OXAPAY_API}/payout`,
      {
        method: "POST",
        headers: {
          "Content-Type":
            "application/json",
          payout_api_key:
            payoutApiKey,
        },
        body: JSON.stringify({
          address:
            payoutMethod.address,
          amount: item.amount,
          currency: item.currency,
          network:
            item.network || undefined,
          memo:
            payoutMethod.memo || undefined,
          callback_url:
            `${process.env.APP_URL}/webhooks/oxapay/payout/${merchant.payoutWebhookEndpointId}`,
          description:
            `Payout item ${item.id}`,
        }),
        signal:
          AbortSignal.timeout(15000),
      },
    );

    const payload = await response.json();

    if (!response.ok) {
      await markExplicitPayoutFailure({
        payoutItemId: item.id,
        payload,
      });

      throw new Error(
        payload?.error?.message ??
          `Payout request failed with ${response.status}`,
      );
    }

    const payout = payload.data;

    return db.payoutItem.update({
      where: { id: item.id },
      data: {
        status:
          "provider_processing",
        providerTrackId:
          String(payout.track_id),
        providerStatus:
          payout.status ??
          "processing",
        sentAt: new Date(),
      },
    });
  } catch (error) {
    if (isAmbiguousDispatchError(error)) {
      await db.payoutItem.update({
        where: { id: item.id },
        data: {
          status:
            "dispatch_unknown",
          lastError: error.message,
        },
      });

      await createOperationalCase({
        merchantId:
          item.merchantId,
        entityType: "payout_item",
        entityId: item.id,
        caseType:
          "payout_dispatch_outcome_unknown",
        severity: "critical",
        summary:
          "The payout request may have reached the provider, but no conclusive response was received.",
        recommendedAction:
          "Reconcile with provider records before retrying.",
      });

      return;
    }

    throw error;
  }
}

Do not blindly retry an ambiguous payout

This is one of the most important rules in the article.

Consider:

Your worker sends the payout request.

OxaPay accepts it.

The network connection closes before your application receives the response.

Your application does not have a track_id.

It also cannot prove the payout was rejected.

Blindly retrying can create a second payout.

Mark the item:

dispatch_unknown

Then reconcile using:

Payout History
account records
destination
amount
currency
network
approximate dispatch time
description or internal evidence when available

Only retry after the first outcome is resolved.

A checkout timeout may delay an order.

A payout timeout can duplicate money movement.

Use a stricter retry policy.

Validate payout webhooks separately

Payout callbacks use the Payout API Key as their HMAC secret.

app.post(
  "/webhooks/oxapay/payout/:endpointId",
  express.raw({
    type: "application/json",
  }),
  async (req, res) => {
    const merchant =
      await loadMerchantByPayoutEndpoint(
        req.params.endpointId,
      );

    if (!merchant) {
      return res
        .status(404)
        .send("unknown endpoint");
    }

    const rawBody = req.body;
    const receivedHmac =
      req.get("HMAC");

    const payoutApiKey =
      await decryptSecret(
        merchant
          .oxapayPayoutApiKeyEncrypted,
      );

    const expectedHmac = crypto
      .createHmac(
        "sha512",
        payoutApiKey,
      )
      .update(rawBody)
      .digest("hex");

    if (
      !safeEqualSha512(
        receivedHmac,
        expectedHmac,
      )
    ) {
      return res
        .status(401)
        .send("invalid signature");
    }

    let payload;

    try {
      payload = JSON.parse(
        rawBody.toString("utf8"),
      );
    } catch {
      return res
        .status(400)
        .send("invalid json");
    }

    const payloadHash = crypto
      .createHash("sha256")
      .update(rawBody)
      .digest("hex");

    try {
      await persistPayoutEventAndOutbox({
        merchant,
        payload,
        payloadHash,
      });

      return res
        .status(200)
        .send("ok");
    } catch (error) {
      console.error(
        "Payout event persistence failed",
        error,
      );

      return res
        .status(500)
        .send("failed");
    }
  },
);

Never validate payout callbacks with the Merchant API Key.

Never use the Payout API Key for payment callbacks.

Map provider payout states

OxaPay payout statuses currently include:

processing
pending
confirming
confirmed
canceled
rejected

Map them into internal operational states.

const PAYOUT_STATUS_MAP = {
  processing:
    "provider_processing",
  pending:
    "provider_pending",
  confirming:
    "blockchain_confirming",
  confirmed:
    "completed",
  canceled:
    "canceled",
  rejected:
    "failed",
};

export function mapPayoutStatus(
  providerStatus,
) {
  return (
    PAYOUT_STATUS_MAP[
      String(providerStatus ?? "")
        .trim()
        .toLowerCase()
    ] ?? "needs_review"
  );
}

The provider state is evidence.

The internal state determines which accounting and operational action should occur.

Settle or release exactly once

When a payout becomes confirmed:

Mark the payout item completed.
Post one payout-settlement journal.
Mark reserved allocations paid.
Close the operational instruction.

When a payout becomes rejected or canceled:

Move the item to review or released.
Post one reservation-release journal.
Return associated allocations to available status.
Preserve the provider event.

export async function applyPayoutStatus({
  payoutItem,
  providerStatus,
  providerPayload,
}) {
  const internalStatus =
    mapPayoutStatus(providerStatus);

  if (internalStatus === "completed") {
    return settleConfirmedPayout({
      payoutItem,
      providerPayload,
    });
  }

  if (
    internalStatus === "failed" ||
    internalStatus === "canceled"
  ) {
    return releaseRejectedPayout({
      payoutItem,
      providerPayload,
      internalStatus,
    });
  }

  return db.payoutItem.update({
    where: {
      id: payoutItem.id,
    },
    data: {
      providerStatus,
      status: internalStatus,
    },
  });
}

Settlement:

async function settleConfirmedPayout({
  payoutItem,
  providerPayload,
}) {
  const businessKey =
    `payout-settlement:${payoutItem.id}`;

  return db.$transaction(async (tx) => {
    const existing =
      await tx.journalTransaction.findUnique({
        where: {
          merchantId_businessKey: {
            merchantId:
              payoutItem.merchantId,
            businessKey,
          },
        },
      });

    if (existing) {
      return existing;
    }

    const journal =
      await tx.journalTransaction.create({
        data: {
          merchantId:
            payoutItem.merchantId,
          businessKey,
          transactionType:
            "payout_settlement",
          referenceType:
            "payout_item",
          referenceId:
            payoutItem.id,
          currency:
            payoutItem.currency,
          description:
            `Confirmed payout ${payoutItem.id}`,
          metadata: {
            providerTrackId:
              payoutItem.providerTrackId,
            providerStatus:
              providerPayload.status,
          },
        },
      });

    await tx.journalLine.createMany({
      data: [
        {
          journalTransactionId:
            journal.id,
          accountCode:
            "payouts_in_transit",
          partnerId:
            payoutItem.partnerId,
          side: "debit",
          amount:
            payoutItem.amount,
        },
        {
          journalTransactionId:
            journal.id,
          accountCode:
            "merchant_funds_control",
          side: "credit",
          amount:
            payoutItem.amount,
        },
      ],
    });

    const reservations =
      await tx.payoutReservation.findMany({
        where: {
          payoutItemId:
            payoutItem.id,
        },
      });

    await tx.earningAllocation.updateMany({
      where: {
        id: {
          in: reservations.map(
            (reservation) =>
              reservation
                .earningAllocationId,
          ),
        },
      },
      data: {
        availabilityStatus: "paid",
      },
    });

    await tx.payoutItem.update({
      where: {
        id: payoutItem.id,
      },
      data: {
        status: "completed",
        providerStatus: "confirmed",
        confirmedAt: new Date(),
      },
    });

    return journal;
  });
}

The unique businessKey prevents duplicate payout callbacks from posting the settlement twice.

Account for payout fees

If the payout creates a separate fee, define who pays it.

Possible policies:

Merchant pays payout fee

Partner pays payout fee

Fee shared by policy

The ledger should record the result explicitly.

Merchant-paid example:

Debit  Payout fee expense
Credit Merchant funds control

Partner-paid example:

Debit  Partner payable
Credit Payout fee recovery

Do not silently reduce the sent amount without showing the partner and merchant how it was calculated.

Reconcile payments and payouts

Webhooks are the real-time path.

Provider information and history endpoints are recovery paths.

Payment reconciliation

Use Payment Information and Payment History to detect:

Provider payment is paid
Local payment is not recognized

Payment recognized
No balanced revenue-allocation journal exists

Journal exists
Earning allocations are missing

Payment was refunded
Original allocations remain unreversed

Payout reconciliation

Use Payout Information and Payout History to detect:

Payout item is dispatch_unknown

Provider payout exists
Local provider_track_id is missing

Provider status is confirmed
Local item is still confirming

Local item is completed
No settlement journal exists

Provider payout was rejected
Reservation remains locked

Unknown provider payout exists
No internal payout item matches it

A practical schedule:

Every 10 minutes:
- refresh open provider payouts
- resolve stale processing states
- investigate dispatch_unknown items

Every hour:
- compare approved and dispatched items
- report unusually old payouts

Every night:
- reconcile Payment History
- reconcile Payout History
- validate balanced journals
- validate reservation states
- produce unresolved-case report

Recovered events should identify their source:

payment_history_backfill

payout_history_backfill

manual_provider_refresh

Evidence provenance matters.

The partner dashboard

A partner should be able to understand their balance without seeing merchant-wide financial data.

Show:

pending earnings
available earnings
reserved amount
paid amount
negative adjustments
payout method
payout history
expected availability date
allocation source
payout status

For each earning:

Order: ORD-1042
Type: Instructor share
Gross allocation basis: 100 USDT
Your share: 70 USDT
Rule version: 4
Status: Available

For each payout:

Payout item: PAY-882
Amount: 350 USDT
Network: Tron
Address version: 3
Status: Confirming

Do not expose:

other partners
merchant API credentials
internal risk notes
unrestricted raw payloads
private merchant balances

Authorization must be enforced by merchant and partner scope on every query.

The merchant dashboard

The merchant needs several operational views.

Revenue allocation

paid order
allocable amount
split-rule version
platform amount
partner amounts
reserve
rounding remainder

Partner balances

pending
available
reserved
paid
negative or disputed

Payout batches

creator
frozen snapshot
approver
item count
total
status
failed items

Needs attention

invalid split total
payment without order
revenue not allocated
partner missing payout method
address changed during payout cycle
dispatch outcome unknown
rejected payout
canceled payout
confirmed payout without settlement journal
refund after partner payout
negative partner balance
unmatched provider payout

Audit history

rule changes
address changes
manual adjustments
batch creation
approvals
dispatch
settlement
release
overrides

The product should make every important number explainable.

Support should trace the full chain

Support and finance should be able to follow:

Customer payment
-> Order
-> Revenue allocation
-> Partner earning
-> Payout reservation
-> Payout item
-> Provider track_id
-> Final journal

Search fields should include:

order ID
payment track_id
partner
payout item ID
payout track_id
payout address
transaction hash
split-rule version
date range
provider status
internal status

This is where the system connects to the Crypto Payment Reconciliation Tool and Crypto Payment Support Desk.

Compliance and responsibility boundaries

Revenue-sharing and payout software can affect:

custody analysis
partner onboarding
sanctions controls
tax reporting
marketplace obligations
contractor relationships
merchant-of-record responsibilities
regional licensing
consumer refunds

The software does not automatically resolve those obligations.

A safer product model is:

The merchant owns the commercial relationship.

The merchant owns the OxaPay payment and payout accounts.

The merchant defines split, reserve, approval, and payout policies.

The merchant authorizes payout batches.

The software calculates, records, queues, executes, and tracks instructions under those policies.

Do not market the system as a way to bypass financial or legal responsibilities.

The MVP

Choose one narrow use case.

A strong first niche is:

Course platform

Support:

Platform share
Instructor share
Optional affiliate share

Build:

one merchant
OxaPay invoice creation
HMAC-validated payment webhook
Payment Information verification
immutable double-entry journal
one versioned percentage rule
pending and available earnings
partner records
verified payout-method versions
one payout currency and network
minimum payout threshold
manual batch creation
balance reservation
frozen batch snapshot
maker-checker approval
OxaPay payout execution
separate payout webhook
payout settlement and release journals
partner dashboard
merchant dashboard
Payment and Payout History recovery
CSV export
complete audit log

Do not include initially:

automatic payouts without approval
several payout currencies
currency conversion
complex tiered commissions
tax calculation
multi-provider routing
advanced risk scoring
internal custodial wallets
public payout API
unlimited custom rules

The MVP should prove:

Every confirmed payment creates explainable earnings, and every outbound payout can be traced to those earnings exactly once.

Production safeguards

Before handling real merchant payouts, implement:

separate Merchant and Payout API Keys
encrypted secret storage
strict tenant isolation
raw-body HMAC verification
timing-safe comparison
immutable rule versions
balanced journal validation
decimal arithmetic
event deduplication
payment-recognition idempotency
payout reservation locks
serializable batch creation
frozen approval snapshots
maker-checker approval
payout limits
address versioning
address-change cooldown
payout worker isolation
ambiguous-dispatch handling
payout-settlement idempotency
refund reversals
Payment History recovery
Payout History recovery
role-based authorization
audit logs
operational alerts
backup and restore testing

A payout system should fail closed.

When evidence is incomplete, stop and review.

Testing checklist

Test at least:

Invalid payment HMAC changes no state

Paying payment creates no final earnings

Paid payment is recognized exactly once

Duplicate payment payload creates no duplicate journal

Different paid callbacks create no duplicate allocation

Split percentages must total the expected amount

Rounding uses the defined policy

Historical order keeps its original rule version

Journal debits equal credits

Pending earnings cannot be reserved

The same earning cannot enter two payout items

Unverified payout address cannot be used

Address change invalidates the old approval path

Batch creator cannot approve the same batch

Changed batch snapshot cannot be executed

Payout key is never exposed to the frontend

Invalid payout HMAC changes no state

Duplicate confirmed payout callback creates one settlement

Rejected payout releases one reservation

Canceled payout releases one reservation

Ambiguous timeout is not retried automatically

Payment History recovers missing payment evidence

Payout History resolves stale payout status

Refund creates reversal entries

Partner cannot access another partner's balance

Support can trace payment to payout

These tests are part of the financial product.

They are not optional technical polish.

Product positioning

Weak positioning:

I integrate crypto payouts.

Better positioning:

I build crypto revenue-sharing dashboards for merchant platforms.

Stronger positioning:

A ledger-first system that converts confirmed customer payments into explainable partner earnings, approval-controlled crypto payouts, and fully traceable financial records.

Niche-specific positioning is stronger:

Crypto revenue sharing for course platforms: split paid course sales between the platform, instructors, and affiliates, then create controlled weekly payout batches with partner statements and audit logs.

The merchant is not purchasing a payout API call.

The merchant is purchasing control over money owed to other parties.

What makes this a real product?

A basic payout script says:

Payment paid
-> Calculate percentage
-> Send crypto

A production revenue split system says:

Verify confirmed payment
-> Freeze allocation basis
-> Apply historical split-rule version
-> Post balanced journal
-> Create pending earnings
-> Release earnings under merchant policy
-> Reserve available balances atomically
-> Freeze payout snapshot
-> Collect authorized approval
-> Dispatch through isolated worker
-> Handle ambiguous delivery safely
-> Track provider states
-> Settle or release exactly once
-> Reconcile provider and internal records
-> Preserve complete audit evidence

That is the difference between payout integration and financial operations software.

Final takeaway

The strongest opportunity is not sending crypto to partners.

It is building the control system between customer revenue and partner payouts.

OxaPay provides the execution primitives:

customer invoices
signed payment callbacks
Payment Information
Payment History
payout requests
signed payout callbacks
Payout Information
Payout History
payout status tracking
SDKs and automation integrations

The merchant product provides:

allocation policy
rule versioning
balanced journals
partner payables
reserve periods
payout-method verification
batch reservation
approval
safe execution
reconciliation
partner reporting
auditability

Start with one merchant type.

Use one allocation currency.

Support one split model.

Build the journal first.

Reserve before sending.

Approve immutable batches.

Never blindly retry an uncertain payout.

Make every balance explainable.

That is how a payout API becomes a trusted merchant operations product.

Which niche would you start with: course platforms, affiliate programs, creator marketplaces, agencies, or reseller networks?

References

OxaPay payment infrastructure

OxaPay payout infrastructure

OxaPay integrations

Security

OWASP API Security: Broken Object Level Authorization

Build a Telegram Paid Access System with Crypto Payments

kevin.s — Tue, 14 Jul 2026 05:24:23 +0000

A customer pays for 30 days of access to a private Telegram community.

The payment reaches paid, but no invitation arrives.

Another customer receives a link, forwards it to a friend, and the wrong person joins first.

A renewal payment is processed twice, extending access by 60 days instead of 30.

An expired member remains inside the group because the removal job failed silently.

The payment bot works.

The membership system does not.

A Telegram Paid Access System must connect four independent processes:

Payment
Membership term
Telegram access
Operational support

It must prove:

which Telegram user purchased access
which payment belongs to that user
which plan and community were purchased
whether the payment was verified
whether access was granted
whether the expected user joined
when the membership expires
whether renewal was applied exactly once
whether expired access was actually removed
what support should do when any step fails

This article uses OxaPay as the crypto payment infrastructure and Telegram's Bot API as the access-control layer.

The architecture is specific enough to build, but the underlying principles apply to other payment providers and community platforms.

This article is part of 10 Crypto Payment Products Developers Can Build for Merchants.

The product is not the bot

A basic bot can:

Show plans
-> Create payment link
-> Send invite after payment

That is enough for a demonstration.

A merchant-facing product must handle the entire access lifecycle:

User identity
-> Plan selection
-> Checkout session
-> Verified payment
-> Membership term
-> Telegram join approval
-> Active access
-> Renewal
-> Expiry
-> Revocation
-> Recovery

The merchant is not buying:

A Telegram bot with a crypto button.

The merchant is buying:

A system that gives paid users access, prevents unpaid users from entering, removes expired members, and explains every payment and membership incident.

That distinction defines the architecture.

Telegram already supports Stars subscriptions

Telegram's Bot API includes createChatSubscriptionInviteLink for channel subscriptions paid with Telegram Stars.

That can be the right solution when:

Telegram Stars are acceptable
the product is a channel subscription
a fixed 30-day subscription period fits the business
the merchant wants payment handled natively inside Telegram

This article solves a different problem.

A custom OxaPay-based system is useful when the merchant specifically needs:

cryptocurrency invoices
external payment records
custom access durations
several plan types
stablecoin or cryptocurrency payments
access across multiple groups or channels
merchant-owned billing and reporting
external CRM, support, or finance integrations

Do not build custom infrastructure when Telegram Stars already satisfy the complete merchant requirement.

Build it when the merchant needs a crypto-specific operational layer.

Separate payment, membership, and access

Do not store everything in one field such as:

is_paid = true

A real system needs separate states.

Payment state

created
waiting
confirming
paid
underpaid
expired
refunded
review_required

Subscription state

pending
active
grace_period
expired
revoked
canceled

Telegram access state

not_requested
invite_pending
join_requested
approved
member
removal_pending
removed
failed

These combinations are valid:

Payment: paid
Subscription: active
Telegram access: failed

The customer paid, but the system still owes access.

Another valid state:

Payment: expired
Subscription: active
Telegram access: member

The renewal invoice expired, but the currently paid membership term has not ended.

An expired renewal checkout should not remove access before the existing term expires.

Define the business invariants

Before writing code, define the rules that must always hold.

Useful invariants include:

Every checkout belongs to one Telegram user and one plan.

Every accepted payment creates at most one membership term.

A membership term cannot begin from an unverified payment.

Access is approved only for the Telegram user attached to the checkout.

A forwarded invite must not grant another user access.

Every active Telegram member must have an active term or an authorized manual grant.

Every expired term must eventually produce a verified removal outcome.

Every manual extension or revocation must have an audit record.

A payment can remain paid even when Telegram access delivery fails.

These rules matter more than the bot's interface.

Recommended access model

Telegram gives you two practical invite strategies.

Option one: limited invite link

Create an additional invite link with:

member_limit = 1
short expiry
unique internal name

This is simple, but it does not guarantee that the intended user joins.

Whoever uses the link first may consume it.

This model may be acceptable for:

low-value communities
simple prototypes
merchants who accept the forwarding risk
workflows with manual join verification

It is not the strongest identity-control model.

Option two: join-request approval

Create an invite link with:

creates_join_request = true

When someone opens the link, Telegram sends a chat_join_request update.

Your backend then compares:

Requested Telegram user ID
Expected Telegram user ID
Community
Active membership term
Invite record

The bot approves the request only when all evidence matches.

This is the recommended model for paid access.

Telegram does not allow member_limit and creates_join_request on the same invite link. Choose one access model deliberately.

The system architecture

+----------------------+
| Telegram User        |
+----------+-----------+
           |
           | /start and plan selection
           v
+----------------------+
| Telegram Bot         |
+----------+-----------+
           |
           | Create local checkout
           v
+----------------------+
| Paid Access Backend  |
+----------+-----------+
           |
           | Generate invoice
           v
+----------------------+
| OxaPay               |
+----------+-----------+
           |
           | Signed payment callback
           v
+----------------------+
| Payment Webhook      |
+----------+-----------+
           |
           | Verify and persist
           v
+----------------------+
| Event + Outbox       |
+----------+-----------+
           |
           v
+----------------------+
| Membership Worker    |
+----------+-----------+
           |
           | Create one membership term
           v
+----------------------+
| Access Worker        |
+----------+-----------+
           |
           | Create join-request link
           v
+----------------------+
| Telegram Join Request|
+----------+-----------+
           |
           | Verify Telegram user ID
           v
+----------------------+
| Approve Access       |
+----------+-----------+
           |
           v
Renewal / Expiry / Revocation / Support

Payment processing and Telegram actions should not run directly inside the OxaPay webhook request.

The webhook endpoint should:

Identify the merchant.
Preserve the raw request body.
validate the HMAC signature.
Store the payment event.
Create an outbox job.
Return HTTP 200 with ok.

Membership activation and Telegram API calls belong in background workers.

A practical data model

CREATE TABLE merchants (
  id UUID PRIMARY KEY,
  name TEXT NOT NULL,
  oxapay_merchant_api_key_encrypted TEXT NOT NULL,
  telegram_bot_token_encrypted TEXT NOT NULL,
  webhook_endpoint_id TEXT NOT NULL UNIQUE,
  created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE TABLE communities (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  name TEXT NOT NULL,
  telegram_chat_id BIGINT NOT NULL,
  access_mode TEXT NOT NULL DEFAULT 'join_request',
  active BOOLEAN NOT NULL DEFAULT TRUE,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (merchant_id, telegram_chat_id)
);

CREATE TABLE access_plans (
  id UUID PRIMARY KEY,
  community_id UUID NOT NULL REFERENCES communities(id),
  code TEXT NOT NULL,
  name TEXT NOT NULL,
  price NUMERIC(20, 8) NOT NULL,
  currency TEXT NOT NULL,
  duration_days INTEGER NOT NULL,
  grace_days INTEGER NOT NULL DEFAULT 0,
  active BOOLEAN NOT NULL DEFAULT TRUE,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (community_id, code)
);

CREATE TABLE telegram_members (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  telegram_user_id BIGINT NOT NULL,
  username TEXT,
  first_name TEXT,
  last_name TEXT,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (merchant_id, telegram_user_id)
);

CREATE TABLE subscriptions (
  id UUID PRIMARY KEY,
  community_id UUID NOT NULL REFERENCES communities(id),
  telegram_member_id UUID NOT NULL REFERENCES telegram_members(id),
  current_plan_id UUID REFERENCES access_plans(id),
  status TEXT NOT NULL DEFAULT 'pending',
  current_term_start TIMESTAMP,
  current_term_end TIMESTAMP,
  grace_until TIMESTAMP,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (community_id, telegram_member_id)
);

CREATE TABLE checkout_sessions (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  community_id UUID NOT NULL REFERENCES communities(id),
  telegram_member_id UUID NOT NULL REFERENCES telegram_members(id),
  subscription_id UUID REFERENCES subscriptions(id),
  plan_id UUID NOT NULL REFERENCES access_plans(id),
  purpose TEXT NOT NULL,
  provider TEXT NOT NULL DEFAULT 'oxapay',
  provider_order_id TEXT NOT NULL UNIQUE,
  provider_track_id TEXT,
  provider_status TEXT,
  internal_status TEXT NOT NULL DEFAULT 'created',
  amount NUMERIC(20, 8) NOT NULL,
  currency TEXT NOT NULL,
  payment_url TEXT,
  expires_at TIMESTAMP,
  paid_at TIMESTAMP,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (provider, provider_track_id)
);

CREATE TABLE payment_events (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  checkout_session_id UUID REFERENCES checkout_sessions(id),
  provider TEXT NOT NULL,
  payload_hash TEXT NOT NULL,
  provider_track_id TEXT,
  provider_status TEXT,
  raw_payload JSONB NOT NULL,
  signature_valid BOOLEAN NOT NULL,
  source TEXT NOT NULL,
  received_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (merchant_id, payload_hash)
);

CREATE TABLE membership_terms (
  id UUID PRIMARY KEY,
  subscription_id UUID NOT NULL REFERENCES subscriptions(id),
  checkout_session_id UUID REFERENCES checkout_sessions(id),
  plan_id UUID NOT NULL REFERENCES access_plans(id),
  starts_at TIMESTAMP NOT NULL,
  ends_at TIMESTAMP NOT NULL,
  grant_type TEXT NOT NULL,
  granted_by TEXT NOT NULL,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (checkout_session_id)
);

CREATE TABLE telegram_invites (
  id UUID PRIMARY KEY,
  community_id UUID NOT NULL REFERENCES communities(id),
  subscription_id UUID NOT NULL REFERENCES subscriptions(id),
  membership_term_id UUID NOT NULL REFERENCES membership_terms(id),
  expected_telegram_user_id BIGINT NOT NULL,
  invite_link TEXT NOT NULL UNIQUE,
  access_mode TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'created',
  expires_at TIMESTAMP NOT NULL,
  joined_at TIMESTAMP,
  created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE TABLE telegram_access_actions (
  id UUID PRIMARY KEY,
  community_id UUID NOT NULL REFERENCES communities(id),
  subscription_id UUID NOT NULL REFERENCES subscriptions(id),
  action_type TEXT NOT NULL,
  idempotency_key TEXT NOT NULL UNIQUE,
  status TEXT NOT NULL,
  attempt_count INTEGER NOT NULL DEFAULT 0,
  request_data JSONB,
  result_data JSONB,
  last_error TEXT,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  completed_at TIMESTAMP
);

CREATE TABLE outbox_jobs (
  id UUID PRIMARY KEY,
  topic TEXT NOT NULL,
  payload JSONB NOT NULL,
  status TEXT NOT NULL DEFAULT 'pending',
  attempt_count INTEGER NOT NULL DEFAULT 0,
  available_at TIMESTAMP NOT NULL DEFAULT NOW(),
  published_at TIMESTAMP,
  created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

CREATE TABLE access_cases (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL REFERENCES merchants(id),
  community_id UUID REFERENCES communities(id),
  subscription_id UUID REFERENCES subscriptions(id),
  checkout_session_id UUID REFERENCES checkout_sessions(id),
  case_type TEXT NOT NULL,
  severity TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'open',
  summary TEXT NOT NULL,
  recommended_action TEXT,
  resolution_note TEXT,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  resolved_at TIMESTAMP
);

The key constraint is:

UNIQUE (checkout_session_id)

on membership_terms.

One accepted payment can create only one membership term.

Duplicate callbacks cannot extend access twice.

Store Telegram IDs as 64-bit values

Do not identify members by username.

Telegram usernames can be changed, removed, or reused.

The durable identity is:

telegram_user_id

Store it in a database type that supports 64-bit values.

Keep the username only as searchable display metadata.

Create the checkout locally first

When the user chooses a plan, create the local checkout before calling OxaPay.

import crypto from "node:crypto";

const OXAPAY_API = "https://api.oxapay.com/v1";

export async function createTelegramCheckout({
  merchant,
  community,
  telegramMember,
  plan,
  purpose = "new_membership",
}) {
  if (!plan.active) {
    throw new Error("Access plan is unavailable");
  }

  const checkoutId = crypto.randomUUID();
  const providerOrderId = `tg_${checkoutId}`;

  const subscription = await db.subscription.upsert({
    where: {
      communityId_telegramMemberId: {
        communityId: community.id,
        telegramMemberId: telegramMember.id,
      },
    },
    create: {
      communityId: community.id,
      telegramMemberId: telegramMember.id,
      currentPlanId: plan.id,
      status: "pending",
    },
    update: {},
  });

  const checkout = await db.checkoutSession.create({
    data: {
      id: checkoutId,
      merchantId: merchant.id,
      communityId: community.id,
      telegramMemberId: telegramMember.id,
      subscriptionId: subscription.id,
      planId: plan.id,
      purpose,
      provider: "oxapay",
      providerOrderId,
      internalStatus: "created",
      amount: plan.price,
      currency: plan.currency,
    },
  });

  try {
    const merchantApiKey = await decryptSecret(
      merchant.oxapayMerchantApiKeyEncrypted,
    );

    const response = await fetch(
      `${OXAPAY_API}/payment/invoice`,
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          merchant_api_key: merchantApiKey,
        },
        body: JSON.stringify({
          amount: plan.price,
          currency: plan.currency,
          lifetime: 60,
          order_id: providerOrderId,
          description:
            `${plan.name} access for ${community.name}`,
          callback_url:
            `${process.env.APP_URL}/webhooks/oxapay/${merchant.webhookEndpointId}`,
          return_url:
            `${process.env.APP_URL}/telegram/checkouts/${checkout.id}`,
          sandbox:
            process.env.NODE_ENV !== "production",
        }),
      },
    );

    const payload = await response.json();

    if (!response.ok) {
      throw new Error(
        payload?.error?.message ??
          `OxaPay invoice creation failed with ${response.status}`,
      );
    }

    const payment = payload.data;

    return db.checkoutSession.update({
      where: { id: checkout.id },
      data: {
        providerTrackId: String(payment.track_id),
        providerStatus: "new",
        internalStatus: "invoice_created",
        paymentUrl: payment.payment_url,
        expiresAt: payment.expired_at
          ? new Date(Number(payment.expired_at) * 1000)
          : null,
      },
    });
  } catch (error) {
    await db.checkoutSession.update({
      where: { id: checkout.id },
      data: {
        internalStatus: "creation_failed",
      },
    });

    throw error;
  }
}

The frontend or bot must never choose the authoritative price.

Load the plan and price from your own database.

Send the invoice through the bot

A simplified Telegraf handler could look like this:

import { Markup, Telegraf } from "telegraf";

const bot = new Telegraf(
  process.env.TELEGRAM_BOT_TOKEN,
);

bot.start(async (ctx) => {
  await upsertTelegramMember(ctx.from);

  await ctx.reply(
    "Choose your access plan:",
    Markup.inlineKeyboard([
      [
        Markup.button.callback(
          "7 days - $15",
          "plan:weekly",
        ),
      ],
      [
        Markup.button.callback(
          "30 days - $39",
          "plan:monthly",
        ),
      ],
      [
        Markup.button.callback(
          "90 days - $99",
          "plan:quarterly",
        ),
      ],
    ]),
  );
});

bot.action(/^plan:(.+)$/, async (ctx) => {
  await ctx.answerCbQuery();

  const planCode = ctx.match[1];
  const telegramMember =
    await upsertTelegramMember(ctx.from);

  const community =
    await getDefaultCommunity();

  const plan = await getPlan({
    communityId: community.id,
    code: planCode,
  });

  const merchant = await getMerchant(
    community.merchantId,
  );

  const subscription =
    await getSubscription({
      communityId: community.id,
      telegramMemberId: telegramMember.id,
    });

  const purpose =
    subscription?.status === "active"
      ? "renewal"
      : "new_membership";

  const checkout =
    await createTelegramCheckout({
      merchant,
      community,
      telegramMember,
      plan,
      purpose,
    });

  await ctx.reply(
    [
      `Plan: ${plan.name}`,
      `Price: ${plan.price} ${plan.currency}`,
      "",
      "Complete the payment using this link:",
      checkout.paymentUrl,
      "",
      "Access will be prepared after the payment reaches its final paid status.",
      "Do not send another payment while your transaction is being processed.",
    ].join("\n"),
  );
});

The bot stores the Telegram user before invoice creation.

The payment is therefore connected to a stable Telegram identity from the beginning.

Identify the merchant before validating OxaPay

A multi-merchant system needs the correct Merchant API Key to validate the callback.

Do not use fields from an unverified payload to select that key.

Give each merchant a public endpoint identifier:

/webhooks/oxapay/{endpoint_id}

The endpoint ID identifies the merchant configuration.

It must not provide dashboard or API access.

Validate the OxaPay webhook

OxaPay signs the raw request body using HMAC SHA-512 and the Merchant API Key.

import crypto from "node:crypto";
import express from "express";

const app = express();

app.post(
  "/webhooks/oxapay/:endpointId",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const merchant = await db.merchant.findUnique({
      where: {
        webhookEndpointId:
          req.params.endpointId,
      },
    });

    if (!merchant) {
      return res.status(404).send("unknown endpoint");
    }

    const rawBody = req.body;
    const receivedHmac = req.get("HMAC");

    const merchantApiKey = await decryptSecret(
      merchant.oxapayMerchantApiKeyEncrypted,
    );

    const expectedHmac = crypto
      .createHmac("sha512", merchantApiKey)
      .update(rawBody)
      .digest("hex");

    if (
      !safeEqualSha512(
        receivedHmac,
        expectedHmac,
      )
    ) {
      await recordRejectedPaymentWebhook({
        merchantId: merchant.id,
        reason: "invalid_hmac",
      });

      return res
        .status(401)
        .send("invalid signature");
    }

    let payload;

    try {
      payload = JSON.parse(
        rawBody.toString("utf8"),
      );
    } catch {
      return res.status(400).send("invalid json");
    }

    const payloadHash = crypto
      .createHash("sha256")
      .update(rawBody)
      .digest("hex");

    try {
      await persistPaymentEventAndOutbox({
        merchant,
        payload,
        payloadHash,
      });

      return res.status(200).send("ok");
    } catch (error) {
      console.error(
        "Payment webhook persistence failed",
        error,
      );

      return res.status(500).send("failed");
    }
  },
);

function safeEqualSha512(
  received,
  expected,
) {
  const sha512Hex = /^[a-f0-9]{128}$/i;

  if (
    !received ||
    !expected ||
    !sha512Hex.test(received) ||
    !sha512Hex.test(expected)
  ) {
    return false;
  }

  return crypto.timingSafeEqual(
    Buffer.from(received, "hex"),
    Buffer.from(expected, "hex"),
  );
}

The event and outbox job should be inserted in one database transaction.

This prevents the event from being stored while the membership-processing job is lost.

Normalize payment status

const PAYMENT_STATUS_MAP = {
  new: "created",
  waiting: "waiting",
  paying: "confirming",
  paid: "paid",
  manual_accept: "manually_accepted",
  underpaid: "underpaid",
  expired: "expired",
  refunding: "refund_in_progress",
  refunded: "refunded",
};

function normalizeProviderStatus(status) {
  return String(status ?? "")
    .trim()
    .toLowerCase();
}

function mapPaymentStatus(status) {
  return (
    PAYMENT_STATUS_MAP[
      normalizeProviderStatus(status)
    ] ?? "unknown"
  );
}

Do not grant access on paying.

The bot may tell the customer:

Payment activity detected. Waiting for completion.

Membership activation should normally begin after paid.

A manually accepted payment should follow a separate merchant policy and preserve an audit record.

Verify the latest payment state

Before creating a membership term, retrieve Payment Information using the track_id.

async function fetchOxaPayPayment({
  merchantApiKey,
  trackId,
}) {
  const response = await fetch(
    `${OXAPAY_API}/payment/${encodeURIComponent(trackId)}`,
    {
      method: "GET",
      headers: {
        "Content-Type": "application/json",
        merchant_api_key: merchantApiKey,
      },
    },
  );

  const payload = await response.json();

  if (!response.ok) {
    throw new Error(
      payload?.error?.message ??
        `Payment lookup failed with ${response.status}`,
    );
  }

  return payload.data;
}

function assertPaymentMatchesCheckout({
  payment,
  checkout,
}) {
  if (
    normalizeProviderStatus(payment.status) !==
    "paid"
  ) {
    throw new PermanentMembershipError(
      "Payment is not in the paid state",
    );
  }

  if (
    String(payment.order_id) !==
    String(checkout.providerOrderId)
  ) {
    throw new PermanentMembershipError(
      "Payment order_id does not match checkout",
    );
  }

  if (
    decimal(payment.amount).lessThan(
      decimal(checkout.amount),
    )
  ) {
    throw new PermanentMembershipError(
      "Paid amount does not satisfy checkout",
    );
  }
}

Use decimal arithmetic for financial values.

Do not use ordinary floating-point comparisons for payment decisions.

Create one membership term per payment

import { addDays } from "date-fns";

export async function applyPaidCheckout(
  checkoutId,
) {
  return db.$transaction(async (tx) => {
    const checkout =
      await tx.checkoutSession.findUnique({
        where: { id: checkoutId },
      });

    if (!checkout) {
      throw new PermanentMembershipError(
        "Checkout session not found",
      );
    }

    const existingTerm =
      await tx.membershipTerm.findUnique({
        where: {
          checkoutSessionId: checkout.id,
        },
      });

    if (existingTerm) {
      return existingTerm;
    }

    const plan = await tx.accessPlan.findUnique({
      where: { id: checkout.planId },
    });

    if (!plan || !plan.active) {
      throw new PermanentMembershipError(
        "Access plan is unavailable",
      );
    }

    const subscription =
      await tx.subscription.findUnique({
        where: {
          id: checkout.subscriptionId,
        },
      });

    if (!subscription) {
      throw new PermanentMembershipError(
        "Subscription not found",
      );
    }

    const now = new Date();

    const startsAt =
      subscription.currentTermEnd &&
      subscription.currentTermEnd > now
        ? subscription.currentTermEnd
        : now;

    const endsAt = addDays(
      startsAt,
      plan.durationDays,
    );

    const term =
      await tx.membershipTerm.create({
        data: {
          subscriptionId: subscription.id,
          checkoutSessionId: checkout.id,
          planId: plan.id,
          startsAt,
          endsAt,
          grantType: checkout.purpose,
          grantedBy: "verified_payment",
        },
      });

    await tx.subscription.update({
      where: { id: subscription.id },
      data: {
        currentPlanId: plan.id,
        status: "active",
        currentTermStart: startsAt,
        currentTermEnd: endsAt,
        graceUntil: null,
      },
    });

    await tx.checkoutSession.update({
      where: { id: checkout.id },
      data: {
        providerStatus: "paid",
        internalStatus: "applied",
        paidAt: now,
      },
    });

    await tx.outboxJob.create({
      data: {
        topic: "telegram.prepare_access",
        payload: {
          subscriptionId: subscription.id,
          membershipTermId: term.id,
        },
      },
    });

    return term;
  });
}

The unique checkout constraint makes this operation idempotent.

The same payment cannot create two terms.

Prefer join-request links for paid access

Create a link requiring administrator approval.

async function telegramApi(
  botToken,
  method,
  body,
) {
  const response = await fetch(
    `https://api.telegram.org/bot${botToken}/${method}`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    },
  );

  const payload = await response.json();

  if (!payload.ok) {
    const error = new Error(
      payload.description ??
        `Telegram ${method} failed`,
    );

    error.errorCode = payload.error_code;
    throw error;
  }

  return payload.result;
}

async function createJoinRequestLink({
  botToken,
  chatId,
  name,
  expiresAt,
}) {
  return telegramApi(
    botToken,
    "createChatInviteLink",
    {
      chat_id: chatId,
      name: name.slice(0, 32),
      expire_date: Math.floor(
        expiresAt.getTime() / 1000,
      ),
      creates_join_request: true,
    },
  );
}

Do not add member_limit when creates_join_request is true.

Prepare Telegram access idempotently

export async function prepareTelegramAccess({
  subscriptionId,
  membershipTermId,
}) {
  const subscription =
    await db.subscription.findUnique({
      where: { id: subscriptionId },
      include: {
        telegramMember: true,
        community: {
          include: {
            merchant: true,
          },
        },
      },
    });

  const term =
    await db.membershipTerm.findUnique({
      where: { id: membershipTermId },
    });

  if (!subscription || !term) {
    throw new PermanentAccessError(
      "Membership data is incomplete",
    );
  }

  const idempotencyKey = [
    subscription.communityId,
    term.id,
    "create_join_request_link",
  ].join(":");

  const existingAction =
    await db.telegramAccessAction.findUnique({
      where: { idempotencyKey },
    });

  if (
    existingAction?.status === "completed"
  ) {
    return existingAction.resultData;
  }

  const action =
    existingAction ??
    (await db.telegramAccessAction.create({
      data: {
        communityId:
          subscription.communityId,
        subscriptionId: subscription.id,
        actionType:
          "create_join_request_link",
        idempotencyKey,
        status: "running",
        attemptCount: 1,
      },
    }));

  const botToken = await decryptSecret(
    subscription.community.merchant
      .telegramBotTokenEncrypted,
  );

  const expiresAt = new Date(
    Date.now() + 15 * 60 * 1000,
  );

  try {
    const invite =
      await createJoinRequestLink({
        botToken,
        chatId:
          subscription.community
            .telegramChatId,
        name: `term_${term.id}`,
        expiresAt,
      });

    const inviteRecord =
      await db.telegramInvite.create({
        data: {
          communityId:
            subscription.communityId,
          subscriptionId:
            subscription.id,
          membershipTermId: term.id,
          expectedTelegramUserId:
            subscription.telegramMember
              .telegramUserId,
          inviteLink: invite.invite_link,
          accessMode: "join_request",
          status: "sent",
          expiresAt,
        },
      });

    await telegramApi(
      botToken,
      "sendMessage",
      {
        chat_id:
          subscription.telegramMember
            .telegramUserId,
        text: [
          "Your payment has been confirmed.",
          "",
          "Use this link to request access:",
          invite.invite_link,
          "",
          "The request must come from the same Telegram account that purchased the plan.",
          "This link expires in 15 minutes.",
        ].join("\n"),
      },
    );

    await db.telegramAccessAction.update({
      where: { id: action.id },
      data: {
        status: "completed",
        resultData: {
          inviteId: inviteRecord.id,
        },
        completedAt: new Date(),
      },
    });

    return inviteRecord;
  } catch (error) {
    await recordTelegramActionFailure({
      actionId: action.id,
      error,
    });

    throw error;
  }
}

If the member was previously banned because an earlier term expired, unban them before sending the new link.

Verify Telegram webhook requests

Telegram's setWebhook method supports a secret_token.

Telegram then sends that value in:

X-Telegram-Bot-Api-Secret-Token

Use it to reject requests that were not sent through the webhook configuration you created.

app.post(
  "/webhooks/telegram/:botEndpointId",
  express.json(),
  async (req, res) => {
    const botConfig =
      await loadBotConfiguration(
        req.params.botEndpointId,
      );

    if (!botConfig) {
      return res.status(404).send("unknown bot");
    }

    const receivedSecret = req.get(
      "X-Telegram-Bot-Api-Secret-Token",
    );

    if (
      receivedSecret !==
      botConfig.webhookSecret
    ) {
      return res
        .status(401)
        .send("invalid secret");
    }

    await storeTelegramUpdateOnce({
      botConfig,
      update: req.body,
    });

    return res.status(200).send("ok");
  },
);

Telegram updates include an update_id.

Use it to deduplicate update processing.

Subscribe to the required Telegram updates

When configuring the Telegram webhook, include the updates needed for access control.

await telegramApi(
  botToken,
  "setWebhook",
  {
    url:
      `${process.env.APP_URL}/webhooks/telegram/${botEndpointId}`,
    secret_token: telegramWebhookSecret,
    allowed_updates: [
      "message",
      "callback_query",
      "chat_join_request",
      "chat_member",
      "my_chat_member",
    ],
  },
);

chat_member is not included automatically in the normal default set.

Request it explicitly when you need member-status tracking.

Approve only the expected user

export async function handleJoinRequest({
  botToken,
  update,
}) {
  const request = update.chat_join_request;

  if (!request) {
    return;
  }

  const inviteLink =
    request.invite_link?.invite_link;

  const telegramUserId =
    request.from.id;

  if (!inviteLink) {
    await createAccessCase({
      caseType: "join_request_without_link",
      severity: "medium",
      summary:
        "A Telegram join request has no traceable invite link.",
    });

    return;
  }

  const invite =
    await db.telegramInvite.findUnique({
      where: { inviteLink },
      include: {
        subscription: true,
        membershipTerm: true,
        community: true,
      },
    });

  if (!invite) {
    await declineJoinRequest({
      botToken,
      chatId: request.chat.id,
      telegramUserId,
    });

    return;
  }

  const now = new Date();

  const identityMatches =
    String(
      invite.expectedTelegramUserId,
    ) === String(telegramUserId);

  const accessIsActive =
    invite.subscription.status ===
      "active" &&
    invite.membershipTerm.startsAt <=
      now &&
    invite.membershipTerm.endsAt >
      now;

  const inviteIsValid =
    invite.status === "sent" &&
    invite.expiresAt > now;

  if (
    !identityMatches ||
    !accessIsActive ||
    !inviteIsValid
  ) {
    await declineJoinRequest({
      botToken,
      chatId: request.chat.id,
      telegramUserId,
    });

    await createAccessCase({
      communityId: invite.communityId,
      subscriptionId:
        invite.subscriptionId,
      caseType:
        identityMatches
          ? "invalid_membership_join_request"
          : "unexpected_user_join_request",
      severity: "high",
      summary:
        "A Telegram join request did not satisfy the access policy.",
    });

    return;
  }

  await telegramApi(
    botToken,
    "approveChatJoinRequest",
    {
      chat_id: request.chat.id,
      user_id: telegramUserId,
    },
  );

  await db.telegramInvite.update({
    where: { id: invite.id },
    data: {
      status: "approved",
      joinedAt: now,
    },
  });
}

async function declineJoinRequest({
  botToken,
  chatId,
  telegramUserId,
}) {
  return telegramApi(
    botToken,
    "declineChatJoinRequest",
    {
      chat_id: chatId,
      user_id: telegramUserId,
    },
  );
}

A forwarded link now has limited value.

The wrong user can request access, but the backend declines the request because the Telegram ID does not match the paid checkout.

Track the final membership result

Approval does not always mean the complete lifecycle is finished.

Use chat_member updates to record when the user becomes a member or leaves.

export async function handleChatMemberUpdate(
  update,
) {
  const memberUpdate = update.chat_member;

  if (!memberUpdate) {
    return;
  }

  const telegramUserId =
    memberUpdate.new_chat_member.user.id;

  const chatId = memberUpdate.chat.id;

  const oldStatus =
    memberUpdate.old_chat_member.status;

  const newStatus =
    memberUpdate.new_chat_member.status;

  await recordMembershipStatusChange({
    chatId,
    telegramUserId,
    oldStatus,
    newStatus,
    inviteLink:
      memberUpdate.invite_link
        ?.invite_link ?? null,
    occurredAt: new Date(
      memberUpdate.date * 1000,
    ),
  });
}

The admin timeline can now distinguish:

Payment confirmed
Invite sent
Join requested
Join approved
User became member

Renewal should create a new payment

Crypto membership renewal is usually invoice-based.

A renewal worker can identify expiring terms:

Five days before expiry
-> Offer renewal checkout

Three days before expiry
-> Send reminder

One day before expiry
-> Send final reminder

At term end
-> Enter grace period or expire

After grace
-> Revoke Telegram access

The renewal payment creates a new membership term.

It does not modify the old payment record.

Do not send repeated renewal invoices

Only one open renewal checkout should exist for the same subscription and renewal window.

async function prepareRenewal(
  subscription,
) {
  const existingCheckout =
    await db.checkoutSession.findFirst({
      where: {
        subscriptionId: subscription.id,
        purpose: "renewal",
        internalStatus: {
          in: [
            "created",
            "invoice_created",
            "waiting",
            "confirming",
          ],
        },
      },
    });

  if (existingCheckout) {
    return existingCheckout;
  }

  return createRenewalCheckout(
    subscription,
  );
}

A scheduled task should be safe to run repeatedly.

Model grace periods explicitly

A grace period is a merchant policy, not a paid term.

During grace, the merchant may choose to:

leave access active temporarily
restrict posting but allow reading
send additional reminders
revoke access immediately for high-value communities

Make the policy explicit.

Do not silently extend current_term_end to simulate grace.

Use a separate grace_until field.

Revoke expired access

Telegram's banChatMember can remove a member and prevent them from returning through an invite link until they are unbanned.

For a paid-access system, that creates a clear lifecycle:

Term expires
-> Ban member
-> Mark access removed

Renewal later succeeds
-> Unban member
-> Create new join-request link

export async function revokeTelegramAccess({
  subscription,
  community,
  telegramMember,
  botToken,
}) {
  const idempotencyKey = [
    community.id,
    subscription.id,
    subscription.currentTermEnd
      ?.toISOString(),
    "revoke_access",
  ].join(":");

  const action =
    await db.telegramAccessAction.upsert({
      where: { idempotencyKey },
      create: {
        communityId: community.id,
        subscriptionId:
          subscription.id,
        actionType: "ban_expired_member",
        idempotencyKey,
        status: "running",
        attemptCount: 1,
      },
      update: {},
    });

  if (action.status === "completed") {
    return;
  }

  try {
    await telegramApi(
      botToken,
      "banChatMember",
      {
        chat_id:
          community.telegramChatId,
        user_id:
          telegramMember.telegramUserId,
        revoke_messages: false,
      },
    );

    await db.$transaction([
      db.subscription.update({
        where: {
          id: subscription.id,
        },
        data: {
          status: "expired",
        },
      }),

      db.telegramAccessAction.update({
        where: { id: action.id },
        data: {
          status: "completed",
          completedAt: new Date(),
        },
      }),
    ]);
  } catch (error) {
    await recordTelegramActionFailure({
      actionId: action.id,
      error,
    });

    await createAccessCase({
      communityId: community.id,
      subscriptionId:
        subscription.id,
      caseType:
        "expired_member_removal_failed",
      severity: "high",
      summary:
        "The membership expired, but Telegram access could not be removed.",
      recommendedAction:
        "Verify bot permissions and retry member removal.",
    });

    throw error;
  }
}

The bot needs the relevant administrator permissions.

Do not promise automatic removal before testing the exact channel or supergroup configuration.

Check bot permissions during onboarding

A merchant setup flow should verify:

the chat exists
the bot is an administrator
the bot can invite users
the bot can restrict or ban members
the stored chat ID is correct
the bot can create invite links
the Telegram webhook is configured
required update types are enabled

Build a setup checker.

Do not wait until the first paid user discovers a missing permission.

Handle failures by layer

Payment paid, term not created

Create:

paid_not_applied

Recommended action:

Verify Payment Information and retry the membership worker.

Term active, invite not sent

Create:

access_delivery_failed

Recommended action:

Check bot availability, private-message capability, and Telegram API response.

Wrong user requests access

Create:

unexpected_user_join_request

Recommended action:

Decline automatically and preserve the event.

Invite expires unused

Create:

invite_expired_unused

Recommended action:

Allow the paid user to request a replacement link after identity verification.

Expired member remains inside

Create:

revocation_failed

Recommended action:

Check administrator rights and retry the removal.

Provider paid, local payment missing

Create:

provider_payment_unmatched

Recommended action:

Search by track_id, order_id, Telegram user, amount, and payment time.

Recover missed payment events

Webhooks provide the real-time path.

Use OxaPay Payment Information to refresh one payment.

Use Payment History for scheduled recovery.

A practical schedule:

Every 10 minutes:
- query an overlapping recent payment window
- upsert provider payment records by track_id
- identify paid payments not applied locally
- create recovery events
- detect expired local checkouts

Every hour:
- find active terms without confirmed Telegram membership
- retry eligible access delivery
- surface unresolved join requests

Every night:
- compare active terms with Telegram member state
- compare expired terms with removal actions
- send an unresolved-case report

Recovered payment events should be labeled:

source = payment_history_backfill

Do not present them as original webhook deliveries.

Give members a self-service status command

A /status command can reduce support tickets.

Plan: Monthly Access
Payment: Confirmed
Membership: Active
Access: Joined
Expires: September 15
Renewal: Available

For a pending payment:

Payment activity detected.
Do not send another payment while it is processing.

For paid but undelivered access:

Your payment is confirmed, but access delivery needs attention.
You do not need to pay again.

For an expired membership:

Your access term has ended.
Use /renew to create a new payment request.

Do not expose raw provider payloads or internal errors to members.

Build the admin workspace around exceptions

The merchant dashboard should answer:

Who paid?

Who currently has access?

Which paid users did not receive access?

Which memberships expire soon?

Which expired users remain in the community?

Which join requests were rejected?

Which renewals are pending?

Useful views include:

Members

Telegram ID
username
community
plan
subscription status
term end
Telegram member state
next reminder

Payments

track_id
order ID
expected amount
provider status
local status
applied membership term
payment source

Access timeline

10:01  Plan selected
10:01  Invoice created
10:05  Payment activity detected
10:06  Payment confirmed
10:06  Membership term created
10:06  Join-request link sent
10:08  Join requested
10:08  Request approved
10:09  User became member

Needs attention

paid but access not delivered
invitation expired
unexpected user attempted entry
active subscription but user is absent
expired subscription but user remains inside
invalid OxaPay webhook
failed Telegram action
unmatched provider payment

Safe admin actions

refresh payment
resend access link
create replacement invite
retry access removal
send renewal reminder
grant authorized manual term
revoke access
add internal note
assign operational case

Every manual change should identify:

Actor
Time
Reason
Previous state
New state

Low-code can validate demand

OxaPay and Telegram can also be connected through Make or n8n.

A low-code prototype may implement:

Telegram plan selection
-> OxaPay invoice
-> Payment webhook
-> Telegram notification
-> Spreadsheet membership record

This can work for a low-volume first client.

It is useful for:

validating merchant demand
demonstrating the workflow
creating a managed service
discovering common plans and support cases

A custom backend becomes more valuable when you need:

strict identity matching
join-request approval
membership-term idempotency
reliable expiry workers
multi-merchant isolation
audit history
case management
recovery from missed events
role-based administration

Low-code orchestration does not remove the need for payment and access controls.

The MVP

The first version should support one complete lifecycle:

One Telegram community
One merchant
Several access plans
OxaPay hosted invoice
Verified paid callback
One membership term
Join-request approval
Renewal reminder
Expiry and removal
Admin search

Build:

/start
plan selection
Telegram user storage
local checkout creation
OxaPay invoice generation
HMAC-validated payment webhook
payment event and outbox storage
Payment Information verification
idempotent membership terms
join-request invite links
Telegram join approval
chat_member tracking
renewal reminders
expiry worker
access revocation
/status
basic needs-attention dashboard
Payment History recovery

Do not include in version one:

affiliate payouts
public community marketplace
ten different community types
advanced analytics
AI support decisions
complex coupons
several payment providers
native mobile application
full CRM replacement

Reliability is the wedge.

Production safeguards

Before selling the system, implement:

encrypted OxaPay Merchant API Key storage
encrypted Telegram bot token storage
HMAC verification over the raw payment body
Telegram webhook secret_token
event deduplication
membership-term uniqueness
asynchronous Telegram actions
action-level idempotency
retries with backoff
permanent versus transient error classification
explicit bot permission checks
join identity validation
access-removal verification
Payment History recovery
tenant-isolated queries
role-based admin permissions
manual-action audit logs
secret masking
rate limiting
incident alerts

Test at least:

Valid paid payment creates one term

Duplicate paid callbacks do not extend access twice

Confirming payment does not grant access

Forwarded join-request link is declined for the wrong Telegram user

Expected paid user is approved

Expired invite can be replaced safely

Renewal extends from the existing term end

Expired renewal invoice does not shorten current access

Expiry worker removes access

Failed removal creates a visible case

Paid payment with failed invite delivery remains visible

Payment History recovers a missed paid event

Refunded payment creates an operational review

Product positioning

Weak positioning:

I build Telegram bots with crypto payments.

Better positioning:

I build crypto-paid Telegram membership systems.

Stronger positioning:

Sell access to private Telegram communities with verified crypto invoices, identity-checked join requests, renewals, expiry automation, and a searchable admin timeline.

A niche-specific version is stronger:

Crypto membership infrastructure for Telegram course communities, including monthly plans, automatic access approval, renewal reminders, expiry handling, and support-ready payment records.

The merchant is not buying a bot.

They are buying controlled access operations.

What makes this a real product?

A basic bot says:

If payment is paid, send invite link.

A production paid-access system says:

Capture Telegram identity
-> Create authoritative checkout
-> Generate crypto invoice
-> Validate signed payment event
-> Verify provider state
-> Create one membership term
-> Create identity-controlled join request
-> Approve only the expected Telegram user
-> Track actual member state
-> Remind before term expiry
-> Revoke access after expiry
-> Recover missed payment events
-> Surface every operational failure

That is the difference between a bot integration and paid membership infrastructure.

Final takeaway

A Telegram Paid Access System is not simply a payment bot.

It is a membership-control system.

OxaPay provides the payment primitives:

hosted invoices
unique track_id values
Merchant order_id references
HMAC-signed webhooks
Payment Information
Payment History
white-label payments
automation integrations

Telegram provides the access primitives:

additional invite links
join-request links
join approval and decline methods
member-status updates
invite revocation
member restriction and removal
webhook authentication tokens

The developer builds the control layer between them.

Start with one community.

Attach every payment to one Telegram identity.

Grant every membership term exactly once.

Approve only the expected member.

Make expiry enforceable.

Make every failure visible.

That is how a Telegram bot becomes reliable paid-access infrastructure.

Would you start with a course community, a creator membership, a premium research channel, or a private software-support group?

References

OxaPay

Build a Vertical Crypto Checkout for Hosting Providers

kevin.s — Tue, 14 Jul 2026 05:24:12 +0000

A customer pays a hosting invoice.

The payment provider reports paid, but the VPS is not provisioned.

Another customer renews an active server. The payment succeeds, but the service expiry date does not change.

A third customer sends funds after the checkout expires and opens a support ticket with a transaction screenshot.

The checkout accepted payment.

The hosting workflow did not complete.

This is why a vertical checkout is more than a payment page.

A vertical crypto checkout connects payment infrastructure to the operational rules of one merchant category. For hosting providers, that means invoice creation, payment verification, account provisioning, service renewal, expiry handling, customer instructions, support visibility, and recovery.

This article uses OxaPay as the payment infrastructure reference, but the architecture is provider-agnostic.

This article is part of 10 Crypto Payment Products Developers Can Build for Merchants.

What makes a checkout vertical?

A generic checkout knows:

Order
Amount
Payment status

A hosting checkout understands:

Hosting invoice
Customer account
Service or server
Plan
Billing period
New order or renewal
Provisioning state
Current service expiry
Support ownership

That context changes what should happen after payment.

For a new hosting order:

Payment confirmed
-> Provision service
-> Create customer credentials
-> Activate billing record
-> Send onboarding email

For a renewal:

Payment confirmed
-> Extend the existing service period
-> Update the billing panel
-> Send renewal confirmation

For an upgrade:

Payment confirmed
-> Validate upgrade eligibility
-> Change service resources
-> Record the new plan

The payment primitive may be identical in all three cases.

The business action is not.

A vertical checkout is therefore:

A payment flow designed around one industry's order, fulfillment, renewal, support, and recovery rules.

Why hosting is a strong vertical

Hosting providers already have structured operational workflows.

They normally manage:

customer accounts
service plans
billing periods
invoices
provisioning
renewals
suspensions
support tickets
service expiry
server credentials

Payment state directly affects service state.

That makes the outcome easy to define:

Customer pays
-> Hosting service starts or continues

Hosting also creates recurring operational scenarios:

new service purchases
monthly or annual renewals
upgrades
overdue invoices
expired payment sessions
duplicate payment attempts
paid but unprovisioned orders
service extensions that fail
payment-related support tickets

A generic payment integration can receive the money.

A hosting-specific checkout controls what happens around it.

Do you need a custom product?

OxaPay already provides plugins for hosting and billing platforms such as WHMCS, WISECP, Blesta, and Clientexec.

Use an existing plugin when the merchant only needs:

standard crypto payment acceptance
normal billing-panel invoice updates
provider-hosted checkout
minimal customization
no additional operational workflow

Do not build custom infrastructure merely to reproduce a plugin.

A vertical checkout becomes useful when the merchant needs something beyond the standard integration:

custom payment UX
multiple hosting or billing systems
specialized provisioning
customer-facing payment status
merchant-specific renewal policies
support timelines
paid-but-not-provisioned detection
recovery from missed callbacks
agency or reseller workflows
consolidated reporting
controlled manual actions

The product must solve a hosting problem that the existing plugin does not solve well enough.

Define the checkout contract

Before writing code, define what the system guarantees.

For a hosting checkout, useful invariants include:

Every payment session belongs to one merchant and one hosting order.

Every confirmed payment maps to a known order or enters manual review.

A service is never provisioned from a weak payment state.

The same payment cannot provision or renew a service twice.

A paid order is either fulfilled or visible in a needs-attention queue.

Every renewal creates an auditable service-period record.

A failed provisioning action does not change the confirmed payment state.

Every manual resolution records who performed it and why.

These rules are more important than the checkout page design.

They determine whether the product can be trusted with real hosting orders.

Keep payment and service states separate

Do not store the entire workflow in one field such as:

status = paid

A hosting order has several independent states.

Payment state

created
waiting
confirming
paid
underpaid
expired
refunded

Order state

pending_payment
paid
processing
completed
cancelled
manual_review

Fulfillment state

not_started
queued
running
completed
failed
needs_attention

Service state

pending
provisioning
active
suspended
terminated

This combination is valid:

Payment: paid
Order: processing
Fulfillment: failed
Service: pending

It means the payment succeeded, but the merchant still owes the customer a hosting service.

Do not reverse the payment state because provisioning failed.

Create an operational exception and retry or escalate fulfillment.

Hosted invoice or white-label checkout?

OxaPay supports both hosted invoices and white-label payment creation.

The right option depends on what part of the experience creates value.

Hosted invoice

The flow is:

Hosting order created
-> Backend creates OxaPay invoice
-> Customer opens payment_url
-> OxaPay displays the payment interface
-> Webhook reports payment status
-> Hosting workflow continues

Hosted invoices are usually the better first version when:

launch speed matters
the merchant accepts an external payment page
the main value exists after payment
you want less checkout UI complexity
you are validating demand

The developer still owns:

hosting order creation
track_id mapping
payment status page
webhook processing
provisioning
renewal
support visibility
recovery

White-label checkout

The flow is:

Customer opens merchant checkout
-> Backend requests white-label payment details
-> Merchant UI displays amount, address, network, QR, and expiry
-> Customer sends payment
-> Webhook reports payment state
-> Checkout updates in real time
-> Hosting workflow continues

White-label is useful when:

the checkout must remain inside the merchant brand
the merchant needs hosting-specific instructions
network selection requires additional explanation
the product includes a custom status page
checkout UX is part of the commercial value

White-label also creates more responsibility.

Your application must display:

the exact payment amount
payment currency
blockchain network
payment address
QR code
expiry time
payment status
clear late-payment warnings

Treat expiry as a hard operational boundary. Do not hide it in small text.

The architecture

A production hosting checkout should separate payment ingestion from provisioning.

+----------------------+
| Hosting Store /      |
| Billing Panel        |
+----------+-----------+
           |
           | Create hosting order
           v
+----------------------+
| Vertical Checkout API|
+----------+-----------+
           |
           | Generate invoice
           v
+----------------------+
| OxaPay               |
+----------+-----------+
           |
           | Payment webhook
           v
+----------------------+
| Webhook Receiver     |
+----------+-----------+
           |
           | Verify and persist
           v
+----------------------+
| Payment Event Store  |
+----------+-----------+
           |
           v
+----------------------+
| Transactional Outbox |
+----------+-----------+
           |
           v
+----------------------+
| Job Queue            |
+----------+-----------+
           |
      +----+------------------+
      |                       |
      v                       v
Provisioning Worker      Renewal Worker
      |                       |
      +-----------+-----------+
                  |
                  v
        +-------------------+
        | Hosting Platform  |
        +---------+---------+
                  |
                  v
        +-------------------+
        | Outcome Verify    |
        +---------+---------+
                  |
                  v
        Dashboard / Support

The Webhook Receiver should not provision a server or extend a service directly.

It should:

Validate the callback.
Store the payment event.
Create an outbox job.
Return the expected response quickly.

Provisioning belongs in a background worker where retries, timeouts, and partial failures can be controlled.

A hosting-specific data model

The data model should know what the customer purchased.

CREATE TABLE hosting_orders (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL,
  external_order_id TEXT NOT NULL,
  customer_id TEXT NOT NULL,
  service_id TEXT,
  plan_id TEXT NOT NULL,
  order_type TEXT NOT NULL,
  billing_period_months INTEGER NOT NULL,
  expected_amount NUMERIC(20, 8) NOT NULL,
  expected_currency TEXT NOT NULL,
  order_status TEXT NOT NULL DEFAULT 'pending_payment',
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (merchant_id, external_order_id)
);

CREATE TABLE payment_sessions (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL,
  hosting_order_id UUID NOT NULL REFERENCES hosting_orders(id),
  provider TEXT NOT NULL DEFAULT 'oxapay',
  provider_track_id TEXT NOT NULL,
  payment_method TEXT NOT NULL,
  provider_status TEXT NOT NULL,
  internal_status TEXT NOT NULL,
  requested_amount NUMERIC(20, 8) NOT NULL,
  requested_currency TEXT NOT NULL,
  payment_url TEXT,
  expires_at TIMESTAMP,
  paid_at TIMESTAMP,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (merchant_id, provider, provider_track_id)
);

CREATE TABLE payment_events (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL,
  payment_session_id UUID,
  payload_hash TEXT NOT NULL,
  provider_status TEXT,
  raw_payload JSONB NOT NULL,
  signature_valid BOOLEAN NOT NULL,
  source TEXT NOT NULL,
  received_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (merchant_id, payload_hash)
);

CREATE TABLE fulfillment_jobs (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL,
  hosting_order_id UUID NOT NULL REFERENCES hosting_orders(id),
  payment_session_id UUID NOT NULL REFERENCES payment_sessions(id),
  action_type TEXT NOT NULL,
  idempotency_key TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'queued',
  attempts INTEGER NOT NULL DEFAULT 0,
  last_error TEXT,
  next_attempt_at TIMESTAMP,
  completed_at TIMESTAMP,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (idempotency_key)
);

CREATE TABLE service_period_grants (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL,
  service_id TEXT NOT NULL,
  hosting_order_id UUID NOT NULL REFERENCES hosting_orders(id),
  payment_session_id UUID NOT NULL REFERENCES payment_sessions(id),
  starts_at TIMESTAMP NOT NULL,
  ends_at TIMESTAMP NOT NULL,
  months_granted INTEGER NOT NULL,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  UNIQUE (payment_session_id)
);

CREATE TABLE operational_cases (
  id UUID PRIMARY KEY,
  merchant_id UUID NOT NULL,
  hosting_order_id UUID,
  payment_session_id UUID,
  case_type TEXT NOT NULL,
  severity TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'open',
  summary TEXT NOT NULL,
  recommended_action TEXT,
  resolution_note TEXT,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  resolved_at TIMESTAMP
);

The order_type can identify:

new_service
renewal
upgrade

The service_period_grants table prevents the same payment from extending a service twice.

Do not merely update an expiry date without recording why it changed.

Create the hosted checkout session

The merchant creates the hosting order first.

Your backend then creates the payment session and stores the returned track_id.

const OXAPAY_API = "https://api.oxapay.com/v1";

export async function createHostingCheckout({
  merchant,
  order,
  webhookEndpointId,
}) {
  const callbackUrl = [
    process.env.APP_URL,
    "webhooks",
    "oxapay",
    webhookEndpointId,
  ].join("/");

  const response = await fetch(
    `${OXAPAY_API}/payment/invoice`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        merchant_api_key: await decryptSecret(
          merchant.oxapayMerchantApiKeyEncrypted,
        ),
      },
      body: JSON.stringify({
        amount: order.expectedAmount,
        currency: order.expectedCurrency,
        order_id: order.externalOrderId,
        email: order.customerEmail,
        description: buildHostingDescription(order),
        callback_url: callbackUrl,
        return_url:
          `${process.env.APP_URL}/checkout/${order.id}/status`,
        lifetime: 60,
        sandbox: process.env.NODE_ENV !== "production",
      }),
    },
  );

  const payload = await response.json();

  if (!response.ok) {
    throw new Error(
      payload?.error?.message ??
        `OxaPay invoice creation failed with ${response.status}`,
    );
  }

  const payment = payload.data;

  return db.paymentSession.create({
    data: {
      merchantId: merchant.id,
      hostingOrderId: order.id,
      provider: "oxapay",
      providerTrackId: String(payment.track_id),
      paymentMethod: "invoice",
      providerStatus: "new",
      internalStatus: "created",
      requestedAmount: order.expectedAmount,
      requestedCurrency: order.expectedCurrency,
      paymentUrl: payment.payment_url,
      expiresAt: payment.expired_at
        ? new Date(Number(payment.expired_at) * 1000)
        : null,
    },
  });
}

function buildHostingDescription(order) {
  if (order.orderType === "renewal") {
    return `Renewal for service ${order.serviceId}`;
  }

  if (order.orderType === "upgrade") {
    return `Upgrade for service ${order.serviceId}`;
  }

  return `New hosting order ${order.externalOrderId}`;
}

Never expose the Merchant API Key to frontend code.

The frontend receives only the checkout information it needs:

{
  "checkout_id": "chk_123",
  "payment_url": "https://...",
  "expires_at": "2026-07-28T10:00:00Z",
  "status_url": "/checkout/chk_123/status"
}

Identify the merchant before validating the webhook

A multi-merchant system needs the correct Merchant API Key to validate the callback.

Do not trust the unverified payload to select that key.

Give each merchant integration a unique public endpoint ID:

/webhooks/oxapay/{endpoint_id}

The endpoint ID identifies the merchant configuration.

It is not an API key and does not grant access to the dashboard.

Validate and persist the callback

OxaPay signs payment callbacks using HMAC SHA-512 over the raw request body. The signature is sent in the HMAC header.

import crypto from "node:crypto";
import express from "express";

const app = express();

app.post(
  "/webhooks/oxapay/:endpointId",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const endpoint = await db.webhookEndpoint.findUnique({
      where: {
        publicId: req.params.endpointId,
      },
      include: {
        merchant: true,
      },
    });

    if (!endpoint || !endpoint.enabled) {
      return res.status(404).send("unknown endpoint");
    }

    const rawBody = req.body;
    const receivedHmac = req.get("HMAC");

    const merchantApiKey = await decryptSecret(
      endpoint.merchant.oxapayMerchantApiKeyEncrypted,
    );

    const expectedHmac = crypto
      .createHmac("sha512", merchantApiKey)
      .update(rawBody)
      .digest("hex");

    if (!safeEqualSha512(receivedHmac, expectedHmac)) {
      await recordRejectedCallback({
        merchantId: endpoint.merchantId,
        reason: "invalid_hmac",
      });

      return res.status(401).send("invalid signature");
    }

    let payload;

    try {
      payload = JSON.parse(rawBody.toString("utf8"));
    } catch {
      return res.status(400).send("invalid json");
    }

    const payloadHash = crypto
      .createHash("sha256")
      .update(rawBody)
      .digest("hex");

    try {
      await persistPaymentEventAndOutbox({
        merchantId: endpoint.merchantId,
        payload,
        payloadHash,
      });

      return res.status(200).send("ok");
    } catch (error) {
      console.error("Payment event persistence failed", error);
      return res.status(500).send("failed");
    }
  },
);

function safeEqualSha512(received, expected) {
  const sha512Hex = /^[a-f0-9]{128}$/i;

  if (
    !received ||
    !expected ||
    !sha512Hex.test(received) ||
    !sha512Hex.test(expected)
  ) {
    return false;
  }

  return crypto.timingSafeEqual(
    Buffer.from(received, "hex"),
    Buffer.from(expected, "hex"),
  );
}

The storage operation should use one database transaction:

Insert payment event
+
Insert outbox job
+
Commit

A separate dispatcher publishes the outbox job to the fulfillment queue.

This prevents a valid callback from being stored without ever reaching the worker.

Normalize payment state

Do not let provider-specific strings spread across the hosting application.

const PAYMENT_STATUS_MAP = {
  new: "created",
  waiting: "waiting",
  paying: "confirming",
  paid: "paid",
  manual_accept: "manually_accepted",
  underpaid: "underpaid",
  expired: "expired",
  refunding: "refund_in_progress",
  refunded: "refunded",
};

function normalizeOxaPayStatus(status) {
  const providerStatus = String(status ?? "")
    .trim()
    .toLowerCase();

  return {
    providerStatus,
    internalStatus:
      PAYMENT_STATUS_MAP[providerStatus] ?? "unknown",
  };
}

Do not provision on paying.

The UI may show:

Payment detected. Waiting for completion.

The hosting action should normally begin only after paid.

A manually accepted payment should follow a separate merchant policy and preserve an audit record.

Verify before an irreversible action

A valid callback proves that OxaPay sent the event.

Before provisioning a paid service, retrieve the latest Payment Information and verify:

payment status
track_id
merchant ownership
order_id
expected amount
currency policy
absence of a conflicting payment session

async function fetchOxaPayPayment({
  merchantApiKey,
  trackId,
}) {
  const response = await fetch(
    `${OXAPAY_API}/payment/${encodeURIComponent(trackId)}`,
    {
      method: "GET",
      headers: {
        "Content-Type": "application/json",
        merchant_api_key: merchantApiKey,
      },
    },
  );

  const payload = await response.json();

  if (!response.ok) {
    throw new Error(
      payload?.error?.message ??
        `Payment lookup failed with ${response.status}`,
    );
  }

  return payload.data;
}

function assertPaymentMatchesOrder({
  payment,
  order,
}) {
  if (
    String(payment.status ?? "").toLowerCase() !== "paid"
  ) {
    throw new PermanentFulfillmentError(
      "Payment is not in the paid state",
    );
  }

  if (
    String(payment.order_id) !==
    String(order.externalOrderId)
  ) {
    throw new PermanentFulfillmentError(
      "Payment order_id does not match hosting order",
    );
  }

  if (
    decimal(payment.amount).lessThan(
      decimal(order.expectedAmount),
    )
  ) {
    throw new PermanentFulfillmentError(
      "Paid amount does not satisfy hosting order",
    );
  }
}

Use decimal arithmetic for financial comparisons.

Do not compare financial values with ordinary JavaScript floating-point operations.

Use hosting fulfillment adapters

A new service and a renewal should not execute the same code path.

const hostingActions = {
  new_service: provisionNewService,
  renewal: renewExistingService,
  upgrade: upgradeExistingService,
};

export async function fulfillHostingOrder({
  order,
  paymentSession,
}) {
  const action = hostingActions[order.orderType];

  if (!action) {
    throw new PermanentFulfillmentError(
      `Unsupported hosting order type: ${order.orderType}`,
    );
  }

  return action({
    order,
    paymentSession,
  });
}

The shared checkout core can handle:

payment creation
verification
event storage
job execution
retries
audit history

The adapter owns the hosting-specific action.

Provision a new hosting service idempotently

A duplicate callback or job retry must not create two servers.

Create a stable idempotency key:

merchant_id
+ payment_session_id
+ provision_new_service

async function provisionNewService({
  order,
  paymentSession,
}) {
  const idempotencyKey = [
    order.merchantId,
    paymentSession.id,
    "provision_new_service",
  ].join(":");

  const job = await db.fulfillmentJob.upsert({
    where: {
      idempotencyKey,
    },
    create: {
      merchantId: order.merchantId,
      hostingOrderId: order.id,
      paymentSessionId: paymentSession.id,
      actionType: "provision_new_service",
      idempotencyKey,
      status: "running",
      attempts: 1,
    },
    update: {},
  });

  if (job.status === "completed") {
    return job;
  }

  try {
    const result = await hostingPlatform.provision({
      customerId: order.customerId,
      planId: order.planId,
      externalOrderId: order.externalOrderId,
      idempotencyKey,
    });

    const service = await verifyProvisionedService({
      externalServiceId: result.serviceId,
      expectedPlanId: order.planId,
    });

    await db.$transaction(async (tx) => {
      await tx.hostingOrder.update({
        where: { id: order.id },
        data: {
          orderStatus: "completed",
          serviceId: service.id,
        },
      });

      await tx.fulfillmentJob.update({
        where: { id: job.id },
        data: {
          status: "completed",
          completedAt: new Date(),
        },
      });
    });

    return service;
  } catch (error) {
    await recordFulfillmentFailure({
      fulfillmentJobId: job.id,
      error,
    });

    throw error;
  }
}

An accepted API request is not always the final outcome.

Verify that the service exists and has the expected plan before marking fulfillment as complete.

Renew a service without extending it twice

A naive renewal implementation does this:

service.expiry += 1 month

If the event is processed twice, the customer receives two months.

Instead, create one immutable service-period grant per payment session.

async function renewExistingService({
  order,
  paymentSession,
}) {
  return db.$transaction(async (tx) => {
    const existingGrant =
      await tx.servicePeriodGrant.findUnique({
        where: {
          paymentSessionId: paymentSession.id,
        },
      });

    if (existingGrant) {
      return existingGrant;
    }

    const service = await tx.hostingService.findUnique({
      where: {
        id: order.serviceId,
      },
    });

    if (!service) {
      throw new PermanentFulfillmentError(
        "Hosting service not found",
      );
    }

    const now = new Date();

    const startsAt =
      service.expiresAt && service.expiresAt > now
        ? service.expiresAt
        : now;

    const endsAt = addMonthsUtc(
      startsAt,
      order.billingPeriodMonths,
    );

    const grant = await tx.servicePeriodGrant.create({
      data: {
        merchantId: order.merchantId,
        serviceId: service.id,
        hostingOrderId: order.id,
        paymentSessionId: paymentSession.id,
        startsAt,
        endsAt,
        monthsGranted: order.billingPeriodMonths,
      },
    });

    await tx.hostingService.update({
      where: {
        id: service.id,
      },
      data: {
        expiresAt: endsAt,
        status: "active",
      },
    });

    await tx.hostingOrder.update({
      where: {
        id: order.id,
      },
      data: {
        orderStatus: "completed",
      },
    });

    return grant;
  });
}

The unique constraint on payment_session_id prevents duplicate renewal.

The period-grant record explains exactly why the service expiry changed.

Distinguish retryable and permanent failures

Some fulfillment failures may succeed later.

Retryable

hosting API timeout
temporary database outage
rate limiting
billing panel unavailable
network interruption
provisioning queue overloaded

Permanent

hosting plan no longer exists
order has no customer ID
service ID is invalid
payment does not match the order
merchant credentials are invalid
requested upgrade is not supported

Retry temporary failures with backoff.

Send permanent failures directly to manual review.

class TransientFulfillmentError extends Error {}
class PermanentFulfillmentError extends Error {}

function classifyHostingError(error) {
  if (
    error.status === 429 ||
    error.status === 502 ||
    error.status === 503 ||
    error.code === "ETIMEDOUT"
  ) {
    return new TransientFulfillmentError(error.message);
  }

  return new PermanentFulfillmentError(error.message);
}

After retry exhaustion:

Payment remains paid
Fulfillment becomes needs_attention
Operational case is created
Merchant is notified
Customer receives a safe status message

Handle expired payment sessions explicitly

An expired checkout is not the same as a cancelled hosting order.

The customer may:

abandon payment
create a replacement invoice
send funds shortly before expiry
send funds after expiry
attempt to reuse old payment details

Your application should:

Mark the payment session expired.
Keep the hosting order pending for a defined period.
Allow creation of a replacement payment session.
Preserve the old track_id.
Prevent two payment sessions from fulfilling the same order twice.
Send late-payment claims to review.
Never tell the customer to pay again until the existing claim is checked.

An order can have several payment attempts:

Hosting order ORD-812
  Payment session A: expired
  Payment session B: paid

The order is fulfilled once from session B.

Session A remains part of the audit history.

Build support prevention into the checkout

Crypto checkout UX is part of payment reliability.

For a hosting customer, show:

merchant name
hosting plan
service or invoice identifier
billing period
exact amount
selected currency
selected network
payment address
QR code
expiry timer
current payment state
what happens after confirmation
support link

Useful instructions include:

Send only the selected currency on the displayed network.

Send the exact amount shown on this page.

Do not send another payment while the transaction is confirming.

Your service will be provisioned or renewed after the payment reaches the paid state.

Keep your order ID for support.

When payment activity is detected:

Payment detected. It is still being processed. Do not pay again.

After confirmation:

Payment confirmed. Your hosting service is being prepared.

If provisioning fails:

Your payment is confirmed, but service activation needs attention. You do not need to send another payment.

That last message prevents duplicate payments and unnecessary customer anxiety.

Give the customer a status page

The return page should not be a generic “thank you” screen.

Use a persistent status page:

/hosting/orders/ORD-812/payment-status

It can show:

Order created
Payment session created
Waiting for payment
Payment detected
Payment confirmed
Provisioning service
Service active

The browser should query your backend, not OxaPay directly.

Do not expose:

Merchant API Keys
raw webhook payloads
internal errors
server credentials before authorization
private support notes
other customer records

The customer-facing page presents business state.

The admin interface retains technical evidence.

Build an operations dashboard

The merchant dashboard should answer:

Which payments are waiting?

Which paid orders are not provisioned?

Which renewals failed?

Which payment sessions expired?

Which cases need support?

What happened to this specific order?

Useful views include:

Needs attention

paid but provisioning failed
paid but service record missing
renewal paid but expiry unchanged
payment without a matching order
underpaid payment
expired payment with a customer claim
repeated invalid HMAC attempts

Order timeline

09:30:11  Hosting order created
09:30:12  OxaPay invoice created
09:34:08  Payment detected
09:35:17  Payment confirmed
09:35:18  Provisioning job queued
09:35:31  Hosting API timed out
09:36:01  Retry scheduled
09:38:12  Service provisioned
09:38:14  Credentials delivered

Safe actions

refresh Payment Information
copy customer status link
retry fulfillment
assign case
create replacement invoice
add support note
escalate to developer
export payment record

Manual actions must be permission-controlled and audited.

Recover missed events

Webhooks provide the real-time path.

They should not be the only path.

Use OxaPay Payment Information to refresh one payment by track_id.

Use Payment History to run scheduled recovery.

A practical schedule:

Every 10 minutes:
- query an overlapping recent payment window
- upsert records by track_id
- identify paid payments missing locally
- identify payments whose fulfillment never completed
- create recovery events

Every night:
- compare paid payments with completed hosting orders
- compare renewals with service-period grants
- report unresolved operational cases

A recovered event should be labeled clearly:

source = payment_history_backfill

Do not make it appear as if the original webhook arrived.

Evidence provenance matters when investigating failures.

The MVP

Do not build a generic multi-industry checkout platform.

Build one reliable hosting workflow.

A strong first version includes:

one hosting merchant
one billing or hosting platform adapter
hosted OxaPay invoice
order and track_id mapping
HMAC-validated webhook ingestion
event and outbox storage
one new-service provisioning flow
one renewal flow
idempotent fulfillment
customer payment status page
needs-attention dashboard
Payment Information refresh
Payment History recovery
daily unresolved-case report

The MVP must prove:

A confirmed hosting payment causes exactly one correct service action, and every failure remains visible.

That is enough to solve a real merchant problem.

What comes after the MVP?

Add features only when the niche requires them:

white-label checkout
custom merchant branding
multiple billing panels
plan upgrades
account balance top-ups
multiple service types
reseller support
role-based merchant access
configurable renewal policies
customer notifications
accounting exports
agency white-label mode
usage-based merchant billing
operational SLA monitoring

Do not start with all of them.

Reliability creates more value than feature count.

Productize the hosting outcome

Weak positioning:

I integrate OxaPay with websites.

Better positioning:

I build crypto checkout integrations for hosting providers.

Stronger positioning:

I connect confirmed crypto payments to hosting invoices, service provisioning, renewals, customer status pages, and support recovery.

The product can be packaged as:

Standard hosting integration

payment creation
billing-panel connection
verified callbacks
normal invoice updates

Managed hosting checkout

provisioning and renewals
retry handling
payment status pages
operational alerts
recovery jobs

White-label hosting payment system

branded checkout
custom network instructions
multi-panel support
support timeline
agency or reseller capabilities

The merchant is not buying an API connection.

They are buying a reliable connection between payment and service delivery.

Common mistakes

Building for several industries at once

Hosting, courses, gaming, SaaS, and communities have different fulfillment rules.

Choose one public positioning.

Rebuilding an existing plugin without added value

Use the plugin when it solves the merchant's actual problem.

Build custom software only when the workflow requires more.

Provisioning inside the webhook request

Persist first. Provision asynchronously.

Treating `paying` as final

Do not activate paid service before the approved payment state.

Updating service expiry without an immutable grant

A duplicate event can otherwise extend the service twice.

Deduplicating callbacks but not business actions

Different callback payloads may still represent the same payment transition.

Use fulfillment-level idempotency.

Treating an expired session as the end of the order

Allow controlled replacement payment sessions and preserve history.

Hiding fulfillment failures

A paid-but-unprovisioned order must be highly visible.

Exposing raw payment data to customers

Translate infrastructure events into safe business statuses.

Ignoring recovery

A merchant-grade system must detect missed callbacks and incomplete fulfillment.

Final takeaway

A vertical crypto checkout is not a generic payment page with industry-specific colors.

It is a payment system that understands one merchant workflow deeply.

For hosting providers, that workflow is:

Hosting order
-> Payment session
-> Verified payment
-> Provisioning or renewal
-> Outcome verification
-> Customer and support visibility

OxaPay provides the underlying payment primitives:

hosted invoices
white-label payment details
unique track_id references
HMAC-signed callbacks
Payment Information
Payment History
hosting-oriented plugins
SDKs

The developer builds the hosting-specific control layer around them.

Start with one hosting provider.

Connect one confirmed payment to one correct service action.

Make retries safe.

Make duplicate actions impossible.

Make failures visible.

That is how checkout becomes a vertical product instead of another payment integration.

Would you begin with new-service provisioning, automated renewals, or a paid-but-not-provisioned recovery dashboard?

References

Build a Crypto PaymentOps Service for Merchants

kevin.s — Sat, 11 Jul 2026 07:55:01 +0000

A customer sends a crypto payment.

The transaction appears on-chain, but the order remains pending.

Support receives a screenshot. The merchant checks a wallet manually. The developer searches through webhook logs. Nobody knows whether the problem came from the payment, the order mapping, or the fulfillment process.

The payment gateway may have worked correctly. The operational system around it did not.

This is the problem a Crypto PaymentOps service solves.

A PaymentOps service sits between the payment provider and the merchant's business systems. It connects payment events to orders, fulfillment, customer support, alerts, and financial records.

This article uses OxaPay as the implementation reference, but the architecture is provider-agnostic. The same operational principles apply whenever a merchant needs to turn asynchronous payment events into reliable business actions.

What Crypto PaymentOps actually means

A basic crypto payment integration usually follows this flow:

Create a payment request.
Send the customer to checkout.
Receive a webhook.
Mark the order as paid.

That is enough for a demo. It is not enough for a production merchant.

A real merchant also needs answers to questions such as:

Which order belongs to this payment?
Is the payment safe to fulfill?
Was the payment underpaid or completed?
Did the webhook arrive more than once?
Did fulfillment succeed after payment?
Why does the customer say they paid while the order remains pending?
Can support search by order ID, email, track ID, or transaction hash?
Can finance export a clean payment report?
What happens when the webhook is missed?

Crypto PaymentOps is the operational layer that answers these questions.

It should manage:

payment creation
order-to-payment mapping
payment state
webhook ingestion
event history
fulfillment jobs
operational exceptions
support visibility
recovery and reconciliation
merchant alerts

The product is not simply a payment gateway integration.

The product is reliable payment operations.

Where PaymentOps ends

PaymentOps can easily become too broad, so its boundaries should be clear.

A reconciliation tool compares payment, order, fulfillment, and finance records to find inconsistencies.

A support desk gives agents a searchable payment timeline and tools for resolving customer cases.

An automation studio converts payment events into actions across CRM, messaging, access control, and other systems.

PaymentOps is the control layer connecting these capabilities.

It owns the payment lifecycle, records what happened, identifies unresolved states, and coordinates the systems that must react.

You do not need to build every capability in the first version. Start with the operational path that matters most to one merchant.

Why merchants pay for this layer

Merchants rarely care about API calls themselves.

They care about outcomes:

fewer manual wallet checks
faster product delivery
fewer unresolved orders
fewer duplicate actions
clearer support answers
reliable payment records
visible operational failures

A small merchant can manage ten payments manually.

At higher volume, the same process creates hidden costs. Staff spend time checking wallets, reviewing screenshots, searching transaction hashes, updating orders, and answering customers.

A PaymentOps service turns those manual decisions into a controlled workflow.

The system architecture

The PaymentOps backend sits between the merchant application and the payment provider.

Customer
   |
   v
Merchant Store / SaaS / Bot
   |
   | Create order
   v
PaymentOps API
   |
   | Create payment request
   v
OxaPay API
   |
   | Customer pays
   v
OxaPay Webhook
   |
   v
Webhook Receiver
   |
   | Validate and persist
   v
Payment Event Store
   |
   v
Job Queue
   |
   +------------------+------------------+
   |                  |                  |
   v                  v                  v
Fulfillment       Notifications     Reconciliation

The architecture separates two concerns:

Payment ingestion records what happened.

Business processing decides what should happen next.

This separation matters because a webhook endpoint should not wait for email providers, CRM APIs, hosting panels, Discord bots, or product delivery systems before acknowledging the event.

Build the merchant-specific MVP

Do not begin with a large multi-merchant SaaS platform.

Choose one merchant and one workflow.

For example:

When a customer pays for a software license, activate the order, deliver the license key, and show the entire timeline to support.

A useful MVP needs seven components.

Create and store the payment session

When the merchant creates an order, your backend creates an OxaPay invoice.

The most important rule is to store the provider's track_id next to the merchant's internal order_id.

Without this mapping, webhook processing and reconciliation become unreliable.

const OXAPAY_API = "https://api.oxapay.com/v1";

export async function createCryptoInvoice(order) {
  const response = await fetch(`${OXAPAY_API}/payment/invoice`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      merchant_api_key: process.env.OXAPAY_MERCHANT_API_KEY,
    },
    body: JSON.stringify({
      amount: order.total,
      currency: order.currency ?? "USD",
      order_id: order.id,
      email: order.customerEmail,
      description: `Order ${order.id}`,
      callback_url: `${process.env.APP_URL}/webhooks/oxapay`,
      return_url: `${process.env.APP_URL}/orders/${order.id}`,
      lifetime: 60,
      sandbox: process.env.NODE_ENV !== "production",
    }),
  });

  const payload = await response.json();

  if (!response.ok) {
    throw new Error(
      payload?.error?.message ??
        `OxaPay invoice request failed with ${response.status}`,
    );
  }

  const session = {
    provider: "oxapay",
    orderId: order.id,
    trackId: payload.data.track_id,
    paymentUrl: payload.data.payment_url,
    expiresAt: payload.data.expired_at,
    status: "new",
  };

  await db.paymentSession.create({ data: session });

  return session;
}

The merchant order and the payment session should remain separate entities.

An order describes what the customer purchased.

A payment session describes one attempt to pay for that order.

A single order may eventually have multiple payment sessions if an invoice expires and the customer creates another one.

Validate and store webhooks

OxaPay sends payment updates to the configured callback_url.

The receiver must:

accept HTTPS POST requests
preserve the raw request body
validate the HMAC signature
store the event
return HTTP 200 with ok

Use the raw request body for HMAC validation. Parsing and serializing the JSON before validation can change the byte representation and invalidate the signature.

import crypto from "node:crypto";
import express from "express";

const app = express();

app.post(
  "/webhooks/oxapay",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    try {
      const rawBody = req.body;
      const receivedHmac = req.get("HMAC");

      const expectedHmac = crypto
        .createHmac(
          "sha512",
          process.env.OXAPAY_MERCHANT_API_KEY,
        )
        .update(rawBody)
        .digest("hex");

      if (!safeEqualHex(receivedHmac, expectedHmac)) {
        return res.status(401).send("invalid signature");
      }

      const event = JSON.parse(rawBody.toString("utf8"));

      const fingerprint = crypto
        .createHash("sha256")
        .update(rawBody)
        .digest("hex");

      await storePaymentEvent({
        fingerprint,
        trackId: String(event.track_id),
        status: normalizeStatus(event.status),
        payload: event,
      });

      return res.status(200).send("ok");
    } catch (error) {
      console.error("OxaPay webhook failed", error);
      return res.status(500).send("failed");
    }
  },
);

function safeEqualHex(received, expected) {
  if (!received || !expected || received.length !== expected.length) {
    return false;
  }

  return crypto.timingSafeEqual(
    Buffer.from(received, "hex"),
    Buffer.from(expected, "hex"),
  );
}

function normalizeStatus(status) {
  return String(status ?? "").trim().toLowerCase();
}

The webhook receiver should validate and persist the event quickly.

A worker can process the stored event after the endpoint has acknowledged it.

Make event processing idempotent

Payment providers retry webhook delivery when requests fail.

Your system may therefore receive the same event more than once.

Without idempotency, a duplicate webhook could:

deliver the same file twice
generate multiple license keys
extend a subscription more than once
send duplicate alerts
create inconsistent accounting records

Store a unique fingerprint for every raw event.

async function storePaymentEvent(event) {
  try {
    await db.paymentEvent.create({
      data: {
        fingerprint: event.fingerprint,
        provider: "oxapay",
        trackId: event.trackId,
        status: event.status,
        rawPayload: event.payload,
        processingStatus: "pending",
      },
    });

    await queue.publish("payment-event.received", {
      fingerprint: event.fingerprint,
    });
  } catch (error) {
    if (isUniqueConstraintError(error)) {
      return;
    }

    throw error;
  }
}

The worker then loads the stored event and applies the state transition once.

async function processPaymentEvent(fingerprint) {
  const event = await db.paymentEvent.findUnique({
    where: { fingerprint },
  });

  if (!event || event.processingStatus === "processed") {
    return;
  }

  const session = await db.paymentSession.findUnique({
    where: { trackId: event.trackId },
  });

  if (!session) {
    await createException({
      type: "unmatched_payment_event",
      trackId: event.trackId,
      details: event.rawPayload,
    });

    return;
  }

  await db.$transaction(async (tx) => {
    await tx.paymentSession.update({
      where: { id: session.id },
      data: { status: event.status },
    });

    await tx.paymentEvent.update({
      where: { fingerprint },
      data: { processingStatus: "processed" },
    });

    if (event.status === "paid") {
      await markOrderPaidAndQueueFulfillment(tx, session);
    }
  });
}

Idempotency must also exist at the fulfillment layer.

Even if two workers attempt to process the same paid event, the system should create only one fulfillment job for that order.

Model payment state explicitly

Do not reduce the payment lifecycle to pending and paid.

OxaPay's payment model includes states such as:

Payment status	Operational meaning	Merchant action
`new`	Payment session created	Display the payment option
`waiting`	Currency selected, waiting for funds	Keep the order pending
`paying`	Payment is being processed	Do not fulfill
`paid`	Payment completed	Queue fulfillment
`underpaid`	Customer sent less than required	Send to review
`expired`	Payment session expired	Offer a new payment session
`manual_accept`	Merchant manually accepted the payment	Apply the merchant's manual policy
`refunding`	Refund is in progress	Pause related actions
`refunded`	Refund completed	Revoke or close according to policy

Payment state and order state should not be the same field.

For example:

Payment: paid
Order: paid
Fulfillment: failed

This combination means the payment succeeded, but the merchant still owes the customer a product or service.

If the system stores only order = paid, that operational failure may remain invisible.

A better model separates:

payment_status
order_status
fulfillment_status
reconciliation_status

Queue fulfillment instead of running it inside the webhook

When the payment reaches paid, create a fulfillment job.

Do not deliver the product directly inside the webhook request.

async function markOrderPaidAndQueueFulfillment(tx, session) {
  await tx.order.update({
    where: { id: session.orderId },
    data: {
      paymentStatus: "paid",
      paidAt: new Date(),
    },
  });

  await tx.fulfillmentJob.upsert({
    where: {
      orderId_type: {
        orderId: session.orderId,
        type: "deliver_order",
      },
    },
    create: {
      orderId: session.orderId,
      type: "deliver_order",
      status: "queued",
      attempts: 0,
    },
    update: {},
  });
}

The fulfillment worker can then:

deliver a file
issue a license key
activate a SaaS plan
provision a hosting account
grant access to a Telegram or Discord community
update a CRM record

Each job should record:

number of attempts
most recent error
next retry time
completion time
external system response

A failed fulfillment after a successful payment is an operational incident. It should appear in the merchant dashboard and trigger an alert.

Build an operational dashboard

The first dashboard does not need complex analytics.

It needs to help support and operations answer questions quickly.

Start with:

search by order ID
search by OxaPay track_id
search by customer email
payment status filters
paid but unfulfilled orders
underpaid payments
expired payment sessions
unmatched webhook events
failed fulfillment jobs
event timeline
CSV export

A payment timeline might look like this:

10:03:12  Order created
10:03:13  OxaPay invoice created
10:03:13  track_id linked to order
10:04:42  Webhook received: paying
10:05:11  Webhook received: paid
10:05:11  Order marked paid
10:05:12  Fulfillment job queued
10:05:18  License delivery failed
10:10:18  Fulfillment retried
10:10:20  License delivered

This timeline gives support an operational answer instead of a single status label.

Add a recovery path

Webhooks are the real-time path. They should not be the only path.

Networks fail. Deployments go wrong. Configuration changes. An endpoint may temporarily return an error.

Your service should periodically compare local records with the payment provider.

Use OxaPay's Payment Information endpoint to retrieve a specific payment by track_id.

Use Payment History to retrieve filtered payment records for a broader period.

A reconciliation job can detect cases such as:

OxaPay reports paid, but the local order is still pending
the local order is marked paid, but no paid provider record exists
the payment is paid, but fulfillment is incomplete
a webhook exists without a local payment session
an expired order still has active access
multiple payment sessions are attached to one order

async function reconcilePaymentSession(session) {
  const remotePayment = await getOxaPayPayment(session.trackId);

  if (
    normalizeStatus(remotePayment.status) === "paid" &&
    session.status !== "paid"
  ) {
    await createException({
      type: "remote_paid_local_not_paid",
      orderId: session.orderId,
      trackId: session.trackId,
      details: remotePayment,
    });
  }
}

Do not silently overwrite every inconsistency.

Some cases can be repaired automatically. Others should enter a manual review queue with a clear reason.

A practical database model

The core data model can remain small.

CREATE TABLE orders (
  id TEXT PRIMARY KEY,
  merchant_id TEXT NOT NULL,
  customer_email TEXT,
  amount DECIMAL(18, 8) NOT NULL,
  currency TEXT NOT NULL,
  payment_status TEXT NOT NULL DEFAULT 'unpaid',
  fulfillment_status TEXT NOT NULL DEFAULT 'not_started',
  paid_at TIMESTAMP,
  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE payment_sessions (
  id TEXT PRIMARY KEY,
  merchant_id TEXT NOT NULL,
  order_id TEXT NOT NULL,
  provider TEXT NOT NULL,
  track_id TEXT UNIQUE NOT NULL,
  payment_url TEXT,
  status TEXT NOT NULL,
  expires_at TIMESTAMP,
  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE payment_events (
  id TEXT PRIMARY KEY,
  fingerprint TEXT UNIQUE NOT NULL,
  provider TEXT NOT NULL,
  track_id TEXT NOT NULL,
  status TEXT NOT NULL,
  raw_payload JSONB NOT NULL,
  processing_status TEXT NOT NULL DEFAULT 'pending',
  received_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE fulfillment_jobs (
  id TEXT PRIMARY KEY,
  order_id TEXT NOT NULL,
  type TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'queued',
  attempts INTEGER NOT NULL DEFAULT 0,
  last_error TEXT,
  next_attempt_at TIMESTAMP,
  completed_at TIMESTAMP,
  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  UNIQUE (order_id, type)
);

CREATE TABLE operational_exceptions (
  id TEXT PRIMARY KEY,
  merchant_id TEXT,
  order_id TEXT,
  track_id TEXT,
  type TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'open',
  details JSONB,
  resolution_notes TEXT,
  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

The important entities are:

orders
payment sessions
immutable payment events
fulfillment jobs
operational exceptions

Everything else can be added when a real merchant workflow requires it.

Add alerts that represent action

Do not notify the merchant about every event.

Send alerts when someone needs to act.

Useful alerts include:

payment received but order not found
paid order with failed fulfillment
underpaid payment requiring review
high-value payment
repeated invalid webhook signatures
reconciliation mismatch
unresolved exception older than a defined limit
daily operations summary

Notifications can go to Slack, Telegram, Discord, email, or the merchant's existing support system.

The alert should contain enough context to investigate:

Issue: Paid order not fulfilled
Order: ORD-1842
Track ID: 982734...
Payment status: paid
Fulfillment status: failed
Last error: License provider timed out
Attempts: 3

A notification without operational context creates another support task.

Keep credentials and permissions separated

A PaymentOps service handles payment infrastructure and should be designed accordingly.

At minimum:

validate every webhook signature
encrypt merchant API keys at rest
never place API keys in logs
restrict access to raw webhook payloads
use separate credentials for merchant and payout operations
require stronger authorization for manual payment acceptance
keep an audit log for manual changes
make fulfillment idempotent
rotate credentials when staff or infrastructure changes
test failure and retry behavior before production

If the service later supports payouts, treat payout credentials as a separate and higher-risk capability.

A dashboard user who can review payments should not automatically be able to initiate payouts.

Start with one vertical workflow

A generic PaymentOps platform is difficult to sell because the value sounds abstract.

A niche workflow is easier to demonstrate.

Digital product seller

The workflow is:

Order created
-> OxaPay invoice generated
-> Payment reaches paid
-> License key reserved
-> Delivery email sent
-> Support timeline updated

The merchant pays for faster delivery and fewer manual checks.

Hosting provider

The workflow is:

Hosting order created
-> Invoice generated
-> Payment reaches paid
-> Provisioning job queued
-> Hosting account created
-> Credentials delivered

The merchant pays because payment state now controls provisioning reliably.

Paid community

The workflow is:

Membership selected
-> Invoice generated
-> Payment reaches paid
-> Role or channel access granted
-> Expiry date stored
-> Renewal reminder scheduled

The merchant pays for access control, not merely checkout.

These products may use the same PaymentOps core, but each vertical needs different fulfillment adapters, operational rules, and support views.

Productize the service

After the first successful merchant implementation, extract the repeatable parts.

A practical service can have three levels.

Payment integration

Includes:

invoice creation
order mapping
webhook validation
paid order handling
basic testing

This is the entry-level package.

PaymentOps implementation

Includes:

event store
state management
fulfillment queue
exception dashboard
support timeline
alerts
reconciliation jobs

This solves ongoing operational problems and supports recurring maintenance.

Managed PaymentOps

Includes:

monitoring
unresolved payment review
incident response
reporting
workflow updates
staff documentation
agreed support boundaries

This is a service business built around payment reliability.

The strongest positioning is not:

I integrate a crypto gateway.

It is:

I connect crypto payments to your orders, fulfillment, support, and reporting so your team does not have to manage payments manually.

The first version to build

A focused first version can include:

Payment flow

create an OxaPay invoice
map track_id to order_id
receive and validate webhooks
store immutable events
update payment state
fulfill only after paid

Operations

show payment and fulfillment status
search by order ID and track ID
list failed fulfillment jobs
list unmatched and underpaid payments
display the event timeline
retry failed jobs safely

Recovery

query Payment Information
compare remote and local state
create reconciliation exceptions
send alerts for unresolved failures

That is enough to solve a real merchant problem.

Do not start with advanced analytics, multi-provider routing, complex role management, or a large no-code workflow builder unless a merchant already needs them.

Final takeaway

The payment API is not the final product.

It creates payment sessions and reports payment state. The merchant still needs an operational system that connects those events to orders, customers, fulfillment, support, and finance.

That system is Crypto PaymentOps.

OxaPay provides the payment primitives required for the implementation: invoices, white-label payment requests, static addresses, payment information, payment history, status tracking, webhooks, and SDKs.

The developer's opportunity is to turn those primitives into a reliable merchant workflow.

A merchant should not need to investigate blockchains, search webhook logs, or update orders manually every time something goes wrong.

They should be able to see:

what happened
what the system did
what failed
what needs attention
whether the customer received what they purchased

That is more valuable than connecting an API.

It is an operational product built around reliability.

References

10 Crypto Payment Products Developers Can Build for Merchants

kevin.s — Sat, 11 Jul 2026 07:54:47 +0000

Most developers see a payment API and think about checkout.

Create an invoice. Redirect the customer. Receive a webhook. Mark the order as paid.

That is the first layer.

The larger opportunity begins after the customer pays.

A merchant may still need to:

match the payment to an order
decide when fulfillment is safe
activate a SaaS plan
deliver a license key
grant community access
reconcile provider and internal records
investigate customer claims
update a CRM
generate finance reports
calculate partner balances
approve and track payouts

These are not payment API features.

They are merchant operations.

Developers can turn these operational problems into focused products, reusable modules, managed services, or niche SaaS businesses.

This article maps 10 such opportunities. Each product also has a complete technical deep dive, so you can use this page as the index for the full series.

OxaPay is used as the implementation reference because it provides the payment primitives needed across these products: invoices, white-label payments, static addresses, webhooks, payment lookup, payment history, payouts, SDKs, plugins, and automation integrations.

The architecture and product thinking remain applicable beyond one payment provider.

The complete series

Product	Primary outcome	Full technical article
Crypto PaymentOps Service	Operate the full payment lifecycle	Read the PaymentOps guide
Vertical Crypto Checkout	Connect checkout to one niche workflow	Read the Vertical Checkout guide
Telegram Paid Access	Connect payment to membership access	Read the Telegram Paid Access guide
Revenue Split and Payout System	Calculate balances and distribute revenue	Read the Revenue Split guide
Payment Reconciliation Tool	Detect payment and order mismatches	Read the Reconciliation guide
Payment Automation Studio	Turn payment events into business actions	Read the Automation Studio guide
Merchant Launch Kit	Help agencies deploy repeatable payment systems	Read the Agency Launch Kit guide
SaaS Payment Module	Connect crypto payments to plans and access	Read the SaaS Payment Module guide
Crypto Payment Support Desk	Help agents investigate payment incidents	Read the Support Desk guide
Cross-Border Payment Stack	Package checkout, fulfillment, support, and reporting	Read the Cross-Border Stack guide

The product opportunity

A payment gateway gives a merchant a way to receive money.

A developer product solves what happens around that payment.

The simplest product model is:

Payment primitive
-> Merchant workflow
-> Operational outcome

For example:

Invoice
-> Confirm payment and identify order
-> Deliver software license

Or:

Payment webhook
-> Match workflow and verify conditions
-> Activate SaaS account

Or:

Confirmed customer payment
-> Record ledger entries and apply split rules
-> Add balances to a controlled payout queue

The API call is not the product.

The product is the reliable business outcome around it.

Why merchants pay for the operational layer

Merchants rarely buy infrastructure because the underlying code is interesting.

They pay because a system can reduce:

manual payment checks
delayed fulfillment
unresolved customer tickets
incorrect order states
duplicate actions
inconsistent financial records
spreadsheet-based operations
developer interruptions
payout mistakes

This changes how the product should be positioned.

A weak offer is:

I can integrate a crypto payment gateway.

A stronger offer is:

I can connect confirmed crypto payments to your orders, fulfillment, customer support, reporting, and internal systems.

An even stronger offer is niche-specific:

I can automatically activate hosting accounts after confirmed crypto payments, retry failed provisioning, and give support a complete payment timeline.

Specific operational outcomes are easier for merchants to understand and harder to compare with commodity integration work.

The shared technical foundation

Although the 10 products solve different problems, most share the same infrastructure.

Merchant Store / SaaS / Bot
          |
          | Create order
          v
Payment Creation Layer
          |
          | Invoice / White Label / Static Address
          v
OxaPay
          |
          | Payment status callback
          v
Webhook Receiver
          |
          | Validate and persist
          v
Payment Event Store
          |
          v
Internal State Machine
          |
          v
Job Queue
          |
     +----+----------------+----------------+
     |                     |                |
     v                     v                v
Fulfillment           Automation      Reconciliation
     |                     |                |
     +---------------------+----------------+
                           |
                           v
              Dashboard / Support / Reports

A production system normally needs:

Verified event ingestion

Preserve the raw webhook body, validate its HMAC signature, store the event, and acknowledge it quickly.

Internal state management

Do not use raw provider statuses as the complete business state. Payment, order, fulfillment, support, and payout states should remain separate.

Idempotent processing

A duplicate callback must not deliver two products, extend access twice, create duplicate ledger entries, or initiate another payout.

Asynchronous execution

Slow operations such as email delivery, CRM updates, hosting provisioning, and license assignment should run through background jobs.

Recovery

Webhooks provide the real-time path. Payment Information and Payment History provide verification and recovery paths.

Operational visibility

The merchant should be able to see what arrived, what ran, what failed, and what requires attention.

The OxaPay primitives

The products in this series use a common set of OxaPay capabilities.

Primitive	Role in a developer product
Generate Invoice	Create a hosted payment session and obtain a payment URL and `track_id`
Generate White Label	Receive payment details for a custom merchant-owned checkout interface
Generate Static Address	Create a reusable address for deposits, top-ups, or account funding
Payment Information	Retrieve the latest state of one payment using its `track_id`
Payment History	Search and backfill provider-side payment records
Payment Status Table	Map provider statuses into internal operational states
Webhook	Receive asynchronous payment and payout status updates
Generate Payout	Execute an approved outbound cryptocurrency payout
Payout Information	Retrieve the latest state of an individual payout
Payout History	Backfill and report payout activity

OxaPay also provides SDKs, ecommerce integrations, Make modules, and an n8n community integration.

These tools can reduce implementation time, but the developer product still needs its own business rules, state model, error handling, and operational controls.

1. Crypto PaymentOps Service for Merchants

A Crypto PaymentOps service is the broad operational layer between the payment provider and the merchant's business systems.

It manages payment creation, order mapping, state changes, fulfillment, alerts, exceptions, reporting, and recovery.

The merchant does not buy another payment page.

They buy one place to answer:

Which customer paid?

Which order belongs to the payment?

Can the order be fulfilled?

Did fulfillment succeed?

What still requires attention?

Best customers: Digital product sellers, hosting providers, SaaS businesses, communities, and merchants currently checking crypto payments manually.

Practical MVP: Invoice creation, track_id mapping, verified webhooks, payment and fulfillment status, failed-action queue, alerts, and a searchable merchant dashboard.

Business model: Setup project followed by monitoring, maintenance, reporting, or managed operations.

Read the complete PaymentOps architecture and implementation guide.

2. Vertical Crypto Checkout for a Specific Niche

A generic checkout accepts payment.

A vertical checkout completes a niche-specific commercial workflow.

For a hosting company:

Payment confirmed
-> Provision hosting account
-> Deliver credentials
-> Schedule renewal reminder

For a course platform:

Payment confirmed
-> Create student account
-> Enroll user
-> Send onboarding email

For a software seller:

Payment confirmed
-> Assign license
-> Deliver key
-> Record activation

The payment primitive may be similar across industries. The operational workflow is not.

Best customers: One narrowly defined merchant segment such as hosting providers, course sellers, software vendors, or digital download stores.

Practical MVP: One checkout flow, one niche fulfillment adapter, one merchant dashboard, and one support path.

Business model: Implementation package, niche plugin, hosted checkout, framework module, or recurring maintenance.

Read the complete Vertical Crypto Checkout guide.

3. Telegram Paid Access System with Crypto Payments

The valuable product is not a Telegram bot that sends a payment link.

It is a membership system that connects payment to access.

User selects plan
-> Invoice created
-> Payment confirmed
-> One-time invite generated
-> Membership activated
-> Expiry stored
-> Renewal reminder scheduled
-> Expired access removed

The system also needs admin search, payment history, membership history, and manual-resolution controls.

Best customers: Educators, creators, private communities, premium channels, paid research groups, and membership businesses operating on Telegram.

Practical MVP: Bot onboarding, plan selection, invoice creation, verified payment handling, single-use access, expiry management, and admin lookup.

Business model: Setup fee, monthly fee per community, white-label bot, or managed access operations.

Read the complete Telegram Paid Access guide.

4. Crypto Revenue Split and Payout System for Merchants

This product begins where checkout ends.

A customer payment may create earnings for several parties:

Customer payment
-> Platform fee
-> Seller share
-> Affiliate commission
-> Reserve

A reliable system should not send payouts directly from the payment webhook.

The safer model is:

Confirmed payment
-> Immutable ledger entries
-> Split calculation
-> Partner balances
-> Payout queue
-> Approval
-> Payout execution
-> Payout reconciliation

The ledger is the source of truth.

The payout API is only the execution layer.

Best customers: Marketplaces, creator platforms, affiliate programs, course platforms, agencies, reseller networks, and partner programs.

Practical MVP: Payment intake, immutable ledger, one split-rule model, partner balances, approval queue, payout execution, and audit logs.

Business model: Higher-value implementation, SaaS subscription, partner operations system, or managed payout workflow.

This is one of the most sensitive products in the series. It requires stronger permissions, separate payout credentials, destination controls, approval workflows, and clear legal boundaries.

Read the complete Revenue Split and Payout guide.

5. Crypto Payment Reconciliation Tool for Merchants

A payment dashboard shows transactions.

A reconciliation tool proves whether different systems agree.

It compares:

Provider payment state
Merchant order state
Fulfillment state
Finance state

Then it creates operational exceptions such as:

Payment paid, order pending

Order paid, fulfillment failed

Order fulfilled, payment not confirmed

Payment exists, order missing

Payment paid, finance export missing

The main product is not the transaction table.

It is the prioritized exception queue.

Best customers: Merchants with meaningful order volume, support tickets, multiple payment methods, finance reporting needs, or paid-but-undelivered incidents.

Practical MVP: Payment History synchronization, exact order matching, normalized states, five to eight reconciliation rules, case deduplication, and resolution notes.

Business model: Monthly SaaS, managed reconciliation, reporting add-on, or finance operations dashboard.

Read the complete Payment Reconciliation guide.

6. Payment Automation Studio for Crypto Merchants

A Payment Automation Studio converts verified payment events into controlled business actions.

Payment event
-> Trigger
-> Conditions
-> Actions
-> Recorded outcome

Examples include:

Paid invoice
-> Activate SaaS plan

Paid invoice
-> Deliver license key

Expired invoice
-> Send reminder

Static address payment
-> Credit account balance

Payout confirmed
-> Notify partner

A real Automation Studio needs more than if status === "paid".

It needs event storage, workflow versions, action-level idempotency, retries, replay controls, connector security, recovery jobs, and execution logs.

Best customers: Merchants with repeated manual workflows and developers experienced with APIs, n8n, Make, queues, or backend automation.

Practical MVP: Three workflows, four connectors, event ingestion, action logs, retry handling, and a needs-attention queue.

Business model: Managed automation, implementation packages, hosted SaaS, connector development, or template plus support.

Read the complete Payment Automation Studio guide.

7. Merchant Crypto Launch Kit for Agencies

Developers do not always need to sell directly to merchants.

Agencies already serve ecommerce stores, SaaS businesses, creators, hosting providers, and membership platforms.

A Merchant Crypto Launch Kit gives those agencies a repeatable delivery system.

It can include:

integration decision tree
plugin or API implementation path
checkout templates
webhook module
payment status handling
merchant dashboard starter
support procedures
testing checklist
deployment checklist
client onboarding documents
handoff documentation

The product is not only code.

It is a standardized way for an agency to sell and deliver crypto payment projects safely.

Best customers: Ecommerce agencies, SaaS studios, WordPress agencies, development companies, and payment integration consultants.

Practical MVP: One implementation package, reusable webhook code, merchant onboarding, launch QA, support procedures, and white-label agency documentation.

Business model: Agency license, per-client implementation, white-label support, training, or recurring maintenance.

Read the complete Merchant Crypto Launch Kit guide.

8. Crypto Payment Module for SaaS Apps

A SaaS founder does not only need a payment button.

The application must connect payments to product access.

User selects plan
-> Payment session created
-> Payment confirmed
-> Access period activated
-> Features unlocked
-> Renewal date stored
-> Billing status displayed

The module should keep separate records for:

Payment session
Subscription period
Access entitlement
Renewal state

Crypto billing should not automatically be described as card-style recurring billing.

A more accurate model may use invoice-based renewals, prepaid balances, account top-ups, or customer-initiated extensions.

Best customers: SaaS founders and developers working in Laravel, Node.js, Django, Next.js, or other reusable application ecosystems.

Practical MVP: Payment session creation, user mapping, plan activation, access middleware, renewal flow, admin lookup, and missed-webhook recovery.

Business model: Framework package, boilerplate, hosted billing add-on, open-source core with paid support, or custom implementation.

Read the complete SaaS Payment Module guide.

9. Crypto Payment Support Desk

A payment status alone does not tell support what happened.

Consider:

Payment: paid
Order: paid
Fulfillment: failed

The customer has paid, but still needs help.

A Crypto Payment Support Desk combines evidence from payment infrastructure and merchant systems into one agent-facing workspace.

It should show:

customer and order context
payment identifiers
current provider state
webhook history
fulfillment status
reconciliation cases
chronological timeline
recommended action
customer-safe response
escalation owner

The Support Desk should not expose unrestricted financial controls to ordinary agents.

Actions need permissions, idempotency, and audit logs.

Best customers: Merchants whose developers are repeatedly interrupted by payment tickets or whose support agents cannot investigate crypto payment incidents independently.

Practical MVP: Search by order ID and track_id, payment timeline, five case classifications, Payment Information refresh, agent notes, escalation, and approved response templates.

Business model: Per-merchant SaaS, per-agent pricing, support operations add-on, or bundled PaymentOps capability.

Read the complete Crypto Payment Support Desk guide.

10. Cross-Border Crypto Payment Stack for Digital Sellers

Many digital sellers reach international customers before they build mature payment operations.

They do not only need checkout.

They need a complete but focused stack:

Product page
-> Payment instructions
-> Invoice or branded checkout
-> Payment tracking
-> Fulfillment
-> Customer status page
-> Support
-> Reconciliation
-> Reporting

This product packages several lower-level capabilities into one deployable solution for a specific type of seller.

Best customers: Software license sellers, digital product stores, course businesses, remote service providers, indie SaaS companies, agencies, and international creator businesses.

Practical MVP: Hosted or branded checkout, verified fulfillment, customer payment status, support lookup, daily reporting, and Payment History backfill.

Business model: Premium implementation, niche-specific launch package, monthly operations plan, or support and reporting add-on.

Avoid broad claims about universal availability, taxation, compliance, or legal suitability. The product should focus on technical infrastructure and merchant operations.

Read the complete Cross-Border Crypto Payment Stack guide.

How to choose the right product

The best product depends on your current skills and distribution.

Your advantage	Strong starting product
Backend and event-driven systems	PaymentOps or Automation Studio
Experience with one merchant niche	Vertical Checkout
Telegram bot development	Telegram Paid Access
Finance or ledger experience	Reconciliation or Revenue Split
Existing agency relationships	Merchant Launch Kit
SaaS framework experience	SaaS Payment Module
Support or operational tooling experience	Payment Support Desk
Merchant implementation services	Cross-Border Payment Stack

The easiest product is not always the one with the smallest codebase.

The easiest product is usually the one where you already understand:

the buyer
the workflow
the existing tools
the failure cases
the distribution channel

Strong first products

For a developer starting without an existing audience or large merchant network, four options are particularly practical.

PaymentOps for one niche

Build the operational layer for one merchant type instead of building a generic platform.

Payment Automation as a managed service

Use custom code, n8n, or Make to prove which workflows merchants will pay for.

Telegram paid access

The payment-to-membership outcome is easy to demonstrate and easy for community owners to understand.

Vertical checkout

Choose one niche and connect payment directly to its most important fulfillment action.

Revenue Split and Reconciliation can become higher-value products, but they normally require more operational maturity, financial modeling, permissions, and audit controls.

The minimum production baseline

Regardless of which product you choose, do not ignore the following requirements.

Verify payment events

Validate OxaPay payment webhooks using the documented HMAC process over the raw request body.

Store immutable evidence

Preserve raw provider events and record how they were processed.

Separate states

Payment, order, fulfillment, reconciliation, support, access, and payout states should not be compressed into one field.

Make actions idempotent

Receiving the same event twice must not repeat an irreversible business action.

Use background jobs

Do not wait for email providers, CRMs, fulfillment systems, or payout operations inside the webhook request.

Recover missing events

Use Payment Information and Payment History to verify and repair local state.

Protect credentials

Encrypt Merchant and Payout API Keys, restrict access, and never expose them to frontend code or logs.

Preserve manual decisions

Every manual acceptance, override, retry, payout approval, and case resolution should have an audit record.

Expose uncertainty

Underpayments, ambiguous matches, invalid signatures, unknown deposits, and conflicting states should enter a review queue instead of being silently automated.

A practical four-week validation plan

Week 1: Select the merchant problem

Choose:

One merchant type
One payment workflow
One business outcome

Example:

Software license sellers
Paid invoice
Automatic license delivery

Week 2: Build the reliable core

Implement:

payment session creation
track_id and order mapping
webhook validation
event storage
internal state
one business action

Week 3: Add operations

Implement:

idempotency
retry handling
Payment Information refresh
Payment History backfill
needs-attention queue
merchant alert
support lookup

Week 4: Package the outcome

Create:

a working demo
a narrow landing page
onboarding checklist
implementation scope
support boundaries
pricing model
one case-study scenario

Do not start by building a large multi-tenant platform.

First prove that one merchant will pay to remove one repeated operational problem.

Read based on what you want to build

For a broad operational foundation, start with Crypto PaymentOps.

For execution and integrations, continue with the Payment Automation Studio.

For data consistency and recovery, read the Payment Reconciliation Tool.

For agent-facing operations, read the Crypto Payment Support Desk.

For higher-risk money distribution, study the Revenue Split and Payout System.

For a narrower path to market, choose the guide that matches your distribution:

Final takeaway

The developer opportunity is not simply adding crypto checkout.

It is building the operational products merchants need around payment:

controlled checkout
order activation
access management
reliable automation
payment reconciliation
customer support
reporting
revenue allocation
payout operations
repeatable agency deployment

OxaPay provides the underlying payment primitives.

The developer creates the merchant-specific system that turns those primitives into reliable business outcomes.

Start with one buyer.

Own one workflow.

Make one important business action reliable.

Then expand only after the product has solved a real operational problem.

Which of these 10 products would you build first, and which merchant would you build it for?

References

Full series

OxaPay technical references

Crypto Payment Reconciliation: The Layer Most Developers Forget

kevin.s — Thu, 09 Jul 2026 11:28:29 +0000

Crypto Payment Reconciliation: The Layer Most Developers Forget

Most developers treat crypto payment integration as a webhook problem.

Create an invoice.

Wait for the callback.

Update the order.

Move on.

That works until the first real production mismatch appears.

The gateway says an invoice is paid, but your database still says pending.

The customer has a transaction hash, but the order was never updated.

A webhook arrived, but your server returned 500.

A payment was completed after the invoice expired.

Support sees an unpaid order, finance sees received funds, and engineering has to open logs to understand what happened.

That is the moment you discover the missing layer:

Webhooks tell your system what changed. Reconciliation proves your system still agrees with reality.

Crypto payment reconciliation is the process of comparing your local payment state with external payment truth: the gateway, the blockchain, settlement records, order records, and ledger entries.

It is not optional.

It is what prevents small asynchronous failures from becoming lost revenue, incorrect fulfillment, duplicate credits, support chaos, and accounting gaps.

This article explains how to design crypto payment reconciliation from a developer’s perspective: state drift, source-of-truth boundaries, webhook failure, invoice lookup, transaction matching, audit trails, anomaly detection, repair jobs, settlement reconciliation, and the operational dashboards that make crypto payment systems trustworthy in production.

I’ll use OxaPay as one implementation reference where useful because its API exposes common reconciliation primitives such as invoice generation, track_id, signed webhooks, payment statuses, and payment lookup by track_id. The architecture itself applies to most crypto payment gateways.

The Short Version

A webhook-driven payment system asks:

Did we receive the event?

A reconciled payment system asks:

Does every system agree on what happened?

That is a much stronger question.

A reliable crypto payment system must compare at least these records:

local order
local invoice
local payment events
gateway payment status
blockchain transaction data
merchant balance / settlement record
business fulfillment state

If those records disagree, the system needs to detect the mismatch, repair it safely when possible, or send it to manual review with enough context for support.

That is reconciliation.

Why Reconciliation Exists

Crypto payments are asynchronous.

The user pushes funds from a wallet or exchange.

The gateway monitors the blockchain.

The gateway sends callbacks to your server.

Your server updates local state.

Your order system triggers fulfillment.

Your finance system records revenue.

Your settlement system moves funds later.

That flow contains many boundaries.

wallet → blockchain
blockchain → gateway
gateway → webhook
webhook → database
database → order system
order system → fulfillment
payment balance → accounting

Every boundary can fail.

A webhook may be delayed.

Your server may be down.

A queue worker may crash.

A database transaction may roll back.

A customer may pay after expiration.

A duplicate event may be ignored incorrectly.

A provider status may update after your local status freezes.

A paid invoice may not trigger fulfillment.

A fulfilled order may not have a final payment record.

Reconciliation exists because no distributed payment system should assume that one event path is perfect.

The Most Common Production Mismatch

The most common mismatch looks like this:

Gateway: invoice paid
Merchant DB: payment pending
WooCommerce / Shopify / app order: unpaid
Customer: already sent funds
Support: confused

This can happen even when every system is “working.”

Maybe the webhook was sent, but your endpoint timed out.

Maybe your endpoint received the webhook, but a later database write failed.

Maybe your code updated the payment table but did not update the order table.

Maybe the provider retried the callback, but your idempotency logic incorrectly treated it as already processed.

Maybe the customer paid after expiration and your system ignored the event.

Without reconciliation, this mismatch stays hidden until the customer complains.

With reconciliation, the system finds it automatically.

Reconciliation Is Not Polling Instead of Webhooks

Some developers hear “reconciliation” and think:

Should I just poll the payment API instead of using webhooks?

No.

That is the wrong framing.

Webhooks and reconciliation solve different problems.

Layer	Purpose
Webhooks	Fast event delivery
Reconciliation	Consistency verification and repair

Webhooks are for responsiveness.

Reconciliation is for correctness.

A good system uses both.

Webhook path:
payment event happens
→ provider sends callback
→ merchant updates state quickly

Reconciliation path:
scheduled job checks unresolved or risky records
→ compares local state with provider state
→ repairs mismatch or flags review

Webhooks are the primary update mechanism.

Reconciliation is the safety net.

The Reconciliation Mindset

A payment reconciliation system should be designed around one principle:

Every important payment fact must be independently verifiable later.

That means you should be able to answer:

Which order was this payment for?
Which invoice did the gateway create?
Which provider reference identifies it?
Which webhook events arrived?
Which transaction hash was detected?
Which asset and network were used?
What amount was expected?
What amount was received?
What did the gateway report?
What did our database record?
What business action did we take?
Was fulfillment triggered?
Was settlement completed?
Did finance record it?

If you cannot answer these questions from stored data, reconciliation will become guesswork.

Guesswork does not scale.

The Systems That Need to Agree

Crypto payment reconciliation is not only “database vs provider.”

It often involves several systems.

1. Order system
2. Invoice/payment table
3. Webhook event table
4. Gateway payment API
5. Blockchain transaction data
6. Fulfillment system
7. Merchant balance / settlement records
8. Accounting or reporting layer

A small merchant may only have the first four.

A larger platform may have all eight.

The architecture should make each layer explicit.

A Practical Reconciliation Model

At minimum, store these local records:

orders
payments / invoices
payment_events
payment_transactions
settlements or balance movements

You do not need a huge system on day one, but you need enough structure to compare states.

A minimal payment table might look like this:

CREATE TABLE crypto_payments (
  id BIGSERIAL PRIMARY KEY,
  order_id TEXT NOT NULL,
  provider TEXT NOT NULL,
  provider_track_id TEXT NOT NULL UNIQUE,
  pricing_currency TEXT NOT NULL,
  expected_amount NUMERIC(18, 8) NOT NULL,
  received_amount NUMERIC(36, 18) NULL,
  selected_asset TEXT NULL,
  selected_network TEXT NULL,
  gateway_status TEXT NULL,
  payment_status TEXT NOT NULL,
  business_status TEXT NOT NULL,
  payment_url TEXT NULL,
  expires_at TIMESTAMP NULL,
  paid_at TIMESTAMP NULL,
  last_provider_check_at TIMESTAMP NULL,
  last_reconciled_at TIMESTAMP NULL,
  reconciliation_status TEXT NOT NULL DEFAULT 'not_checked',
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);

A webhook event table:

CREATE TABLE crypto_payment_events (
  id BIGSERIAL PRIMARY KEY,
  provider TEXT NOT NULL,
  provider_track_id TEXT NOT NULL,
  event_hash TEXT NOT NULL UNIQUE,
  provider_status TEXT NULL,
  raw_payload JSONB NOT NULL,
  received_at TIMESTAMP NOT NULL DEFAULT NOW(),
  processed_at TIMESTAMP NULL,
  processing_status TEXT NOT NULL DEFAULT 'received',
  processing_error TEXT NULL
);

A transaction table:

CREATE TABLE crypto_payment_transactions (
  id BIGSERIAL PRIMARY KEY,
  payment_id BIGINT NOT NULL,
  tx_hash TEXT NOT NULL,
  asset TEXT NOT NULL,
  network TEXT NOT NULL,
  expected_amount NUMERIC(36, 18) NULL,
  received_amount NUMERIC(36, 18) NULL,
  confirmations INTEGER NULL,
  tx_status TEXT NOT NULL,
  detected_at TIMESTAMP NULL,
  confirmed_at TIMESTAMP NULL,
  UNIQUE (payment_id, tx_hash)
);

These tables give your system enough memory to understand what happened.

Without this structure, reconciliation has nothing reliable to compare.

Source of Truth Is Not One Thing

A common mistake is asking:

What is the source of truth?

In payment systems, the better question is:

Source of truth for what?

Different systems own different facts.

Fact	Likely Source of Truth
Customer ordered item	Merchant order system
Invoice was created	Payment provider + local invoice table
Provider payment status	Gateway API
Blockchain transaction exists	Blockchain / gateway monitor
Webhook was received	Local event table
Order was fulfilled	Merchant fulfillment system
Funds were settled	Gateway balance / settlement ledger
Revenue was recognized	Accounting system

Trying to force one system to be the source of truth for everything creates bad architecture.

Reconciliation works by comparing specialized truths.

Local State vs External Truth

Your database may say:

payment_status = waiting_for_payment

The gateway may say:

status = paid

That does not automatically mean your database is wrong.

It means your database is stale.

The reconciliation system needs to ask:

Can we safely move local status from waiting_for_payment to paid?
Was the payment already fulfilled?
Was the order cancelled?
Did the invoice expire?
Was the payment underpaid?
Is this a duplicate provider result?
Does this require manual review?

A reconciliation job should not blindly overwrite state.

It should apply safe transitions.

The Reconciliation Loop

A basic reconciliation loop looks like this:

1. Select payments that need checking
2. Fetch external payment truth
3. Normalize external status
4. Compare with local state
5. Decide whether to repair, ignore, or flag
6. Apply idempotent state transition
7. Record reconciliation result
8. Emit alerts or admin notes if needed

In code terms:

async function reconcileOpenPayments() {
  const payments = await findPaymentsNeedingReconciliation();

  for (const payment of payments) {
    try {
      const providerPayment = await fetchProviderPayment(payment.provider_track_id);

      const externalStatus = normalizeProviderStatus(providerPayment.data.status);
      const nextStatus = mapGatewayStatusToPaymentStatus(externalStatus);

      const decision = decideReconciliationAction({
        localPayment: payment,
        providerPayment: providerPayment.data,
        nextStatus
      });

      await applyReconciliationDecision(payment, decision, providerPayment.data);
    } catch (error) {
      await recordReconciliationFailure(payment, error);
    }
  }
}

The important part is not the language.

The important part is the decision layer.

Reconciliation should not be:

fetch provider status → overwrite local status

It should be:

fetch provider status → compare → validate transition → repair safely

Which Payments Should Be Reconciled?

You do not need to check every payment forever.

Start with records that are likely to drift.

Good candidates:

created
waiting_for_payment
payment_detected
confirming
underpaid
manual_review
expired_recently
paid_but_not_fulfilled
fulfilled_but_payment_not_final
webhook_failed
event_received_but_not_processed
settlement_pending

You can define selection rules like:

SELECT *
FROM crypto_payments
WHERE payment_status IN (
  'created',
  'waiting_for_payment',
  'payment_detected',
  'confirming',
  'underpaid',
  'manual_review'
)
AND created_at > NOW() - INTERVAL '7 days';

Add special checks for stale states:

SELECT *
FROM crypto_payments
WHERE payment_status = 'confirming'
AND updated_at < NOW() - INTERVAL '30 minutes';

And for suspicious business mismatches:

SELECT *
FROM crypto_payments
WHERE payment_status = 'paid'
AND business_status != 'fulfilled'
AND paid_at < NOW() - INTERVAL '10 minutes';

That last query is powerful.

It catches payments that succeeded but did not trigger the expected business action.

Reconciliation Frequency

Reconciliation does not need to run at the same frequency for every payment.

Use different schedules for different risk zones.

Payment Group	Suggested Frequency
newly created invoices	every 1–2 minutes
payment detected / confirming	every 1–5 minutes
underpaid / manual review	every 10–30 minutes
expired within last few hours	every 10–30 minutes
paid but not fulfilled	every few minutes
settlement pending	hourly or daily
historical audit	daily

The goal is not to overload the provider API.

The goal is to reduce the time that your system remains inconsistent.

Use backoff.

A payment that was created two minutes ago deserves more attention than a failed invoice from three weeks ago.

Avoid Infinite Reconciliation

A reconciliation system should not keep retrying forever with no strategy.

Store retry metadata.

ALTER TABLE crypto_payments
ADD COLUMN reconciliation_attempts INTEGER NOT NULL DEFAULT 0,
ADD COLUMN next_reconciliation_at TIMESTAMP NULL,
ADD COLUMN last_reconciliation_error TEXT NULL;

Then apply backoff:

attempt 1 → retry in 1 minute
attempt 2 → retry in 5 minutes
attempt 3 → retry in 15 minutes
attempt 4 → retry in 1 hour
attempt 5 → manual review

This prevents a broken payment from consuming resources forever.

It also makes stuck cases visible.

Mapping Gateway Statuses

Every provider has its own status vocabulary.

Your application should not scatter provider-specific strings throughout the codebase.

Normalize them.

Using OxaPay as an implementation reference, payment statuses may include values such as new, waiting, paying, paid, manual_accept, underpaid, refunding, refunded, and expired.

A simple mapper:

function mapGatewayStatusToPaymentStatus(status) {
  const normalized = String(status || "").toLowerCase();

  const map = {
    new: "created",
    waiting: "waiting_for_payment",
    paying: "payment_detected",
    paid: "paid",
    manual_accept: "paid_manual",
    underpaid: "underpaid",
    refunding: "refunding",
    refunded: "refunded",
    expired: "expired"
  };

  return map[normalized] || "manual_review";
}

This gives your system one internal language.

If you change providers later, most business logic remains stable.

Safe State Transitions

Reconciliation must respect valid state transitions.

Example:

const allowedTransitions = {
  created: [
    "waiting_for_payment",
    "payment_detected",
    "paid",
    "expired",
    "manual_review"
  ],
  waiting_for_payment: [
    "payment_detected",
    "paid",
    "underpaid",
    "expired",
    "manual_review"
  ],
  payment_detected: [
    "confirming",
    "paid",
    "underpaid",
    "manual_review"
  ],
  confirming: [
    "paid",
    "underpaid",
    "manual_review"
  ],
  underpaid: [
    "paid",
    "expired",
    "manual_review"
  ],
  expired: [
    "late_payment",
    "manual_review"
  ],
  late_payment: [
    "paid",
    "manual_review",
    "refunded"
  ],
  paid: [
    "refunding",
    "refunded"
  ],
  paid_manual: [
    "refunding",
    "refunded"
  ],
  refunding: [
    "refunded"
  ],
  refunded: [],
  manual_review: [
    "paid",
    "expired",
    "refunded"
  ]
};

function canTransition(from, to) {
  return from === to || allowedTransitions[from]?.includes(to);
}

Why allow expired → late_payment?

Because crypto payments can arrive after expiration.

The invoice may be expired from a checkout perspective, but money still moved.

A good reconciliation system makes that visible.

Decision Matrix

Reconciliation should produce decisions, not just updates.

Example:

Local State	Provider State	Business Context	Decision
`waiting_for_payment`	`paid`	order still active	repair to `paid`, trigger fulfillment once
`waiting_for_payment`	`expired`	no transaction	mark expired
`expired`	`paid`	late payment allowed	move to `late_payment` or `paid` based on policy
`paid`	`paid`	already fulfilled	no-op
`paid`	`refunded`	refund confirmed	update refund status
`underpaid`	`paid`	remaining amount completed	repair to `paid`
`paid`	`underpaid`	impossible regression	flag manual review
`created`	`paid`	webhook missed	repair to `paid`, record missed event
`paid`	provider not found	provider error	retry later, do not downgrade
`fulfilled` order	unpaid provider	serious mismatch	manual review

This table is where production maturity shows.

A reconciliation system should be careful with destructive changes.

For example, do not move a paid order back to unpaid just because one provider lookup fails.

Fetching Provider Payment Information

Most payment gateways expose some way to look up a payment by provider reference.

In OxaPay, the Payment Information endpoint lets developers retrieve payment details by track_id.

Example request:

curl -X GET https://api.oxapay.com/v1/payment/184747701 \
  -H "merchant_api_key: $OXAPAY_MERCHANT_API_KEY" \
  -H "Content-Type: application/json"

Example wrapper:

async function fetchOxaPayPayment(trackId) {
  const response = await fetch(`https://api.oxapay.com/v1/payment/${trackId}`, {
    method: "GET",
    headers: {
      "merchant_api_key": process.env.OXAPAY_MERCHANT_API_KEY,
      "Content-Type": "application/json"
    }
  });

  const result = await response.json();

  if (!response.ok || result.status !== 200) {
    throw new Error(`Payment lookup failed: ${JSON.stringify(result.error)}`);
  }

  return result.data;
}

In your own abstraction, do not let the rest of the system depend on one provider response shape.

Wrap it:

async function fetchProviderPayment(provider, trackId) {
  if (provider === "oxapay") {
    const data = await fetchOxaPayPayment(trackId);

    return {
      provider: "oxapay",
      trackId,
      gatewayStatus: data.status,
      expectedAmount: data.amount,
      receivedAmount: data.received_amount,
      asset: data.currency,
      network: data.network,
      txHash: data.tx_hash,
      raw: data
    };
  }

  throw new Error(`Unsupported provider: ${provider}`);
}

This makes reconciliation easier to maintain if your payment infrastructure changes later.

Repairing State Safely

When reconciliation finds a mismatch, repair should be idempotent.

Example:

async function applyReconciliationDecision(payment, decision, providerPayment) {
  await db.transaction(async (trx) => {
    await trx.reconciliation_runs.insert({
      payment_id: payment.id,
      previous_status: payment.payment_status,
      provider_status: providerPayment.gatewayStatus,
      decision: decision.type,
      reason: decision.reason,
      raw_provider_payload: providerPayment.raw
    });

    if (decision.type === "noop") {
      return;
    }

    if (decision.type === "manual_review") {
      await trx.crypto_payments.update({
        id: payment.id,
        reconciliation_status: "manual_review",
        last_reconciled_at: new Date()
      });

      return;
    }

    if (decision.type === "repair_status") {
      await trx.crypto_payments.update({
        id: payment.id,
        payment_status: decision.nextStatus,
        gateway_status: providerPayment.gatewayStatus,
        last_provider_check_at: new Date(),
        last_reconciled_at: new Date(),
        reconciliation_status: "repaired"
      });

      if (decision.nextStatus === "paid") {
        await fulfillOrderOnce(trx, payment.order_id, payment.id);
      }
    }
  });
}

The fulfillOrderOnce function matters.

Reconciliation may discover a missed paid status.

That does not mean it should blindly trigger fulfillment again.

Use a uniqueness rule.

CREATE TABLE order_fulfillments (
  id BIGSERIAL PRIMARY KEY,
  order_id TEXT NOT NULL UNIQUE,
  payment_id BIGINT NOT NULL,
  fulfilled_at TIMESTAMP NOT NULL DEFAULT NOW()
);

Then fulfillment becomes safe to call from both webhook processing and reconciliation.

Reconciliation Run Table

Store reconciliation runs.

Do not just update payment rows silently.

Example:

CREATE TABLE payment_reconciliation_runs (
  id BIGSERIAL PRIMARY KEY,
  payment_id BIGINT NOT NULL,
  provider TEXT NOT NULL,
  provider_track_id TEXT NOT NULL,
  local_status_before TEXT NOT NULL,
  provider_status TEXT NULL,
  decision TEXT NOT NULL,
  reason TEXT NULL,
  raw_provider_payload JSONB NULL,
  created_at TIMESTAMP NOT NULL DEFAULT NOW()
);

This table gives you an audit trail.

It answers:

When did we check this payment?
What did the provider say?
What did our system say before the check?
What did reconciliation decide?
Did we repair anything?
Why was it sent to manual review?

This is extremely useful for production support.

Webhook Events and Reconciliation Should Share the Same State Engine

Do not build two separate status systems:

webhook handler status logic
reconciliation job status logic

That creates divergence.

Both should call the same internal state engine.

webhook event
        |
        v
normalize provider status
        |
        v
apply payment transition
        |
        v
business side effects

reconciliation lookup
        |
        v
normalize provider status
        |
        v
apply payment transition
        |
        v
business side effects

The source is different.

The transition engine should be the same.

That makes behavior consistent whether the update came from a webhook or from reconciliation.

Reconciliation and Idempotency Work Together

Reconciliation will find the same paid payment more than once.

That is normal.

Your system should handle it.

A payment already marked paid should not trigger fulfillment again.

An already recorded transaction should not be duplicated.

An already refunded order should not be refunded twice.

Idempotency rules should exist at multiple levels:

Level	Idempotency Rule
Webhook event	unique event hash
Transaction	unique provider + tx hash
Payment state	safe transition guard
Fulfillment	unique order fulfillment record
Credit balance	unique ledger entry reference
Refund	unique refund reference
Reconciliation	no repeated side effects for same state

Idempotency is not one feature.

It is a pattern across the whole payment system.

Reconciling Transactions

Payment status is not the only thing to reconcile.

You may also need transaction reconciliation.

For each provider payment, compare transaction-level data:

tx_hash
asset
network
received_amount
confirmation count
detected_at
confirmed_at

If the provider reports a transaction that your local system does not have, insert it.

If your local transaction exists but confirmation status changed, update it.

Example:

async function reconcileTransactions(payment, providerPayment) {
  const transactions = providerPayment.transactions || [];

  for (const tx of transactions) {
    await db.crypto_payment_transactions.upsert({
      payment_id: payment.id,
      tx_hash: tx.hash,
      asset: tx.asset,
      network: tx.network,
      received_amount: tx.amount,
      confirmations: tx.confirmations,
      tx_status: tx.status,
      detected_at: tx.detected_at,
      confirmed_at: tx.confirmed_at
    }, {
      conflict: ["payment_id", "tx_hash"]
    });
  }
}

One invoice can have multiple transactions.

Your reconciliation model should allow that.

Reconciling Amounts

Amount reconciliation is subtle in crypto.

A merchant may price an invoice in fiat, while the customer pays in crypto.

You need to compare:

expected commercial amount
expected crypto amount
received crypto amount
received fiat-equivalent amount
fees
settlement amount

At minimum, store:

pricing_currency
expected_amount
selected_asset
selected_network
expected_crypto_amount
received_crypto_amount
received_fiat_value

Then detect cases:

Case	Meaning
received = expected	normal paid
received < expected	underpaid
received > expected	overpaid
received after expiration	late payment
received on wrong network	support/recovery issue
received in multiple txs	aggregate before deciding
provider says paid but local amount missing	repair local amount

Never rely only on a boolean paid.

Payment amount is part of the truth.

Reconciling Orders

A payment can be paid while the order is not fulfilled.

That is a mismatch.

A payment can be unpaid while the order is fulfilled.

That is a more serious mismatch.

Order reconciliation checks business effects.

Examples:

SELECT *
FROM crypto_payments p
JOIN orders o ON o.id = p.order_id
WHERE p.payment_status = 'paid'
AND o.fulfillment_status = 'not_fulfilled'
AND p.paid_at < NOW() - INTERVAL '10 minutes';

And the opposite:

SELECT *
FROM crypto_payments p
JOIN orders o ON o.id = p.order_id
WHERE p.payment_status NOT IN ('paid', 'paid_manual')
AND o.fulfillment_status = 'fulfilled';

The first case may require repair.

The second case requires investigation.

Reconciliation is not only about fixing pending payments.

It also catches dangerous business inconsistencies.

Reconciling Settlement

Payment completion and settlement are different.

A customer may pay an invoice, but funds may still need to be:

credited to merchant balance
converted
withdrawn
posted to ledger
matched to accounting records

For small integrations, settlement reconciliation may be manual.

For larger systems, it needs to be explicit.

Separate these fields:

payment_status
settlement_status
ledger_status

Example:

Status Type	Example
`payment_status`	`paid`
`settlement_status`	`credited_to_balance`
`ledger_status`	`posted`

A paid invoice that never appears in finance reporting is still a problem.

It may not affect the customer, but it affects the business.

Handling Late Payments

Late payments are a major reason reconciliation exists.

A customer may pay after invoice expiration because:

they used an exchange withdrawal
they waited too long
the blockchain was congested
the payment page expired before the transaction appeared
they copied the address and paid later

The provider may later show:

expired invoice received funds

Your local system may show:

order cancelled

Reconciliation should detect this and move the payment into a visible state.

expired
→ late_payment
→ manual_review

Example decision:

function decideLatePayment(payment, providerPayment) {
  if (payment.payment_status === "expired" && providerPayment.gatewayStatus === "paid") {
    return {
      type: "manual_review",
      nextStatus: "late_payment",
      reason: "payment_received_after_expiration"
    };
  }

  return null;
}

Do not silently ignore late money movement.

Even if the order should not be fulfilled, finance and support need to know funds arrived.

Handling Underpayments

Underpaid invoices should not disappear into failure.

Reconciliation should keep checking if the provider allows additional payments or if the customer completes the remaining amount later.

Example:

Provider: underpaid
Local: waiting_for_payment
Decision: move to underpaid, notify customer/support

Later:

Provider: paid
Local: underpaid
Decision: repair to paid, trigger fulfillment once

This is why underpaid → paid should be a valid transition.

A strict state machine that treats underpaid as terminal creates unnecessary manual work.

Handling Overpayments

Overpayment reconciliation should record the excess.

Do not simply mark paid and discard the difference.

Possible handling:

mark invoice paid
record overpaid amount
create admin note
optionally create refund/credit task

Store:

expected_amount
received_amount
overpaid_amount
overpayment_policy

This matters for accounting and customer trust.

Handling Provider API Failures

A reconciliation job depends on provider API availability.

That API can fail.

Your job should not panic.

Classify provider errors:

Error Type	Handling
timeout	retry with backoff
429 rate limit	slow down
5xx provider error	retry later
401 auth error	alert immediately
payment not found	retry if recent, manual review if persistent
malformed response	alert engineering
network error	retry later

Do not downgrade payments because one lookup failed.

A provider error means:

external truth unavailable right now

It does not mean:

payment failed

Rate Limits and Batching

Reconciliation can create unnecessary API load if implemented carelessly.

Good practices:

reconcile only unresolved or risky payments
prioritize recent invoices
use exponential backoff
stop checking terminal states after a safe window
batch where provider supports it
cache recent lookup results briefly
avoid multiple workers reconciling the same payment at once
respect provider rate limits

Use locks.

Example:

ALTER TABLE crypto_payments
ADD COLUMN reconciliation_locked_until TIMESTAMP NULL;

Worker selection:

SELECT *
FROM crypto_payments
WHERE next_reconciliation_at <= NOW()
AND (
  reconciliation_locked_until IS NULL
  OR reconciliation_locked_until < NOW()
)
LIMIT 100;

Then lock selected rows before processing.

Without locks, multiple workers may reconcile the same payment and create duplicate work.

Manual Review Is a Feature

Manual review should not be treated as failure.

It is a valid state.

Some cases should not be repaired automatically:

provider says paid, order was already refunded
provider status regressed unexpectedly
payment arrived after order cancellation
wrong network suspected
large overpayment
provider data incomplete
transaction hash conflicts with another invoice
fulfilled order has unpaid payment status

Manual review should include context.

A good review record includes:

order_id
provider_track_id
local_status
provider_status
expected_amount
received_amount
asset
network
tx_hash
reason
recommended action
raw provider payload

Support should not see only:

manual_review

They should see why.

Alerting Rules

Not every mismatch needs a pager.

But some do.

Useful alert categories:

Alert	Severity
paid provider status but local pending for more than 10 minutes	medium
fulfilled order with unpaid payment status	high
webhook signature failures spike	high
provider API authentication failure	critical
reconciliation job not running	high
many expired invoices later paid	medium
underpayment rate increasing	medium
duplicate webhook rate unusually high	low/medium
settlement mismatch	high
manual review queue growing	medium

Metrics should support alerts.

Do not rely only on logs.

Reconciliation Metrics

Track these metrics:

open_payments_count
stale_pending_count
paid_not_fulfilled_count
fulfilled_not_paid_count
webhook_failed_count
reconciliation_run_count
reconciliation_repair_count
manual_review_count
provider_lookup_failure_count
average_time_to_payment
average_time_to_reconciliation_repair
underpayment_rate
late_payment_rate
settlement_mismatch_count

These metrics tell you whether your payment system is healthy.

For example:

high stale_pending_count may mean callbacks are failing
high paid_not_fulfilled_count may mean order transition logic is broken
high manual_review_count may mean policies are unclear
high provider_lookup_failure_count may mean API or auth issues
high late_payment_rate may mean invoice lifetime is too short

Reconciliation is not just repair.

It is observability.

Admin and Support View

A reconciliation system should surface useful information to humans.

For each payment, show:

order_id
provider
track_id
payment_url
gateway_status
payment_status
business_status
expected_amount
received_amount
asset
network
tx_hash
invoice_created_at
expires_at
paid_at
last_webhook_at
last_provider_check_at
last_reconciled_at
reconciliation_status
manual_review_reason

Also show the timeline:

12:00 invoice created
12:03 webhook received: waiting
12:06 webhook received: paying
12:08 webhook failed during processing
12:12 reconciliation checked provider: paid
12:12 local state repaired: waiting_for_payment → paid
12:12 order fulfillment triggered

This kind of timeline reduces support time dramatically.

It also reduces pressure on engineering.

Example Implementation: OxaPay as a Reference

OxaPay is useful as an implementation reference because it exposes the core primitives a reconciliation system needs.

The Generate Invoice endpoint creates a payment request and returns a track_id and payment_url.

The Webhook documentation explains callback delivery, HMAC SHA-512 validation over the raw POST body, and the need to return HTTP 200 with ok after successful processing.

The Payment Status Table gives developers provider-side statuses that can be mapped into internal payment states.

The Payment Information endpoint lets your backend retrieve payment details by track_id, which is exactly what reconciliation needs.

The important point is not that reconciliation belongs to one provider.

The important point is that reliable crypto payment systems need these primitives:

provider reference
signed event delivery
status table
payment lookup
local event storage
idempotent state transitions
manual review path
reconciliation job

Whether you use OxaPay, another gateway, or your own infrastructure, those primitives still need to exist.

A Minimal Reconciliation Architecture

A practical architecture looks like this:

Webhook Receiver
  |
  | signed payment events
  v
Event Store
  |
  | raw events, hashes, processing status
  v
Payment State Engine
  |
  | normalize status, apply transitions
  v
Order / Business Layer
  |
  | fulfill, hold, refund, notify
  ^
  |
Reconciliation Worker
  |
  | provider lookup by track_id
  v
Provider Payment API

The key design principle:

Webhooks and reconciliation should both feed the same payment state engine.

Do not build separate logic paths.

Minimal Reconciliation Pseudocode

Here is the whole system in compact form:

async function runReconciliationBatch() {
  const payments = await selectPaymentsForReconciliation();

  for (const payment of payments) {
    await reconcileOnePayment(payment);
  }
}

async function reconcileOnePayment(payment) {
  const providerPayment = await fetchProviderPayment(
    payment.provider,
    payment.provider_track_id
  );

  const nextStatus = mapGatewayStatusToPaymentStatus(
    providerPayment.gatewayStatus
  );

  const decision = decideReconciliationAction({
    payment,
    providerPayment,
    nextStatus
  });

  await applyDecisionIdempotently({
    payment,
    providerPayment,
    decision
  });
}

function decideReconciliationAction({ payment, providerPayment, nextStatus }) {
  if (payment.payment_status === nextStatus) {
    return { type: "noop", reason: "already_consistent" };
  }

  if (!canTransition(payment.payment_status, nextStatus)) {
    return {
      type: "manual_review",
      reason: "invalid_state_transition",
      nextStatus
    };
  }

  if (payment.payment_status === "expired" && nextStatus === "paid") {
    return {
      type: "manual_review",
      reason: "late_payment_after_expiration",
      nextStatus: "late_payment"
    };
  }

  if (nextStatus === "paid") {
    return {
      type: "repair_and_fulfill_once",
      reason: "provider_paid_local_not_paid",
      nextStatus
    };
  }

  return {
    type: "repair_status",
    reason: "safe_state_repair",
    nextStatus
  };
}

This is not complete production code, but the shape is right.

It has:

selection
provider lookup
normalization
decision
safe transition
manual review
idempotent repair

That is the core of reconciliation.

Testing Reconciliation

Test reconciliation directly.

Do not only test webhooks.

Important test cases:

provider paid, local pending
provider paid, local expired
provider underpaid, local waiting
provider paid, local underpaid
provider expired, local waiting
provider refunded, local paid
provider lookup timeout
provider auth failure
provider not found
order fulfilled, payment not paid
payment paid, order not fulfilled
duplicate reconciliation run
two workers select same payment
manual review case
late payment after expiration

Each case should have an expected decision.

If you cannot define the expected decision, your production system will behave inconsistently.

Production Checklist

Before shipping crypto payment reconciliation, verify this:

Every invoice stores provider_track_id
Every webhook event is stored with a unique hash
Provider statuses are normalized in one place
Payment state transitions are guarded
Fulfillment is idempotent
Paid payments can be repaired if webhook fails
Expired invoices can detect late payments
Underpaid invoices can later become paid
Provider lookup failures do not downgrade local state
Manual review has reasons and context
Reconciliation runs are logged
Reconciliation has backoff and retry limits
Workers use locks or safe selection
Metrics track stale states and repairs
Support can search by order_id, track_id, tx_hash
Settlement state is separate from payment state
Webhooks and reconciliation use the same state engine

This checklist is the difference between:

We hope callbacks arrive.

and:

We can prove our payment state is correct.

Final Thought

Crypto payment reconciliation is easy to ignore because the first integration usually works without it.

The first invoice is created.

The first webhook arrives.

The first order is marked paid.

Everything looks done.

But production is not the first transaction.

Production is the thousandth transaction, the missed callback, the late payment, the underpaid invoice, the duplicate webhook, the customer with a transaction hash, the order stuck in pending, and the finance report that does not match the gateway balance.

That is where reconciliation matters.

Webhooks make crypto payment systems responsive.

Reconciliation makes them trustworthy.

If you are building a crypto payment integration, do not stop at:

Can we receive payment events?

Ask the harder question:

Can we prove later that our local payment state still matches what actually happened?

That question is where serious payment infrastructure begins.

DEV Community: kevin.s

Build a Cross-Border Crypto Payment Stack for Digital Sellers

Cross-border is more than buyer location

What this product is

How this differs from PaymentOps

Choose one digital seller niche

Define the commercial transaction

Separate the currency concepts

Pricing currency

Payment asset

Payment network

Received asset

Reporting currency

Recommended architecture

A cross-border data model

Create the order before the invoice

Create an OxaPay hosted invoice

Hosted invoice or white-label?

Use hosted invoices when

Use white-label when

Configure payment methods dynamically

Stablecoin-first is a UX policy

Validate OxaPay callbacks

Do not fulfill on paying

Verify before digital delivery

Deliver a software license exactly once

Other fulfillment adapters

Make delivery links temporary

Build a localized customer status page

Waiting for payment

Payment detected

Payment confirmed

Delivered

Expired

Under review

Localize the high-friction content first

Use UTC internally

Apply regional policies before creating payment

Treat late payments as exceptions

Handle duplicate payments deliberately

Recover missed events with Payment History

Reconcile business outcomes

Build support around evidence

Use customer-safe support templates

Payment detected

Paid but not delivered

Expired payment session

Payment cannot be matched

Build reporting records at payment time

Optional payouts belong in a separate module

Security baseline

Compliance and policy boundaries

The MVP

Production expansion

Product positioning

What makes this a real product?

Final takeaway

Related articles

References

OxaPay

Build a Crypto Payment Support Desk

The problem is not payment status

Where the Support Desk fits

Design around support questions

The case workspace

Customer and order context

Payment context

Evidence timeline

Diagnosis

Safe actions

Add support-specific tables

Build a support case snapshot

Classify cases automatically

Use an evidence-based case taxonomy

Treat OxaPay webhooks as evidence

Add a provider refresh action

Use Payment History for recovery

Make support actions safe

Retry fulfillment idempotently

Give agents customer-safe responses

Do not fulfill on `paying`