Minimal Checkout Relay API

The minimal theme is APay's single payment relay. APay creates the payment order, collects the actual payment currency, and stores an immutable conversion snapshot. External relay orders notify Qingpu after payment; APay-owned wallet top-ups are credited locally and never emit a downstream credit event.

APay relay orders never run the normal APay product fulfillment engine. External requests use a hidden minimal-checkout-recharge carrier product; an optional source product is retained only as business context.

Endpoints

  • POST /api/minimal/checkout/create
  • GET /api/minimal/checkout/consume?token=...
  • GET /api/minimal/checkout/status
  • POST /api/admin/minimal/checkout/orders/{orderId}/retry-notify (admin)
  • POST /api/orders/topup (signed-in APay wallet top-up)
  • GET /api/users/wallet/topups (signed-in user's top-up records)
  • GET /api/admin/topups and POST /api/admin/topups/retry (admin)

Secret And Signature

The shared secret is read from setting minimal_checkout_secret, with MINIMAL_CHECKOUT_SECRET as the environment fallback. Signed endpoints return 503 when neither is configured.

create and status require:

X-APay-Timestamp: 1785312345678
X-APay-Signature: <hex-hmac-sha256>

The timestamp must be within five minutes of server time. The request signature is:

HMAC_SHA256(secret, timestamp + "\n" + method + "\n" + path_with_sorted_query + "\n" + sha256(raw_body))

method is uppercase. Query parameters are sorted by key and value, and the signature query parameter is excluded. For a bodyless GET, hash the empty string.

Create A Relay Order

Endpoint: POST /api/minimal/checkout/create

{
  "externalOrderId": "QP-20260728-0001",
  "productId": 12,
  "amount": 13.75,
  "currency": "USD",
  "sourceAmount": 99,
  "sourceCurrency": "CNY",
  "exchangeRate": 0.13888889,
  "rechargeAmount": 99,
  "rechargeCurrency": "CNY",
  "balanceType": "cash",
  "customerEmail": "buyer@example.com",
  "notifyUrl": "https://qingpu.example.com/api/payment/notify",
  "returnUrl": "https://qingpu.example.com/payment/success",
  "cancelUrl": "https://qingpu.example.com/payment/cancel",
  "productName": "Qingpu Pro Monthly",
  "attach": {
    "userId": 1024,
    "businessType": "subscription",
    "channel": "qingpu-web"
  }
}
FieldTypeRequiredDescription
externalOrderIdstringYesQingpu business order ID and downstream idempotency key.
productIdnumberNoSource APay product used only for validation and business context.
amountnumberConditionalActual amount charged by the payment gateway, including 0 for a free order. Required when productId is omitted.
currencystringNoActual payment currency. Defaults to CNY.
sourceAmountnumberNoOriginal amount before conversion.
sourceCurrencystringNoOriginal/base currency before conversion.
exchangeRatenumberNoLocked rate snapshot where amount = sourceAmount * exchangeRate.
rechargeAmountnumberNoAmount Qingpu must credit or use for final fulfillment.
rechargeCurrencystringNoQingpu accounting/recharge currency.
balanceTypecash or grantNoTarget Qingpu balance pool. Defaults to cash.
customerEmailstringNoBuyer contact email.
notifyUrlstringNoDedicated server callback URL. Defaults to the minimal checkout admin setting.
returnUrlstringNoBrowser success redirect.
cancelUrlstringNoBrowser cancel/failure redirect.
productNamestringNoSource product display snapshot.
productDescriptionstringNoSource product description snapshot.
productImageUrlstringNoSource product image snapshot.
productMetaobjectNoTrusted source product metadata snapshot.
attachobjectNoBusiness context echoed in status and paid notifications.

If rechargeAmount is omitted, APay resolves it from trusted product metadata, sourceAmount, or the payment amount in that order. Do not derive the recharge amount again from current exchange-rate settings after the order has been created.

Response

{
  "code": 0,
  "message": "Checkout order created",
  "data": {
    "orderId": "TU20260728123456AB12CD34",
    "externalOrderId": "QP-20260728-0001",
    "checkoutUrl": "https://apay.example.com/api/minimal/checkout/consume?token=...",
    "amount": 13.75,
    "currency": "USD",
    "sourceAmount": 99,
    "sourceCurrency": "CNY",
    "exchangeRate": 0.13888889,
    "rechargeAmount": 99,
    "rechargeCurrency": "CNY",
    "balanceType": "cash",
    "isFreeOrder": false,
    "reused": false,
    "expiresAt": "2026-07-28T13:05:00.000Z"
  }
}

Idempotency

externalOrderId is unique within the minimal_checkout source. APay enforces this with the indexed (orders.source, orders.external_order_id) key, including concurrent create requests. A retry returns the existing order and a fresh checkout URL with reused: true.

APay returns 409 when a retry conflicts with the existing immutable payment facts, such as product, customer, callback URLs, amount, currency, or recharge amount/currency.

An order whose payment amount is 0 is marked paid and relayed immediately. The response contains isFreeOrder: true and expiresAt: null; Qingpu must still apply the same externalOrderId idempotency rule when processing the notification.

Qingpu must also use externalOrderId as its credit/fulfillment idempotency key. HTTP retries and lost responses must never apply the same recharge twice.

Consume Checkout URL

GET /api/minimal/checkout/consume?token=... is a browser endpoint. It verifies the signed token, restores the order's visitor_id cookie, and redirects to /payment/{orderId}. Open the returned checkoutUrl directly; do not call it from the Qingpu server.

Query Status

Endpoint: GET /api/minimal/checkout/status

Pass either orderId or externalOrderId. The response includes the payment fields, source conversion snapshot, recharge fields, callback state, redirects, and attach business context.

{
  "code": 0,
  "data": {
    "orderId": "TU20260728123456AB12CD34",
    "externalOrderId": "QP-20260728-0001",
    "productId": 12,
    "productName": "Qingpu Pro Monthly",
    "amount": 13.75,
    "currency": "USD",
    "sourceAmount": 99,
    "sourceCurrency": "CNY",
    "exchangeRate": 0.13888889,
    "rechargeAmount": 99,
    "rechargeCurrency": "CNY",
    "balanceType": "cash",
    "status": "none",
    "payStatus": "pending",
    "payMethod": "alipay",
    "notify": null,
    "attach": {
      "userId": 1024,
      "businessType": "subscription",
      "channel": "qingpu-web"
    }
  }
}

When payment is claimed successfully, APay marks the relay order delivered and sends exactly one downstream event channel:

  • An APay-owned wallet top-up (attach.walletOwner: "apay") is credited to local user_wallets and sends neither downstream channel.
  • If notifyUrl exists, minimal.checkout.paid is authoritative.
  • If no notifyUrl exists, APay falls back to the legacy order.paid event bus.
  • A failed dedicated notification does not fall through to the legacy channel, because the receiver may already have applied the credit before its response was lost.

This behavior applies equally to gateway callbacks, payment-query recovery, admin manual confirmation, and zero-amount relay orders.

X-APay-Event: minimal.checkout.paid
X-APay-Timestamp: 1785312345678
X-APay-Signature: <hex-hmac-sha256>
Content-Type: application/json

The outbound signature is:

HMAC_SHA256(secret, timestamp + "\n" + raw_json_body)
{
  "event": "minimal.checkout.paid",
  "timestamp": "2026-07-28T12:40:00.000Z",
  "data": {
    "orderId": "TU20260728123456AB12CD34",
    "externalOrderId": "QP-20260728-0001",
    "amount": 13.75,
    "currency": "USD",
    "sourceAmount": 99,
    "sourceCurrency": "CNY",
    "exchangeRate": 0.13888889,
    "rechargeAmount": 99,
    "rechargeCurrency": "CNY",
    "balanceType": "cash",
    "status": "delivered",
    "payStatus": "paid",
    "tradeNo": "2026072800019988",
    "paidAt": "2026-07-28T12:39:45.000Z",
    "contactEmail": "buyer@example.com",
    "product": {
      "id": 12,
      "name": "Qingpu Pro Monthly",
      "type": "subscription"
    },
    "attach": {
      "userId": 1024,
      "businessType": "subscription",
      "channel": "qingpu-web"
    }
  }
}

Qingpu must verify the signature, claim externalOrderId atomically, then apply the wallet or subscription mutation in the same transaction. Return a 2xx response only after that transaction commits.

Full Refund Notification

A verified full-refund gateway callback or an administrator-recorded full refund sends minimal.checkout.refunded to the original dedicated notifyUrl, with the same HMAC headers and data fields as the payment notification and data.payStatus: "refunded". APay-owned wallet orders and orders without a dedicated URL do not send this event. Refund delivery never falls back to the paid event bus. Attempts are stored separately in refundNotify; paid delivery evidence in notify is preserved. Failed gateway delivery returns 500 for retry; failed administrator delivery returns 502 after saving the refund, and saving again retries the notification. This records refund state and notifies the original site; it does not issue a gateway refund by itself.

Receivers must bind the event header to the signed body's event, match externalOrderId to the URL, and compare the original paid sourceAmount/sourceCurrency (or settlement amount/currency when absent) with their stored order. Duplicate notifications must be idempotent. Deploy receiver support before enabling sender support. Partial gateway refunds must not be reported as this full-refund event.

Retry A Failed Notification

An administrator can retry a paid relay order whose dedicated notification has not succeeded:

POST /api/admin/minimal/checkout/orders/TU20260728123456AB12CD34/retry-notify

The endpoint refuses unpaid orders, orders without a dedicated notifyUrl, and notifications already marked successful. APay-owned wallet top-ups return success without sending a notification because their credit was completed locally. Every external relay attempt updates notify.attemptCount, attemptedAt, and the latest HTTP result. The minimal checkout admin table exposes the same action for eligible failed orders.

APay Wallet Top-up Ledger

POST /api/orders/topup accepts a payment currency and positive amount. The server calculates and locks the wallet credit; clients cannot override the credit amount, accounting currency, or balance pool. These orders carry attach.walletOwner: "apay" and use three separate sources of truth:

TableResponsibility
ordersGateway payment amount, currency, and payment status
topupsTop-up lifecycle and locked payment/credit snapshots
balance_logsActual wallet mutations with topup:<orderId> and refund:<orderId> idempotency keys

The lifecycle is pending / payment_failed → paid → crediting → credited, and refunds use refunding → refunded. Failed credit becomes credit_failed; an ambiguous interrupted credit or refund becomes review_required and is never retried automatically. Only credited top-ups can mark their APay order delivered.

Users query GET /api/users/wallet/topups?page=1&pageSize=20. Administrators query GET /api/admin/topups (with status filtering and search query across order ID, email, or gateway trade no), inspect single top-up details and associated wallet mutations via GET /api/admin/topups/:id, retry safe incomplete credits via POST /api/admin/topups/retry (supporting single orderId retry or batch limit retry), or schedule POST /api/cron/reconcile-topups with Authorization: Bearer <CRON_SECRET>.

Browser Redirects

Success and cancel redirects append orderId, externalOrderId, and status. Redirects are user-experience signals only; Qingpu must use the signed server notification or signed status query as payment proof.

Free-order Completion Compatibility

Storefront checkout and the shared payment page now use POST /api/orders/complete-free. The existing administrator endpoint POST /api/admin/minimal/checkout/orders/complete-free remains a bridge-only adapter with the existing theme administrator permission. Its transport and response shape are preserved; it delegates payment claiming and fulfillment to the core implementation. Other frontend login sessions do not restrict this administrator operation. Existing notify retry endpoints and signed payloads remain unchanged.