---
title: "Minimal Checkout Relay API"
canonical_url: "https://ainode.run/docs/minimal-checkout-bridge"
type: "doc"
locale: "en"
description: "Use the minimal theme as a payment relay that records the actual charge and notifies Qingpu to perform the final recharge or business fulfillment."
---

# Minimal Checkout Relay API
> Use the minimal theme as a payment relay that records the actual charge and notifies Qingpu to perform the final recharge or business fulfillment.

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:

```http
X-APay-Timestamp: 1785312345678
X-APay-Signature:
```

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

```text
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`

```json
{
  "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"
  }
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `externalOrderId` | string | Yes | Qingpu business order ID and downstream idempotency key. |
| `productId` | number | No | Source APay product used only for validation and business context. |
| `amount` | number | Conditional | Actual amount charged by the payment gateway, including `0` for a free order. Required when `productId` is omitted. |
| `currency` | string | No | Actual payment currency. Defaults to `CNY`. |
| `sourceAmount` | number | No | Original amount before conversion. |
| `sourceCurrency` | string | No | Original/base currency before conversion. |
| `exchangeRate` | number | No | Locked rate snapshot where `amount = sourceAmount * exchangeRate`. |
| `rechargeAmount` | number | No | Amount Qingpu must credit or use for final fulfillment. |
| `rechargeCurrency` | string | No | Qingpu accounting/recharge currency. |
| `balanceType` | `cash` or `grant` | No | Target Qingpu balance pool. Defaults to `cash`. |
| `customerEmail` | string | No | Buyer contact email. |
| `notifyUrl` | string | No | Dedicated server callback URL. Defaults to the minimal checkout admin setting. |
| `returnUrl` | string | No | Browser success redirect. |
| `cancelUrl` | string | No | Browser cancel/failure redirect. |
| `productName` | string | No | Source product display snapshot. |
| `productDescription` | string | No | Source product description snapshot. |
| `productImageUrl` | string | No | Source product image snapshot. |
| `productMeta` | object | No | Trusted source product metadata snapshot. |
| `attach` | object | No | Business 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

```json
{
  "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.

```json
{
  "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"
    }
  }
}
```

## Paid Notification

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.

```http
X-APay-Event: minimal.checkout.paid
X-APay-Timestamp: 1785312345678
X-APay-Signature:
Content-Type: application/json
```

The outbound signature is:

```text
HMAC_SHA256(secret, timestamp + "\n" + raw_json_body)
```

```json
{
  "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:

```http
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:

| Table | Responsibility |
| --- | --- |
| `orders` | Gateway payment amount, currency, and payment status |
| `topups` | Top-up lifecycle and locked payment/credit snapshots |
| `balance_logs` | Actual wallet mutations with `topup:` and `refund:` 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 `.

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