退款接口（Actions API）

POST <退款接口地址>
content-type: application/json
user-agent: purser-actions/1
purser-signature: t=<unix 秒>,v1=<hex HMAC-SHA256(密钥, "<t>.<原始 body>")>
purser-idempotency-key: <幂等键>

{
  "id": "01K…",
  "type": "refund.create",
  "workspace": "<工作区 ID>",
  "createdAt": 1790000000000,
  "idempotencyKey": "<幂等键>",
  "data": {
    "actionId": "01K…",
    "orderId": "ord_2001",
    "customerId": "cus_mia",
    "lines": [{ "itemId": "li_1", "quantity": 1 }],
    "reason": "defect",
    "amount": 1599,
    "currency": "USD",
    "mode": "execute"
  }
}

{
  "type": "coupon.issue",
  "idempotencyKey": "<幂等键>",
  "data": {
    "actionId": "01K…",
    "customerId": "cus_mia",
    "orderId": "ord_2001",
    "templateRef": "tpl_sorry_10",
    "valueType": "fixed",
    "amount": 1000,
    "currency": "USD",
    "minSubtotal": null,
    "expiresAt": 1792600000000,
    "reason": "包裹晚到 5 天"
  }
}

{ "type": "points.grant", "idempotencyKey": "<幂等键>",
  "data": { "actionId": "01K…", "customerId": "cus_mia", "orderId": "ord_2001", "points": 300, "reason": "包裹晚到 5 天" } }

{ "type": "order.update_address", "idempotencyKey": "<幂等键>",
  "data": { "actionId": "01K…", "orderId": "ord_2001", "customerId": "cus_mia", "reason": "顾客搬家了",
            "address": { "name": "Mia", "line1": "9 New Ave", "line2": "Apt 3", "city": "Austin",
                         "province": "TX", "postalCode": "78701", "country": "US", "phone": "+1 512 555 0100" } } }

{ "type": "order.cancel", "idempotencyKey": "<幂等键>",
  "data": { "actionId": "01K…", "orderId": "ord_2001", "customerId": "cus_mia", "reason": "重复下单" } }

import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

function verifyPurserSignature(secret, rawBody, header, nowS = Math.floor(Date.now() / 1000)) {
  if (!secret || !header) return false;
  const parts = Object.fromEntries(
    header.split(",").map((p) => {
      const i = p.indexOf("=");
      return [p.slice(0, i).trim(), p.slice(i + 1).trim()];
    }),
  );
  const t = Number(parts.t);
  if (!Number.isFinite(t) || Math.abs(nowS - t) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const given = String(parts.v1 ?? "");
  return given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

const app = express();

// 用 text() 拿原始 body，验签之后再解析
app.post("/purser/actions", express.text({ type: "application/json" }), async (req, res) => {
  if (!verifyPurserSignature(process.env.PURSER_ACTIONS_SECRET, req.body, req.get("purser-signature"))) {
    return res.status(401).json({ ok: false, code: "bad_signature" });
  }
  const delivery = JSON.parse(req.body);
  const { type, idempotencyKey, data } = delivery;
  try {
    if (type === "ping") return res.json({ ok: true });
    if (type === "refund.preview") {
      const order = await db.orders.get(data.orderId);
      if (order.finalSale) return res.json({ ok: false, code: "final_sale", message: "Final sale" });
      return res.json({ ok: true, amount: order.total, currency: order.currency });
    }
    if (type === "refund.create") {
      // 同一个幂等键只退一次
      const done = await db.refunds.findByKey(idempotencyKey);
      if (done) return res.json({ ok: true, status: "succeeded", refundId: done.id });
      const refundId = await refundOrder(data.orderId, data.amount, data.currency, idempotencyKey);
      await db.refunds.save({ key: idempotencyKey, id: refundId });
      return res.json({ ok: true, status: "succeeded", refundId });
    }
    return res.status(400).json({ ok: false, code: "unknown_type" });
  } catch (e) {
    // 5xx = 让 purser 稍后用同一个幂等键重试
    return res.status(500).json({ ok: false, code: "error" });
  }
});

curl -X POST https://askpurser.com/api/v1/actions/$ACTION_ID/status \
  -H "Authorization: Bearer $PURSER_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "succeeded", "refundId": "re_123" }'

import { actionsHandler } from "@purser-ai/node";

const handle = actionsHandler({
  secret: process.env.PURSER_ACTIONS_SECRET,
  refund: {
    // 只计算，不动钱。金额用最小货币单位。
    async preview({ orderId, lines, reason }) {
      const order = await db.orders.get(orderId);
      if (order.finalSale) return { refused: "final_sale", message: "Final sale" };
      return { amount: order.total, currency: order.currency };
    },
    // 真退款。同一个 idempotencyKey 只能退一次。
    async create({ orderId, amount, currency, idempotencyKey, mode }) {
      const done = await db.refunds.findByKey(idempotencyKey);
      if (done) return { status: "succeeded", refundId: done.id };
      const refundId = await refundOrder(orderId, amount, currency, idempotencyKey);
      await db.refunds.save({ key: idempotencyKey, id: refundId });
      return { status: "succeeded", refundId };
    },
  },
});

// Cloudflare Workers / Bun / Deno / Hono 这类 fetch 风格的服务器：
export default { fetch: (request) => handle(request) };

actionsHandler({
  secret: process.env.PURSER_ACTIONS_SECRET,
  coupon: { async issue({ idempotencyKey, customerId, amount }) { return { code: await makeCode(idempotencyKey) }; } },
  points: { async grant({ customerId, points, idempotencyKey }) { return { balance: await addPoints(customerId, points, idempotencyKey) }; } },
  order: {
    async updateAddress({ orderId, address }) { await shipTo(orderId, address); return {}; },
    async cancel({ orderId }) { await cancelAndRefund(orderId); return {}; },
  },
});